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.

  3. @method <metadata>
  4. Annotates a native method.

  5. @param <name> <metadata>

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

  6. @field <metadata>
  7. 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.

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

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

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

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

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

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

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

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

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

  17. sentinel
  18. 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

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

  21. cast
  22. 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

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

  25. address
  26. 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

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

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

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

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

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

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

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

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

  43. adder
  44. 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