GlueGen Struct [17]: Handle void pointers, i.e. `void*`, within a struct as `Opaque` configured pointer-types

.. includes cross-ref'ed doc and unit test

2 files changed, 69 insertions, 33 deletions

diff --git a/doc/GlueGen_Mapping.html b/doc/GlueGen_Mapping.html
index 96c56c5..9739082 100644
--- a/doc/GlueGen_Mapping.html
+++ b/doc/GlueGen_Mapping.html
@@ -940,6 +940,8 @@ fields</p>
 <ul>
 <li>See <a href="#primitive-mapping"><em>Primitive Mapping</em></a>
 above.</li>
+<li>See <a href="#struct-mapping-notes"><em>Opaque and
+<code>void*</code> notes</em></a> below.</li>
 <li>See <a href="#pointer-mapping"><em>Pointer Mapping</em></a> for
 <em>pointer-to-pointer</em> values above and <a
 href="#struct-pointer-pointer-support">Struct Pointer-Pointer
@@ -969,7 +971,48 @@ function which has to be compiled and its library loaded.</p>
 <code>public static boolean usesNativeCode()</code> can be used to
 validate whether the produced Java class requires a corresponding
 library for additional native code.</p>
+<h3 id="struct-mapping-notes">Struct Mapping Notes</h3>
+<ul>
+<li><p><a href="#opaque-java-primitive-type-symbol"><code>Opaque</code>
+configured pointer-types</a> are treated as <code>long</code> values
+from the Java side<br />
+while maintaining their architecture dependent pointer size within
+native memory.</p></li>
+<li><p>Void pointers, i.e. <code>void*</code>, within a struct are
+handled as <a
+href="#opaque-java-primitive-type-symbol"><code>Opaque</code> configured
+pointer-types</a>.</p></li>
+<li><p><em>ConstElemCount</em> via <strong>ReturnedArrayLength
+&lt;int&gt;</strong> implies <em>native ownership</em> for a
+<em>Pointer</em> referenced <em>native</em> memory if the expression is
+constant. Otherwise the <em>native</em> memory has <em>java
+ownership</em>. See <a
+href="#returnedarraylength-symbol-expression">ReturnedArrayLength
+Setting</a> below.</p></li>
+<li><p>Utilizing a <em>flexible</em> <em>elemCount</em> via
+<strong>ReturnedArrayLength getValElements()</strong> renders us unable
+to determine ownership of pointer referenced <em>native</em> memory
+segment and hence renders ownership <em>mixed or ambiguous</em>, <a
+href="#signature-const-int32_t--customsize-ambiguous-java-owned">see
+[5]</a>. This is due to the fact, that native code may allocate memory
+and writes its <em>elemCount</em> into the designated field
+<em>valElements</em>. In such cases, the user being aware of the
+underlying API shall utilize <code>setVal(..)</code> and
+<code>releaseVal()</code> with care.</p></li>
+<li><p>To release native memory with <em>java ownership</em>, i.e. a
+native ByteBuffer, <code>releaseVal()</code> can be used.</p></li>
+</ul>
 <h3 id="gluegen-struct-settings">GlueGen Struct Settings</h3>
+<h4 id="opaque-java-primitive-type-symbol"><strong>Opaque</strong>
+<em>Java-primitive-type</em> <em>symbol</em></h4>
+<p>See also <a href="manual/index.html#SecOpaque">Opaque section in
+manual</a>.</p>
+<ul>
+<li><p><code>Opaque long T2_UndefStruct*</code></p>
+<p>Pointers to <code>T2_UndefStruct</code> will be handled opaque, i.e.
+as <code>long</code> values from the Java side while maintaining their
+architecture dependent pointer size within native memory.</p></li>
+</ul>
 <h4 id="immutableaccess-symbol"><strong>ImmutableAccess</strong>
 <em>symbol</em></h4>
 <p>Immutable access can be set for a whole struct or a single field of a
@@ -1045,28 +1088,6 @@ variants, a <code>String</code> variant will be produced.</p>
 <p>See <a href="#string-mapping"><em>String Mapping</em></a>
 above.</p></li>
 </ul>
-<h3 id="struct-mapping-notes">Struct Mapping Notes</h3>
-<ul>
-<li><p><em>ConstElemCount</em> via <strong>ReturnedArrayLength
-&lt;int&gt;</strong> implies <em>native ownership</em> for a
-<em>Pointer</em> referenced <em>native</em> memory if the expression is
-constant. Otherwise the <em>native</em> memory has <em>java
-ownership</em>. See <a
-href="#returnedarraylength-symbol-expression">ReturnedArrayLength
-Setting</a> above.</p></li>
-<li><p>Utilizing a <em>flexible</em> <em>elemCount</em> via
-<strong>ReturnedArrayLength getValElements()</strong> renders us unable
-to determine ownership of pointer referenced <em>native</em> memory
-segment and hence renders ownership <em>mixed or ambiguous</em>, <a
-href="#signature-const-int32_t--customsize-ambiguous-java-owned">see
-[5]</a>. This is due to the fact, that native code may allocate memory
-and writes its <em>elemCount</em> into the designated field
-<em>valElements</em>. In such cases, the user being aware of the
-underlying API shall utilize <code>setVal(..)</code> and
-<code>releaseVal()</code> with care.</p></li>
-<li><p>To release native memory with <em>java ownership</em>, i.e. a
-native ByteBuffer, <code>releaseVal()</code> can be used.</p></li>
-</ul>
 <h3 id="struct-setter-pseudo-code">Struct Setter Pseudo-Code</h3>
 <h4 id="overview-1">Overview</h4>
 <p>In general we have the following few cases</p>
diff --git a/doc/GlueGen_Mapping.md b/doc/GlueGen_Mapping.md
index 8965dd6..b6a9514 100644
--- a/doc/GlueGen_Mapping.md
+++ b/doc/GlueGen_Mapping.md
@@ -208,6 +208,7 @@ A *Struct* is a C compound type declaration, which can be mapped to a Java class
 A *Struct* may utilize the following data types for its fields
 * *Primitive*, i.e. *char*, *int32_t*, ...
   * See [*Primitive Mapping*](#primitive-mapping) above.
+  * See [*Opaque and `void*` notes*](#struct-mapping-notes) below.
   * See [*Pointer Mapping*](#pointer-mapping) for *pointer-to-pointer* values above and [Struct Pointer-Pointer Support](#struct-pointer-pointer-support) below.
   * See [*String Mapping*](#string-mapping) above.
 * *Struct*, i.e. an aggregated or referenced compound variable
@@ -226,8 +227,33 @@ call the underlying native function which has to be compiled and its library loa
 The generated method `public static boolean usesNativeCode()` can be used to validate
 whether the produced Java class requires a corresponding library for additional native code.
 
+### Struct Mapping Notes
+
+* [`Opaque` configured pointer-types](#opaque-java-primitive-type-symbol) are treated as `long` values from the Java side    
+  while maintaining their architecture dependent pointer size within native memory.
+  
+* Void pointers, i.e. `void*`, within a struct are handled as [`Opaque` configured pointer-types](#opaque-java-primitive-type-symbol).
+
+* *ConstElemCount* via **ReturnedArrayLength \<int\>** 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.
 
@@ -301,17 +327,6 @@ A direct C code `char` array or indirect array via pointer can be interpreted as
     
     See [*String Mapping*](#string-mapping) above.
 
-### Struct Mapping Notes
-
-* *ConstElemCount* via **ReturnedArrayLength \<int\>** 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) above.
-
-* 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.
-
 ### Struct Setter Pseudo-Code
 #### Overview
 In general we have the following few cases