** implies *native ownership* for a *Pointer* referenced *native* memory
if the expression is constant. Otherwise the *native* memory has *java ownership*.
See [ReturnedArrayLength Setting](#returnedarraylength-symbol-expression) below.
* Utilizing a *flexible* *elemCount* via **ReturnedArrayLength getValElements()** renders us unable to determine ownership
of pointer referenced *native* memory segment and hence renders ownership *mixed or ambiguous*, [see \[5\]](#signature-const-int32_t--customsize-ambiguous-java-owned). This is due to the fact, that native code may allocate memory and writes its *elemCount* into the designated field *valElements*. In such cases, the user being aware of the underlying API shall utilize `setVal(..)` and `releaseVal()` with care.
* To release native memory with *java ownership*, i.e. a native ByteBuffer, `releaseVal()` can be used.
### GlueGen Struct Settings
#### **Opaque** *Java-primitive-type* *symbol*
See also [Opaque section in manual](manual/index.html#SecOpaque).
* `Opaque long T2_UndefStruct*`
Pointers to `T2_UndefStruct` will be handled opaque,
i.e. as `long` values from the Java side while maintaining their architecture dependent pointer size within native memory.
#### **ImmutableAccess** *symbol*
Immutable access can be set for a whole struct or a single field of a struct.
Immutable access will simply suppress generating setters in the Java code
and hence also reduces the footprint of the generated Java class for such struct.
* `ImmutableAccess TK_Struct`
Immutable access for the whole struct `TK_Struct
Sets pseudo-code flag *ImmutableAccess*, see below.
* `ImmutableAccess TK_Struct.val`
Immutable access for the single field `val` within struct `TK_Struct`
Sets pseudo-code flag *ImmutableAccess*, see below.
#### **MaxOneElement** *symbol*
* `MaxOneElement TK_Struct.val`
Sets field pointer `val`
to point to a array with a maximum of one element and unset initial value (zero elements).
Sets pseudo-code flag *MaxOneElement*, see below.
#### **ReturnedArrayLength** *symbol* *expression*
* `ReturnedArrayLength TK_Struct.val 3`
Sets field pointer `val` to point to a array with three elements.
Sets pseudo-code flag *ConstElemCount*, see below.
Having set *ConstElemCount* also implies *native ownership* for a *Pointer* referenced *native* memory.
* `ReturnedArrayLength TK_Struct.val 1`
Sets field pointer `val` to point to a array with one element.
Sets pseudo-code flags *ConstElemCount* and *MaxOneElement*, see below.
Having set *ConstElemCount* also implies *native ownership* for a *Pointer* referenced *native* memory.
* `ReturnedArrayLength TK_Struct.val getValElements()`
Sets field pointer `val` to point to a array with a variable length as described by the
field `valElements` retrievable via its getter `getValElements()`.
Sets pseudo-code flag *VariaElemCount*, see below.
#### **ReturnsString** *symbol*
A direct C code `char` array or indirect array via pointer can be interpreted as a Java `String`.
* `ReturnsString TK_Struct.name`
Sets field char-array or char-pointer `name` to be additionally interpreted as a Java `String`.
Besides the `byte[]` and `ByteBuffer` getter and setter variants, a `String` variant will be added.
Sets pseudo-code flags *String*, see below.
See [*String Mapping*](#string-mapping) above.
#### **ReturnsStringOnly** *symbol*
* `ReturnsStringOnly TK_Struct.name`
Sets field char-array or char-pointer `name` to be exclusively interpreted as a Java `String`.
Instead of the `byte[]` and `ByteBuffer` getter and setter variants, a `String` variant will be produced.
Sets pseudo-code flags *StringOnly*, see below.
See [*String Mapping*](#string-mapping) above.
### Struct Setter Pseudo-Code
#### Overview
In general we have the following few cases
* Array owned by parent struct itself
* `int32_t val[10]`
* Setter of `val` within range, keeping memory
* `const int32_t val[10]`
* No setter allowed due to const value
* Referenced Memory (array) owned by Java
* `int32_t* val`
* Setter within range, keeping memory, or replacing memory
* `const int32_t* val`
* Setter replacing memory, since memory is non-const but value is const
* Referenced Memory (array) owned by Native Code due to set *ConstElemCount*
* `int32_t* val`
* Setter of `val` within range, keeping memory owned by native code
* `const int32_t* val`
* No setter allowed, since memory is owned by native code and value is const
#### Implemented Pseudo Code
* *ImmutableAccess*: Drops setter, immutable
* *Pointer* & *ConstValue* & *ConstElemCount*: Drops setter, native ownership on const-value
* *Array* & *ConstValue* : Drops setter, const-value array
* *Primitive*
* Single aggregated instance
* Store value within *native* memory
* *Array* | *Pointer*
* *MaxOneElement*
* *Pointer*
* *ConstValue*: Allocate new memory and store value
* *VariaValue*:
* *ConstElemCount*: Reuse *native* memory and store value with matching *elemCount 1*, otherwise Exception
* *VariaElemCount*: Reuse *native* memory and store value with matching *elemCount 1*, otherwise allocates new memory (had *elemCount 0*)
* *Array* & *VariaValue*: Reuse *native* memory and store value (has const *elemCount 1*)
* *else*: *SKIP* setter for const single-primitive array
* *AnyElementCount*
* *String* & *isByteBuffer* & *Pointer*
* *ConstElemCount*: Reuse *native* memory and store UTF-8 bytes with EOS with matching *elemCount*, otherwise Exception
* *StringOnly*: End, no more setter for this field, otherwise continue
* *VariaElemCount*: Allocate new *native* memory and store UTF-8 bytes with EOS
* *StringOnly*: End, no more setter for this field, otherwise continue
* *ConstValue*
* *Pointer*
* *VariaElemCount*: Allocates new *native* memory and store value
* *else*: *SKIP* setter for const primitive array
* *Array* | *ConstElemCount*: Reuse *native* memory and store value with <= *elemCount*, otherwise Exception
* *Pointer* & *VariaElemCount*: Reuse *native* memory and store value with <= *elemCount*, otherwise allocate new *native* memory
* *Struct* ...
### Struct Java Signature Table
Please find below signature table as generated by the *C Declaration* including its *C Modifier*,
e.g. `const` for constant, `[const]` for const and non-const and `empty` for non-const (variable).
Further, the *GlueGen Setting* (see above) impacts the code generation as well.
Below table demonstrates *primitive* types being mapped within a `struct` named `TK_Struct`.
A similar mapping is produced for `struct` types, i.e. *compounds*.
| C Mod | C Declaration | Java Setter | Java Getter | GlueGen Setting | Ownership | Remarks |
|:--------|:--------------|:-----------------------------------------------------------------|:--------------------------------------|:-----------------------------------------------|:----------|:----------|
| | | | static boolean usesNativeCode() | | | Java, static,
*true* if using native code |
| | | | static int size() | | | Java, static,
native size in bytes |
| | | | static TK_Struct create() | | | Java, static ctor |
| | | | static TK_Struct create(ByteBuffer) | | | Java, static ctor
w/ existing ByteBuffer |
| | | | static TK_Struct derefPointer(long addr) | | | Java, static ctor
dereferencing ByteBuffer
at native address of size() |
| | | | ByteBuffer getBuffer() | | | Java,
underlying ByteBuffer |
| | | | long getDirectBufferAddress() | | | Java, native address
of underlying getBuffer() |
| | int32_t val | setVal(int v) | int getVal() | | Parent | |
| const | int32_t val | *none* | int getVal() | | Parent | Read only |
| | int32_t val | *none* | int getVal() | **ImmutableAccess** | Parent | Read only |
| [const] | int32_t* val | setVal(int v) \[[1](#signature-int32_t--maxoneelement-java-owned)\]\[[2](#signature-const-int32_t--maxoneelement-java-owned)\]
releaseVal() | int getVal()
boolean isValNull()
int getValElemCount() | **MaxOneElement** | Java | Starts w/ null elements,
max 1 element |
| const | int32_t* val | *none* | int getVal()
boolean isValNull()
static int getValElemCount() | **ReturnedArrayLength 1** | Native | Const element count 1 |
| | int32_t* val | setVal(int v) | int getVal()
boolean isValNull()
static int getValElemCount() | **ReturnedArrayLength 1** | Native | Const element count 1 | |
| | int32_t val[3]| setVal(int[] src, int srcPos, int destPos, int len) \[[3](#signature-int32_t3-constelemcount-3-parent-owned)\] | IntBuffer getVal()
int[] getVal(int srcPos, int[] dest, int destPos, int len) | | Parent | Reuses parent memory,
fixed size. |
| const | int32_t val[3]| *none* | IntBuffer getVal()
int[] getVal(int srcPos, int[] dest, int destPos, int len) | | Parent | Read only |
| const | int32_t* val | *none* | IntBuffer getVal()
int[] getVal(int srcPos, int[] dest, int destPos, int len)
boolean isValNull()
static int getValElemCount() | **ReturnedArrayLength 3** | Native | Read only
Const element count 3 |
| | int32_t* val | setVal(int[] src, int srcPos, int destPos, int len) \[[4](#signature-int32_t--constelemcount-3-natively-owned)\] | IntBuffer getVal()
int[] getVal(int srcPos, int[] dest, int destPos, int len)
boolean isValNull()
static int getValElemCount() | **ReturnedArrayLength 3** | Native | Const element count 3.
Reuses native memory,
fixed size. |
| | int32_t* val | setVal(boolean subset, int[] src, int srcPos, int destPos, int len) \[[5](#signature-int32_t--freesize-java-owned)\]
releaseVal() | IntBuffer getVal()
int[] getVal(int srcPos, int[] dest, int destPos, int len)
boolean isValNull()
int getValElemCount() | | Java | Starts w/ null elements.
Reuses or replaces Java memory,
variable size. |
| const | int32_t* val | setVal(int[] src, int srcPos, int len) \[[6](#signature-const-int32_t--freesize-java-owned)\]
releaseVal() | IntBuffer getVal()
int[] getVal(int srcPos, int[] dest, int destPos, int len)
boolean isValNull()
int getValElemCount() | | Java | Starts w/ null elements.
Replaces Java memory,
variable size. |
| | int32_t* val | setVal(boolean subset, int[] src, int srcPos, int destPos, int len) \[[7](#signature-int32_t--customsize-ambiguous-ownership)\]
releaseVal() | IntBuffer getVal()
int[] getVal(int srcPos, int[] dest, int destPos, int len)
boolean isValNull() | **ReturnedArrayLength getValCount()** | **Ambiguous** | Variable element count
using field *valCount*,
which has getter and setter |
| const | int32_t* val | setVal(int[] src, int srcPos, int len) \[[8](#signature-const-int32_t--customsize-ambiguous-ownership)\]
releaseVal() | IntBuffer getVal()
int[] getVal(int srcPos, int[] dest, int destPos, int len)
boolean isValNull() | **ReturnedArrayLength getValCount()** | **Ambiguous** | Variable element count
using field *valCount*,
which has getter and setter |
| [const] | char* name | setName(String srcVal)
releaseVal() | String getName()
boolean isNameNull()
int getNameElemCount() | **ReturnsStringOnly** | Java | String only, w/ EOS |
| [const] | char* name | setName(String srcVal)
setName(byte[] src, int srcPos, int destPos, int len)
releaseVal() | String getNameAsString()
ByteBuffer getName()
boolean isNameNull()
int getNameElemCount() | **ReturnsString** | Java | String and byte access, w/ EOS|
### Struct Java Signature Examples
#### Signature `int32_t *` MaxOneElement, Java owned
* `void com.jogamp.gluegen.test.junit.generation.TK_Field.setVariaInt32PointerMaxOneElemElemCount(int src)`
Setter for native field variaInt32PointerMaxOneElem, referencing a Java owned array with variable element count of 0 initial elements.
Maximum element count is 1.
Native Signature:
* field-type (PointerType) 'int32_t *' -> (int32_t) * , size [fixed false, lnx64 8], const[false], pointer*1
* referenced (IntType) typedef 'int32_t', size [fixed true, lnx64 4], const[false], int
Will reuse memory if existing, otherwise allocating memory.
#### Signature `const int32_t *` MaxOneElement, Java owned
* `TK_Field com.jogamp.gluegen.test.junit.generation.TK_Field.setConstInt32PointerMaxOneElem(int src)`
Setter for native field variaInt32PointerMaxOneElem, referencing a Java owned array with variable element count of 0 initial elements.
Maximum element count is 1.
Native Signature:
* field-type (PointerType) 'int32_t *' -> (const int32_t) * , size [fixed false, lnx64 8], const[false], pointer*1
* referenced (IntType) typedef 'int32_t', size [fixed true, lnx64 4], const[native, true], int
Always replaces memory due to `const` value modifier.
#### Signature `int32_t[3]` ConstElemCount 3, Parent owned
* `TK_Field com.jogamp.gluegen.test.junit.generation.TK_Field.setVariaInt32ArrayConstLen(int[] src, int srcPos, int destPos, int length)`
Setter for native field variaInt32ArrayConstLen, being an array with fixed element count of 3 elements.
Native Field Signature (ArrayType) 'int32_t *', size [fixed false, lnx64 12], const[false], array*1
Copies the given source elements into the respective field's existing memory.
Parameters:
* src the source array of elements
* srcPos starting element position within the source array with 'srcPos >= 0` && `srcPos + length <= src.length`, otherwise an IndexOutOfBoundsException is thrown
* destPos starting element position within the destination with 'destPos >= 0` && `destPos + length <= elemCount`, otherwise an exception is thrown
* length the element count to be copied with 'length >= 0` && `srcPos + length <= src.length` && `destPos + length <= elemCount`, otherwise an IndexOutOfBoundsException is thrown
Returns:
* this instance of chaining
#### Signature `int32_t *` ConstElemCount 3, Natively owned
* `TK_Field com.jogamp.gluegen.test.junit.generation.TK_Field.setVariaInt32PointerConstLen(int[] src, int srcPos, int destPos, int length)`
Setter for native field variaInt32PointerConstLen, referencing a natively owned array with fixed element count of 3 elements.
Native Signature:
* field-type (PointerType) 'int32_t *' -> (int32_t) * , size [fixed false, lnx64 8], const[false], pointer*1
* referenced (IntType) typedef 'int32_t', size [fixed true, lnx64 4], const[false], int
Copies the given source elements into the respective field's existing memory.
Parameters:
* src the source array of elements
* srcPos starting element position within the source array with 'srcPos >= 0` && `srcPos + length <= src.length`, otherwise an IndexOutOfBoundsException is thrown
* destPos starting element position within the destination with 'destPos >= 0` && `destPos + length <= elemCount`, otherwise an exception is thrown
* length the element count to be copied with 'length >= 0` && `srcPos + length <= src.length` && `destPos + length <= elemCount`, otherwise an IndexOutOfBoundsException is thrown
Returns:
* this instance of chaining
#### Signature `int32_t *` FreeSize, Java owned
* `TK_Field com.jogamp.gluegen.test.junit.generation.TK_Field.setVariaInt32PointerVariaLen(boolean subset, int[] src, int srcPos, int destPos, int length)`
Setter for native field variaInt32PointerVariaLen, referencing a Java owned array with variable element count of 0 initial elements.
Native Signature:
* field-type (PointerType) 'int32_t *' -> (int32_t) * , size [fixed false, lnx64 8], const[false], pointer*1
* referenced (IntType) typedef 'int32_t', size [fixed true, lnx64 4], const[false], int
Copies the given source elements into the respective field, either writing into the existing memory or creating a new memory and referencing it.
Parameters:
* subset if `true` keeps the underlying memory and only allows to set up to `elemCount` elements. Otherwise may replace the underlying memory if `destPos + length != elemCount`.
* src the source array of elements
* srcPos starting element position within the source array with 'srcPos >= 0` && `srcPos + length <= src.length`, otherwise an IndexOutOfBoundsException is thrown
* destPos starting element position within the destination with 'destPos >= 0`. If `subset == true`, `destPos + length <= elemCount` also must be be `true`. Otherwise an exception is thrown
* length the element count to be copied with 'length >= 0` && `srcPos + length <= src.length`, otherwise an IndexOutOfBoundsException is thrown
Returns:
* this instance of chaining
#### Signature `const int32_t *` FreeSize, Java owned
* `TK_Field com.jogamp.gluegen.test.junit.generation.TK_Field.setConstInt32PointerVariaLen(int[] src, int srcPos, int length)`
Setter for native field constInt32PointerVariaLen, referencing a Java owned array with variable element count of 0 initial elements.
Native Signature:
* field-type (PointerType) 'int32_t *' -> (const int32_t) * , size [fixed false, lnx64 8], const[false], pointer*1
* referenced (IntType) typedef 'int32_t', size [fixed true, lnx64 4], const[native, true], int
Replaces the respective field's memory with a new memory segment containing given source elements and referencing it.
Parameters:
* src the source array of elements
* srcPos starting element position within the source array with 'srcPos >= 0` && `srcPos + length <= src.length`, otherwise an IndexOutOfBoundsException is thrown
* length the element count to be copied with 'length >= 0` && `srcPos + length <= src.length`, otherwise an IndexOutOfBoundsException is thrown
Returns:
* this instance of chaining
#### Signature `int32_t *` CustomSize, Ambiguous ownership
* `TK_Field com.jogamp.gluegen.test.junit.generation.TK_Field.setVariaInt32PointerCustomLen(boolean subset, int[] src, int srcPos, int destPos, int length)`
Setter for native field variaInt32PointerCustomLen, referencing a mixed and ambigously owned (warning) array with variable element count of getVariaInt32PointerCustomLenElemCount() elements.
Native Signature:
* field-type (PointerType) 'int32_t *' -> (int32_t) * , size [fixed false, lnx64 8], const[false], pointer*1
* referenced (IntType) typedef 'int32_t', size [fixed true, lnx64 4], const[false], int
Copies the given source elements into the respective field, either writing into the existing memory or creating a new memory and referencing it.
Parameters:
* subset if `true` keeps the underlying memory and only allows to set up to `elemCount` elements. Otherwise may replace the underlying memory if `destPos + length != elemCount`.
* src the source array of elements
* srcPos starting element position within the source array with 'srcPos >= 0` && `srcPos + length <= src.length`, otherwise an IndexOutOfBoundsException is thrown
* destPos starting element position within the destination with 'destPos >= 0`. If `subset == true`, `destPos + length <= elemCount` also must be be `true`. Otherwise an exception is thrown
* length the element count to be copied with 'length >= 0` && `srcPos + length <= src.length`, otherwise an IndexOutOfBoundsException is thrown
Returns:
* this instance of chaining
#### Signature `const int32_t *` CustomSize, Ambiguous ownership
* `TK_Field com.jogamp.gluegen.test.junit.generation.TK_Field.setConstInt32PointerCustomLen(int[] src, int srcPos, int length)`
Setter for native field constIntxxPointerCustomLen, referencing a mixed and ambigously owned (**warning**) array with variable element count of getConstIntxxPointerCustomLenElemCount() elements.
Native Signature:
* field-type (PointerType) 'int32_t *' -> (const int32_t) * , size [fixed false, lnx64 8], const[false], pointer*1
* referenced (IntType) typedef 'int32_t', size [fixed true, lnx64 4], const[native, true], int
Replaces the respective field's memory with a new memory segment containing given source elements and referencing it.
Parameters:
* src the source array of elements
* srcPos starting element position within the source array with 'srcPos >= 0` && `srcPos + length <= src.length`, otherwise an IndexOutOfBoundsException is thrown
* length the element count to be copied with 'length >= 0` && `srcPos + length <= src.length`, otherwise an IndexOutOfBoundsException is thrown
Returns:
* this instance of chaining
### Struct Pointer-Pointer Support
See primitive [*Pointer Mapping*](#pointer-mapping) above.
*Pointer* are exposed in the following examples
```
typedef struct {
int32_t* int32PtrArray[10];
int32_t** int32PtrPtr;
...
} T2_PointerStorage;
```
or via and undefined forward-declared struct
```
typedef struct T2_UndefStruct* T2_UndefStructPtr;
typedef struct {
...
T2_UndefStructPtr undefStructPtr;
T2_UndefStructPtr undefStructPtrArray[10];
T2_UndefStructPtr* undefStructPtrPtr;
const T2_UndefStructPtr* constUndefStructPtrPtr;
} T2_PointerStorage;
```
and the following GlueGen configuration
```
Opaque long T2_UndefStruct*
Ignore T2_UndefStruct
```
*TODO: Enhance documentation*
### Struct Function-Pointer Support
GlueGen supports function pointers as struct fields,
generating function calls as methods as well function-pointer opaque getter and setter as `long` types.
The latter only in case if mutable, i.e. non-const.
#### Example
Assume the following C Header file example:
```
typedef struct {
int32_t balance;
} T2_UserData;
typedef int32_t ( * T2_CustomFuncA)(void* aptr);
typedef int32_t ( * T2_CustomFuncB)(T2_UserData* pUserData);
typedef struct {
...
T2_CustomFuncA customFuncAVariantsArray[10];
T2_CustomFuncA* customFuncAVariantsArrayPtr;
T2_CustomFuncB customFuncBVariantsArray[10];
T2_CustomFuncB* customFuncBVariantsArrayPtr;
} T2_PointerStorage;
typedef struct {
...
const T2_CustomFuncA CustomFuncA1;
T2_CustomFuncB CustomFuncB1;
} T2_InitializeOptions;
```
and the following GlueGen configuration
```
Opaque long void*
EmitStruct T2_UserData
StructPackage T2_UserData com.jogamp.gluegen.test.junit.generation
EmitStruct T2_InitializeOptions
StructPackage T2_InitializeOptions com.jogamp.gluegen.test.junit.generation
```
This will lead to the following result for `const T2_CustomFuncA customFuncA1`
```
/**
* Getter for native field CustomFuncA1, being a struct owned function pointer.
*
* Native Field Signature (PointerType) typedef 'T2_CustomFuncA' -> int32_t (*)(void * aptr), size [fixed false, lnx64 8], const[false], pointer*1, funcPointer
*
*/
public final long getCustomFuncA1() { .. }
/** Interface to C language function:
int32_t CustomFuncA1(void * aptr)
*/
public final int CustomFuncA1(long aptr) { ... }
```
and similar to `T2_CustomFuncB customFuncB1`
```
/**
* Setter for native field CustomFuncB1, being a struct owned function pointer.
*
* Native Field Signature (PointerType) typedef 'T2_CustomFuncB' -> int32_t (*)(T2_UserData * pUserData), size [fixed false, lnx64 8], const[false], pointer*1, funcPointer
*
*/
public final T2_InitializeOptions setCustomFuncB1(long src) { .. }
/**
* Getter for native field CustomFuncB1, being a struct owned function pointer.
*
* Native Field Signature (PointerType) typedef 'T2_CustomFuncB' -> int32_t (*)(T2_UserData * pUserData), size [fixed false, lnx64 8], const[false], pointer*1, funcPointer
*
*/
public final long getCustomFuncB1() { .. }
/** Interface to C language function:
int32_t CustomFuncB1(T2_UserData * pUserData)
*/
public final int CustomFuncB1(T2_UserData pUserData) { .. }
```
### Java Callback from Native C-API Support
GlueGen supports registering Java callback methods to native C-API functions in the form:
```
typedef int32_t ( * T_CallbackFunc)(size_t id, const char* msg, void* userParam);
void AddMessageCallback(T_CallbackFunc func, void* userParam);
void RemoveMessageCallback(T_CallbackFunc func, void* userParam);
void InjectMessageCallback(size_t id, const char* msg);
```
and the following GlueGen configuration
```
ArgumentIsString T2_CallbackFunc 1
ArgumentIsString InjectMessageCallback 1
# Define a JavaCallback, enacted on a function-pointer argument `T2_CallbackFunc` and a user-param `void*` for Java Object mapping
JavaCallbackDef T2_CallbackFunc 2
```
This will lead to the following result
```
public interface Bindingtest2 {
/** JavaCallback interface: T2_CallbackFunc -> int32_t (*T2_CallbackFunc)(size_t id, const char * msg, void * userParam) */
public static interface T2_CallbackFunc {
/** Interface to C language function:
int32_t callback(size_t id, const char * msg, void * userParam)
Alias for: T2_CallbackFunc */
public int callback(long id, String msg, Object userParam);
}
...
/** Entry point (through function pointer) to C language function:
void AddMessageCallback(int32_t (*func)(size_t id, const char * msg, void * userParam), void * userParam)
*/
public void AddMessageCallback(T2_CallbackFunc func, Object userParam);
/** Entry point (through function pointer) to C language function:
void RemoveMessageCallback(int32_t (*func)(size_t id, const char * msg, void * userParam), void * userParam)
*/
public void RemoveMessageCallback(T2_CallbackFunc func, Object userParam);
/** Entry point (through function pointer) to C language function:
void InjectMessageCallback(size_t id, const char * msg)
*/
public void InjectMessageCallback(long id, String msg);
```
*TODO: Work in progress*
## Misc Configurations
### `LibraryOnLoad ` for `JNI_OnLoad*(..)` ...
`LibraryOnLoad ` generates native JNI code `JNI_OnLoad(..)` used for dynamic libraries,
`JNI_OnLoad_(..)` used for static libraries,
`JVMUtil_GetJNIEnv(..)` and the instance of `JavaVM* _jvmHandle`.
The `JNI_OnLoad*(..)` methods set the `JavaVM* _jvmHandle`, which in turn is utilized by
`JVMUtil_GetJNIEnv(..)` to attach a new thread to the `JavaVM*` generating a new `JNIEnv*`in daemon mode -
or just to retrieve the thread's `JNIEnv*`, if already attached to the `JavaVM*`.
The `LibraryBasename` parameter is used to generate the `JNI_OnLoad_(..)` variant for statically linked libraries.
`JNI_OnLoad(..)`, `JNI_OnLoad_(..)` and `JVMUtil_GetJNIEnv(..)`
## Platform Header Files
GlueGen provides convenient platform headers,
which can be included in your C header files for native compilation and GlueGen code generation.
Example:
```
#include
#include
uint64_t test64;
size_t size1;
ptrdiff_t ptr1;
```
To compile this file you have to include the following folder to your compilers system includes, ie `-I`:
```
gluegen/make/stub_includes/platform
```
To generate code for this file you have to include the following folder to your GlueGen `includeRefid` element:
```
gluegen/make/stub_includes/gluegen
```
## Pre-Defined Macros
To identity a GlueGen code generation run, GlueGen defines the following macros:
```
#define __GLUEGEN__ 2
```