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

@jniclass<metadata>

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

@method<metadata>

Annotates a native method.

@param<name> <metadata>

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

@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

cast

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

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.

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

no_gen

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

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

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

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

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

init

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

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

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

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

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

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

jni

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

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

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

cpp

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

new

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

delete

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

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

gcobject

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

setter

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

getter

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

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