| <?php require_once($_SERVER['DOCUMENT_ROOT'] . "/eclipse.org-common/system/app.class.php"); require_once($_SERVER['DOCUMENT_ROOT'] . "/eclipse.org-common/system/nav.class.php"); require_once($_SERVER['DOCUMENT_ROOT'] . "/eclipse.org-common/system/menu.class.php"); $App = new App(); $Nav = new Nav(); $Menu = new Menu(); include($App->getProjectCommon()); |
| |
| $pageTitle = "SWT JNIGen Tool Metadata"; |
| |
| ob_start(); |
| ?> |
| <div id="midcolumn"> |
| <h1>SWT JNI Tool Meta Data</h1> |
| |
| <p>All of the C code used by SWT is generated by the <b>JNIGeneratorApp</b> |
| application included in the SWT Tools bundle and available on the |
| <a href="updatesite.php">SWT Tools Update Sites</a>. |
| |
| 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. </p> |
| |
| |
| <h3> Tags </h3> |
| |
| <ol> |
| <li> <b>@jniclass</b> <tt><metadata></tt></li> |
| |
| <p>Annotates a class. Classes can be either a structure class or a main class that contains natives.</p> |
| |
| <li> <b>@method</b> <tt><metadata></tt> </li> |
| |
| <p>Annotates a native method.</p></li> |
| |
| <li> <b>@param</b> <tt><name> <metadata></tt> |
| |
| <p>Annotates a parameter of a native method. The parameter is identified by its name.</p></li> |
| |
| <li> <b>@field</b> <tt><metadata></tt></li> |
| |
| <p>Annotates a field of a structure class.</p> |
| </ol> |
| |
| <h3> Metadata </h3> |
| |
| <p> The metadata is a comma separated list of attributes of the form <i>key=value</i>. For example: |
| |
| <p><b>cast=(HWND),flags=flag1 flag2,accessor=othername</b></p> |
| |
| The key or value must not contain the comma character <<b>,</b>>. </p> |
| |
| |
| <h3> Attributes </h3> |
| <ol> |
| <li> <b>cast</b></li> |
| <p>Provide the C cast of a structure field <i>@field</i> or native method parameter <i>@param</i>.</p> |
| <li> <b>accessor</b></li> |
| <p>Provide the C, C# or C++ name/identifier to be used instead of the java name. This can be used by structure fields <i>@field</i> or native methods <i>@method</i>.</p> |
| <li> <b>flags</b></li> |
| <p>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.</p> |
| </ol> |
| |
| |
| <h3> Flags </h3> |
| |
| |
| <ol> |
| <li> <b>no_gen</b></li> |
| <p>Indicate that the item should not be generated. For example, custom natives are coded by hand. Used in: <i>@jniclass</i>, <i>@method</i>, <i>@field</i></p> |
| <li> <b>no_in</b></li> |
| <p>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: <i>@param</i></p> |
| <li> <b>no_out</b></li> |
| <p>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: <i>@param</i></p> |
| <li> <b>critical</b></li> |
| <p>Indicate that <tt>GetPrimitiveArrayCritical()</tt> should be used instead of <tt>Get<PrimitiveType>ArrayElements()</tt> 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 <tt>MoveMemory()</tt> and <tt>memmove()</tt> natives. Used in: <i>@param</i><p> |
| <li> <b>dynamic</b></li> |
| <p>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: <i>@method</i><p> |
| <li> <b>init</b></li> |
| <p>Indicate that the associated C local variable for a native method parameter should be initialized with zeros. Used in: <i>@param</i></p> |
| <li> <b>struct</b></li> |
| <p>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: <i>@param</i></p> |
| <li> <b>unicode</b></li> |
| <p>Indicate that <tt>GetStringChars()</tt>should be used instead of <tt>GetStringUTFChars()</tt> to get the characters of a java.lang.String passed as a parameter to native methods. Used in: <i>@param</i></p> |
| <li> <b>sentinel</b></li> |
| <p>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 <tt>NULL</tt>. Some compilers expect the sentinel to be the literal <tt>NULL</tt> and output a warning if otherwise. Used in: <i>@param</i></p> |
| <li> <b>const</b></li> |
| <p>Indicate that the native method represents a constant or global variable instead of a function. This omits <tt>()</tt> from the generated code. Used in: <i>@method</i></p> |
| <li> <b>cast</b></li> |
| <p>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: <i>@method</i></p> |
| <li> <b>jni</b></li> |
| <p>Indicate that the native is part of the Java Native Interface. For example: <tt>NewGlobalRef()</tt>. Used in: <i>@method</i></p> |
| <li> <b>address</b></li> |
| <p>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: <i>@method</i></p> |
| <li> <b>no_wince</b></li> |
| <p>Indicate that the item should be #ifdef out in the Windows CE platform, but not in the regular win32 platform. Used in: <i>@field</i></p> |
| <li> <b>cpp</b></li> |
| <p>Indicate that the platform source is in C++. Used in: <i>@jniclass</i>, <i>@method</i></p> |
| <li> <b>new</b></li> |
| <p>Indicate that the native method is a C++ constructor that allocates an object on the heap. Used in: <i>@method</i></p> |
| <li> <b>delete</b></li> |
| <p>Indicate that the native method is a C++ destructor that deallocates an object from the heap. Used in: <i>@method</i></p> |
| <li> <b>gcnew</b></li> |
| <p>Indicate that the native method is a C# constructor that allocates an object on the managed (i.e. garbage collected) heap. Used in: <i>@method</i></p> |
| <li> <b>gcobject</b></li> |
| <p>Indicate that the native method's return value or parameter is a C# managed object. Used in: <i>@method</i>, <i>@param</i></p> |
| <li> <b>setter</b></li> |
| <p>Indicate that the native method represents a setter for a field in an object or structure. Used in: <i>@method</i></p> |
| <li> <b>getter</b></li> |
| <p>Indicate that the native method represents a getter for a field in an object or structure. Used in: <i>@method</i></p> |
| <li> <b>adder</b></li> |
| <p>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: <i>@method</i></p> |
| </ol> |
| |
| </div> |
| <?php |
| $html = ob_get_clean(); |
| |
| # Generate the web page |
| $App->generatePage($theme, $Menu, $Nav, $pageAuthor, $pageKeywords, $pageTitle, $html); |
| ?> |