From 5ceca8550b82591a6a2661a26d3e0d5e6e3e15ff Mon Sep 17 00:00:00 2001
From: Sven Gothel <sgothel@jausoft.com>
Date: Wed, 5 Jul 2023 10:21:48 +0200
Subject: GlueGen: Add 'PascalString' string semantics (length + value-ptr),
 added prelim code for JavaCallback use-case emitBodyMapCToJNIType()

It is common in toolkit APIs that a string might not be passed as a 'nul' terminated (EOS) C string,
but as a Pascal string with a given length argument.

A C string is specied as
  ArgumentIsString alEventCallbackInject 3
while allowing multiple indices ..

A Pascal string can be specified as
  ArgumentIsPascalString ALEVENTPROCSOFT 3 4
while allowing multiple indice-tuples for length and value ..

The tuple consist of the length agrument-index first (usually an int)
followed by the value argument-index (usually a 'char*').

+++

CMethodBindingEmitter.emitBodyMapCToJNIType(), where PascalString is implemented,
is currently being used for
- JNI return statement (no PascalString impact possible)
- JavaCallback C type -> JNI type, PascalString impacting
---
 doc/manual/index.html | 13 +++++++++++++
 1 file changed, 13 insertions(+)

(limited to 'doc/manual')

diff --git a/doc/manual/index.html b/doc/manual/index.html
index 01449f7..b960b56 100755
--- a/doc/manual/index.html
+++ b/doc/manual/index.html
@@ -959,6 +959,19 @@
                             <code>byte[]</code> or <code>ByteBuffer</code>.
                         </dd>
 
+                        <dt><strong><a name="ArgumentIsString">ArgumentIsPascalString</a></strong></dt>
+                        <dd> Syntax: <code>ArgumentIsString [function name]
+                                [indice-tuples...]</code>, with each tuple being index for the <code>int length</code>
+                                and the <code>const char* value</code> argument with index 0 for the the first argument<br/>
+
+                            (optional) For a C function with one or more outgoing
+                            <code>int length</code> and <code>char* value</code> (or compatible data type) arguments, 
+                            indicates that those arguments are semantically non-null-terminated Pascal strings rather than
+                            null-terminated C strings or arbitrary arrays of bytes. The generated glue code will be modified to
+                            emit those arguments as java.lang.String objects rather than
+                            <code>byte[]</code> or <code>ByteBuffer</code>.
+                        </dd>
+
                         <dt><strong><a name="ClassJavadoc">ClassJavadoc</a></strong></dt>
                         <dd> Syntax: <code>ClassJavadoc [class name] [code...]</code> <br/>
 
-- 
cgit v1.2.3