Skip to main content

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>

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

  2. @method <metadata>

    3. 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>

    5. 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

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

  2. accessor

    3. 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

    4. 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

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

  2. no_in

    3. 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

    4. 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

    5. 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

    6. 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

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

  7. struct

    8. 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

    9. 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

    10. 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

    11. 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

    12. 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

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

  13. address

    14. 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

    15. 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

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

  16. new

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

  17. delete

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

  18. gcnew

    19. 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

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

  20. setter

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

  21. getter

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

  22. adder

    23. 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

Back to the top