The @dll.struct directive is specified at the class level and marks the class declaration as equivalent to a C structure definition. Instances of the class can then be passed through J/Direct and COM method calls that require a C structure with the same composition.
Note The syntax for @dll.struct and @com.struct is nearly identical. The only difference between them is the way that some fields are marshaled between Java and native code.
Within the class declaration, you need to supply fields whose Java types map to the types of the fields in the native structure in the order they occur in the native structure. For information about choosing the data types of the fields, see Correspondence Between Types Inside Structures.
All strings and characters in a class with an @com.struct directive will be converted to and from their native counterparts using the Unicode character encoding.
A Java-callable data wrapper (JCDW) is a Java object exposed by the Microsoft VM for external data (such as a C struct). Values are automatically propagated between fields in the Java object and fields in the external structure. You can explicitly cause propagation of the fields by calling com.ms.dll.DllLib.propagateStructFields.
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.
The directive parameters ansi, auto, and unicode, used with the @dll.struct directive, determine the native character encoding (ANSI or Unicode) that the Microsoft VM will use when converting Java string and character fields to their native counterparts. In operating systems that use ANSI as their base character encoding, such as Microsoft® Windows® 95 or Windows® 98, ANSI strings and characters are generally required in structures. In Unicode-based operating systems, such as Microsoft® Windows NT® and Microsoft® Windows® 2000, Unicode strings and characters are generally desirable. The auto parameter causes the VM to choose the correct encoding type at runtime, depending on the base character encoding of the operating system that the class is used on.
At most one of the directive parameters ansi, auto, and unicode can be specified in a given @dll.struct directive. If none are specified, the default is ansi.
@dll.struct([ansi | unicode | auto], [pack=1 | 2 | 4 | 8], [noAutoOffset], [safe], [safeAddFlags=integer])
ansi | Specifies that the VM should use an ANSI character encoding when converting Java string and character fields to and from their native counterparts.
Dependency: Cannot be used with auto or unicode. Not a valid parameter for the @com.struct directive. |
unicode | Specifies that the VM should use the Unicode character encoding when converting Java string and character fields to and from their native counterparts.
Dependency: Cannot be used with ansi or auto. Not a valid parameter for the @com.struct directive. |
auto | Specifies that the character encoding that the VM should use when converting Java string and character fields to and from their native counterparts should be determined at runtime. Specifically, the base character encoding of the operating system will be used.
Dependency: Cannot be used with ansi or unicode. Not a valid parameter for the @com.struct directive. |
pack=1 | 2 | 4 | 8 | Specifies the packing alignment of the structure, which determines how fields will be aligned in memory. Typically, the packing alignment for a structure is specified in C by using the #pragma pack(n) syntax. The value given for the Java pack parameter should be the same as that used for the corresponding C structure. The default value is 8, which is the default Microsoft® Visual C++® packing alignment. For more information on setting the packing size, see Structure Packing.
Dependency: If the noAutoOffset parameter is specified, the Microsoft VM ignores this parameter. |
noAutoOffset | Specifies that the offset of each field in the structure will be explicitly defined. Each field in the class must have an @dll.structmap directive that specifies the field’s offset via the offset directive parameter.
If this parameter is not specified, the Microsoft VM automatically calculates offsets for each field in the structure. In this case, the default packing size is 8 bytes, but can be modified by the pack parameter. Dependency: @dll.structmap |
safe | Specifies that the structure may be used safely by untrusted classes. A COM_Safety attribute is attached to the class. |
safeAddFlags=integer | Specifies a word of information to be put in the COM_Safety attribute.
Note The Microsoft VM currently ignores this data when reading the COM_Safety attribute. |
COM_Class_Type | Class scope. |
COM_MapsTo | Field scope. |
COM_Safety | Class scope. |
@dll.structmap (and @com.structmap)
Calling Different Versions of DLL Functions
The following table describes the syntax for several situations that you might use the @dll.struct directive in.
Situation | Required Syntax | Explanation |
Declare a structure. | /**@dll.struct()*/ | When you do not specify ansi, unicode, or auto, character and string fields will be converted to their native counterparts using an ANSI character encoding. |
Set a structure's packing size. | /**@dll.struct (pack=integer)*/ |
integer can be 1, 2, 4, or 8. |
Declare a structure that has a field of type char. | /**@dll.struct(ansi)*/ | The character field represents an ANSI character. |
Declare a structure with a field of type string and set the packing size. | /**@dll.struct (unicode, pack=integer)*/ |
The string fields will be in Unicode format, and the packing size is set to 1, 2, 4, or 8, depending on the value of integer. |
When used without parameters, @dll.struct defaults to auto, and assumes that pack=8, that it is unsafe to link to this class from untrusted classes, and that field offsets are automatically generated by the Microsoft VM. An example @dll.struct directive using no parameters has the following syntax:
/** @dll.struct() */ public class MyStruct{ public int x; public int y; }