jnigen_metadata.php

<?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>&lt;metadata&gt;</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>&lt;metadata&gt;</tt> </li>

	<p>Annotates a native method.</p></li>

<li> <b>@param</b> <tt>&lt;name&gt; &lt;metadata&gt;</tt>

	<p>Annotates a parameter of a native method. The parameter is identified by its name.</p></li>

<li> <b>@field</b> <tt>&lt;metadata&gt;</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 &lt;<b>,</b>&gt;. </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&lt;PrimitiveType&gt;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 &amp;. 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);
?>