The @dll.structmap directive is applied to a field in an @dll.struct class to specify how a field is exposed to native memory. This directive must be used for each field if the structure was declared using @dll.struct(noAutoOffset), which requires the offset keyword in each @dll.structmap directive. This directive can also be used to override the default field mappings in other struct classes.
Note When passing an array of JCDW's between COM/Microsoft® Win32® APIs and Java, in either direction, if the JCDW contains complex types such as Strings, then these complex types may not be properly propagated to memory that is not garbage collected. For normal JCDW parameters, the marshaling engine always attempts to propagate structs, but this is not true for the case of marshaling arrays.
Static fields in a Java class with an @dll.struct directive are not considered part of the class’ corresponding native structure. Therefore, such fields can hold information that is not present in the native structure.
Note There are currently no differences between @dll.structmap and @com.structmap directives.
@dll.structmap([[[offset=integer | long], [type=BOOLEAN | CURRENCY | CUSTOM | CUSTOMBYVAL | DATE | DISPATCH | FIXEDARRAY | I1 | I2 | I4 | I8 | OBJECT | PTR | R4 | R8 | STRING | TCHAR | TCHAR[integer] | U1 | U2 | U4 | U8], [iid=GUID], [thread=AUTO | NO], [size=integer | long], [customMarshal=string], [customMarshalFlags=integer], [addFlags=integer]]] [string])
| offset=integer | long
Example: offset=4 |
Specifies the byte offset of the starting byte in this field.
Dependency: Should be used if noAutoOffset is declared in the @dll.struct or @com.struct directive at class level. |
| type=BOOLEAN | CURRENCY | CUSTOM | CUSTOMBYVAL | DATE | DISPATCH | FIXEDARRAY | I1 | I2 | I4 | I8 | OBJECT | PTR | R4 | R8 | STRING | TCHAR | TCHAR[integer] | U1 | U2 | U4 | U8 | Defines the native type of the Java field. See Type Values for @com.parameters and @dll.structmap for more information.
If this directive parameter is not declared, a default native type is used, according to the Default Native Types for Java Parameters table. Fields of struct type are special cases. These are Java-Callable Data Wrappers (JCDWs), those classes that declare an @com.struct or @dll.struct directive. In such cases, the native type is an embedded struct. There is no way to declare this mapping using the type parameter. Dependencies: CUSTOM and CUSTOMBYVAL: The customMarshal directive parameter must be declared. DISPATCH and OBJECT: Secondary information may be specified using the iid directive parameter. FIXEDARRAY: Secondary information may be specified using the size directive parameter. Note By-value structures containing any primitive types with @com.stuctmap [(type=FIXEDARRAY size=n)] are not automatically propagated. Call com.ms.com.DllLib.propagateStructFields(MyStruct, false) before passing values to the native side. SAFEARRAY: The vt directive parameter must be specified. TCHAR and TCHAR[integer]: Secondary information may be specified using the ansi, unicode, and auto directive parameters in the @dll.struct directive for the class containing this field. |
| iid=GUID
Example: iid=0000000F-0000-0000-C000-000000000046 |
Specifies the interface identifier (IID) of this field. The Microsoft VM ensures that only interfaces of this type are given to COM clients and servers.
Dependency: Valid only for Java fields declaring type=OBJECT or type=DISPATCH. Default: IID_IUnknown. |
| thread=AUTO | NO | Specifies the marshaling behavior to be applied to the COM object field. If AUTO is specified, the Microsoft VM automatically marshals any calls from Java on this object to the thread that the object was created in. This is the safest option, and the default.
If NO is specified, the Microsoft VM assumes that the object is callable on any Java thread. Dependency: Valid only for Java fields declaring type=DISPATCH or type=OBJECT. Default: AUTO. |
| size=integer | long
Example: size=3 |
Specifies the number of elements in an array.
Dependency: Valid only for Java fields declaring type=FIXEDARRAY. Default: 1. |
| customMarshal=string
Example: |
Specifies the name of a class. This class will be asked to marshal the field.
Dependency: Valid only for Java fields declaring type=CUSTOM or type=CUSTOMBYVAL. |
| customMarshalFlags=integer | Specifies bits available to the custom marshaler when invoked. Must be in the range 0 to 3. These bits move into the high two bits of the MCMapsTo.typedesc.Flags field in the COM_MapsTo attribute generated for the field.
Dependency: Valid only for Java fields declaring type=CUSTOM or type=CUSTOMBYVAL. |
| addFlags=integer | A low-level parameter that allows direct modification of created class attributes. Specifies a word of information to be put in the COM_Safety attribute.
A low-level parameter that specifies a byte value in the range 0 to 255 that is moved into the MCMapsTo.typedesc.Flags field in the COM_MapsTo attribute generated for the field. |
| string | The name of the Java field. The preceding directive parameters apply to this field in the class.
Dependency: The field name specified must be that of the field immediately following the directive. |
| COM_MapsTo | Field scope. |
@dll.struct (and @com.struct)
@dll.structmap (and @com.structmap)
Fixed-size Strings Embedded within Structures
Fixed-Size Scalar Arrays Embedded within Structures
| Situation | Required syntax | Explanation |
| Structure that contains a fixed-size field. |
/**@dll.structmap ([type=TCHAR[size]])*/ |
size is a decimal integer that indicates the number of characters in the string, including space for the null terminator. |
| Structure that contains a fixed-size array. |
/**@dll.structmap ([type=FIXEDARRAY, size=n])*/ |
n is a decimal integer that represents the number of elements in the array. |
The following structure uses the noAutoOffset directive parameter and specifies the offset for each field using the @com.structmap directive. The safe parameter indicates that this structure is safe to use by untrusted classes. The unicode parameter indicates that any strings or characters in the structure should be represented as native Unicode characters.
/** @com.struct(noAutoOffset, safe, unicode) */
public final class MULTI_QI {
/** @com.structmap([offset=0, type=PTR] pIID) */
public com.ms.com._Guid pIID;
/** @com.structmap([offset=4, iid=00000000-0000-0000-C000000000000046, thread=AUTO, type=OBJECT] pItf) */
public com.ms.com.IUnknown pItf;
/** @com.structmap([offset=8, type=U4] hr) */
public int hr;
}
The following example illustrates how a custom marshaler can be specified using the @dll.structmap directive.
/** @dll.struct() */
public final class StringStruct {
/** @dll.structmap([type=CUSTOM, customMarshal="com.ms.com.UniStringMarshaller"]) */
String strUnicode;
/** @dll.structmap([type=CUSTOM, customMarshal="com.ms.com.AnsiStringMarshaller"]) */
String strAnsi;
/** @dll.structmap([type=CUSTOM, customMarshal="com.ms.dll.StringMarshaler"]) */
String strAuto;
}