SWT JNI Tool Meta Data

All of the C code used by SWT is generated by the JNIGeneratorApp application included in the SWT Tools bundle and available on the SWT Tools Update Sites. This page describes the metadata used to annotate the native methods and structures to help the tool generate the appropriate C code. This metadata is provide in the form of tags in the java doc comment.

Tags

1. @jniclass <metadata>

   Annotates a class. Classes can be either a structure class or a main class that contains natives.

2. @method <metadata>

   Annotates a native method.

3. @param <name> <metadata>

   Annotates a parameter of a native method. The parameter is identified by its name.

4. @field <metadata>

   Annotates a field of a structure class.

Metadata

The metadata is a comma separated list of attributes of the form key=value. For example:

cast=(HWND),flags=flag1 flag2,accessor=othername

The key or value must not contain the comma character <,>.

Attributes

1. cast

   Provide the C cast of a structure field @field or native method parameter @param.

2. accessor

   Provide the C, C# or C++ name/identifier to be used instead of the java name. This can be used by structure fields @field or native methods @method.

3. flags

   Provide switches to control how the C code is generated. Any tag may have this attribute. Multiple flags are separated by a space character. See below for a list of the known flags.

Flags

1. no_gen

   Indicate that the item should not be generated. For example, custom natives are coded by hand.
   Used in: @jniclass, @method, @field

2. no_in

   Indicate that a native method parameter is an out only variable. This only makes sense if the parameter is a structure or an array of primitives. It is an optimization to avoid copying the java memory to C memory on the way in.
   Used in: @param

3. no_out

   Indicate that a native method parameter is an in only variable. This only makes sense if the parameter is a structure or an array of primitives. It is an optimization to avoid copying the C memory from java memory on the way out.
   Used in: @param

4. critical

   Indicate that GetPrimitiveArrayCritical() should be used instead of Get<PrimitiveType>ArrayElements() when transferring array of primitives from/to C. This is an optimization to avoid copying memory and must be used carefully. It is ok to be used in MoveMemory() and memmove() natives.
   Used in: @param

5. dynamic

   Indicate that a native method should be looked up dynamically. It is useful when having a dependence on a given library is not desirable. The library name is specified in the *_custom.h file.
   Used in: @method

6. init

   Indicate that the associated C local variable for a native method parameter should be initialized with zeros.
   Used in: @param

7. struct

   Indicate that a structure parameter should be passed by value instead of by reference. This dereferences the parameter by prepending *. The parameter must not be NULL.
   Used in: @param

8. unicode

   Indicate that GetStringChars() should be used instead of GetStringUTFChars() to get the characters of a java.lang.String passed as a parameter to native methods.
   Used in: @param

9. sentinel

   Indicate that the parameter of a native method is the sentinel (last parameter of a variable argument C function). The generated code is always the literal NULL. Some compilers expect the sentinel to be the literal NULL and output a warning if otherwise.
   Used in: @param

10. const

    Indicate that the native method represents a constant or global variable instead of a function. This omits () from the generated code.
    Used in: @method

11. cast

    Indicate that the C function should be casted to a prototype generated from the parameters of the native method. Useful for variable argument C functions.
    Used in: @method

12. jni

    Indicate that the native is part of the Java Native Interface. For example: NewGlobalRef().
    Used in: @method

13. address

    Indicate that the native method represents a structure global variable and the address of it should be returned to Java. This is done by prepending &.
    Used in: @method

14. no_wince

    Indicate that the item should be #ifdef out in the Windows CE platform, but not in the regular win32 platform.
    Used in: @field

15. cpp

    Indicate that the platform source is in C++.
    Used in: @jniclass, @method

16. new

    Indicate that the native method is a C++ constructor that allocates an object on the heap.
    Used in: @method

17. delete

    Indicate that the native method is a C++ destructor that deallocates an object from the heap.
    Used in: @method

18. gcnew

    Indicate that the native method is a C# constructor that allocates an object on the managed (i.e. garbage collected) heap.
    Used in: @method

19. gcobject

    Indicate that the native method's return value or parameter is a C# managed object.
    Used in: @method, @param

20. setter

    Indicate that the native method represents a setter for a field in an object or structure.
    Used in: @method

21. getter

    Indicate that the native method represents a getter for a field in an object or structure.
    Used in: @method

22. adder

    Indicate that the native method takes 2 arguments, a collection and an item, and the += operator is used to add the item to the collection.
    Used in: @method