The @com.parameters directive is used with the @com.method directive to specify how Java parameter types and return types are mapped to the underlying COM or native types. It is also possible to specify a custom marshaler that handles how the parameters are represented in the native and Java representations.
Each @com.parameters directive contains a group of directive parameters inside square braces for every parameter in the method, and for the return value if it is not void.
@com.parameters([parameters] methodParamName1, [parameters] methodParamName2, … [[parameters] return])
iid=GUID | Specifies the interface identifier (IID) of this parameter. The Microsoft VM will ensure that only interfaces of this "type" are given to COM clients and servers.
Dependency: Valid only for Java parameters declaring type=OBJECT or type=DISPATCH. Default: IID_IUnknown. |
thread=AUTO | NO | Specifies the marshaling behavior to be applied to the COM object parameter. If AUTO is specified, the Microsoft virtual machine 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 parameters declaring type=OBJECT or type=DISPATCH. Default: AUTO. |
type=ARRAY | BOOLEAN | CURRENCY | CUSTOM | CUSTOMBYREF | CUSTOMBYVAL | DATE | DISPATCH | I1 | I2 | I4 | I8 | OBJECT | PTR | R4 | R8 | SAFEARRAY | STRING | STRUCT | U1 | U2 | U4 | U8 | VARIANT | Defines the native type of the Java parameter. See Type Values for @com.parameters and @dll.structmap for details.
If this directive parameter is not declared, a default native type is used, according to the table below. Dependencies: ARRAY: Secondary information may be specified using the size and elementType directive parameters. CUSTOM, CUSTOMBYREF, and CUSTOMBYVAL: The directive parameter customMarshal must be declared. DISPATCH and OBJECT: Secondary information may be specified using the iid directive parameter. PTR: Secondary information may be specified using the elementType directive parameter. Note For return value parameters declaring type=PTR, the VM does not auto-propagate the struct parameter. Call com.ms.com.DllLib.propagateStructFields(JCDW, true) to manually propagate the structure. SAFEARRAY: The directive parameter vt must be specified. |
methodParamNameN or return | methodParamNameN is the name of the Nth parameter in the Java method. The preceding directive parameters apply to this parameter in the method.
return indicates that the preceding directive parameters apply to the return value of the Java method, which corresponds to the COM return value (which may be retval-mapped. |
in | Indicates that the parameter is to be passed from the calling procedure to the called procedure. The out directive parameter may also be specified. |
out | Indicates that data contained in the parameter is to be passed back from the called procedure to the calling procedure. This allows the calling procedure to obtain data modified by the called procedure. The directive parameter in may also be specified.
Valid only for reference parameters (objects and arrays). |
elementType=DISPATCH | I2 | I4 | OBJECT | R4 | R8 | STRING | U1 | VARIANT | Specifies the element type of arrays if type=ARRAY or type=PTR.
Dependency: Valid only for Java parameters declaring type=ARRAY or type=PTR. Default: Determined by the Java array element type as defined in the Java and Native Array Type Mappings table. |
size=integer | long | For Java parameters declaring type=ARRAY, specifies the number of elements in the array parameter. For Java parameters declaring type=STRUCT, specifies the size, in bytes, of the Java parameter’s corresponding native structure.
Dependency: Valid only for Java parameters declaring type=ARRAY or type=STRUCT. Default: 1 for type=ARRAY, 0 for type=STRUCT. |
customMarshal=string
Example: customMarshal="com.ms. |
Specifies the name of a class. This class will be asked to marshal the field.
Dependency: Valid only for Java parameters declaring type=CUSTOM, type=CUSTOMBYREF, 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 this parameter's MCTypeDesc.Flags field in the method pool entries generated for the method.
Dependency: Valid only for Java parameters declaring type=CUSTOM, type=CUSTOMBYREF, or type=CUSTOMBYVAL. |
vt=integer | Specifies the VARTYPE of elements within a SAFEARRAY parameter. Use the VT_* values (for example, for an array of integers, use 3=VT_I4).
Dependency: Valid only for Java parameters declaring type=SAFEARRAY. |
byref | Specifies that this argument is passed by reference (VT_BYREF) in a VARIANT.
Dependency: Valid only for dispatch methods. |
array | Specifies that this parameter is passed as an array (VT_ARRAY) in a VARIANT.
Dependency: Valid only for dispatch methods. |
name=string
Example: name="Hello" |
Specifies a name to be associated with this parameter.
Dependency: Valid only for dispatch methods. Note This parameter is not currently used by the VM. |
type | Native Type (for vtable Method Parameters and struct Fields) | VARTYPE (for dispatch Method Parameters) |
ARRAY | A native array. The size of the native array is given by the size directive parameter. See the Java and Native Array Type Mappings table for details. | The elementType directive parameter defines the array element VARTYPE.
Call this element VARTYPE vtElement. The VARTYPE of this parameter is then VT_BYREF | vtElement. A default VARTYPE is generated if elementType is not declared. See the Java and Native Array Type Mappings table for details. |
BOOLEAN | VARIANT_BOOL (16-bit value) | VT_BOOL |
CURRENCY | __int64 (unsigned 64-bit integer) | VT_CY |
CUSTOM | Specifies that this parameter or field will be custom marshaled by the class specified in the customMarshal directive parameter. The native type is defined by the custom marshaling class. | N/A |
CUSTOMBYREF | Specifies that this parameter will be custom marshaled by the class specified in the customMarshal directive parameter as a by-reference value. This means that the custom marshaler's toExternal method will be called to marshal the parameter to native code, and its toJava method will be called to marshal the parameter from native code to Java. The native type is defined by the custom marshaling class. | N/A |
CUSTOMBYVAL | Specifies that this parameter or field will be custom marshaled by the class specified in the customMarshal directive parameter as a by-value parameter. This means that the custom marshaler's copyToExternal method will be called to marshal the parameter to native code, and its copyToJava method will be called to marshal the value from native code to Java. The native type is defined by the custom marshaling class. | N/A |
DATE | double (64-bit float) | VT_DATE |
DISPATCH | The native type is a pointer to an IDispatch-derived interface. The exact type of the interface is given by the iid directive parameter. | VT_DISPATCH |
FIXEDARRAY | The native type is an embedded array. The size of the array is given by the size directive parameter. Valid only for fields typed as an array of primitive type (asserted by the Microsoft VM). For arrays with elements of type char, the native element type is determined by the structure's default character type (see the @dll.struct directive parameters ansi, unicode, and auto). Arrays with elements of type boolean are mapped to native arrays with elements of type BOOL. | N/A |
I1 | char (unsigned 8-bit integer) | VT_I2 |
I2 | short (signed 16-bit integer) | VT_I2 |
I4 | long (signed 32-bit integer) | VT_I4 |
I8 | __int64 (signed 64-bit integer) | N/A |
OBJECT | The native type is a pointer to an IUnknown-derived interface. The exact type of the interface is given by the iid directive parameter. | VT_UNKNOWN |
PTR | For parameters of type java.lang.String, the native type is a Unicode string allocated using the CoTaskMemAlloc API.
For parameters or fields of struct type (those classes with @com.struct or @dll.struct declarations), the native type is a pointer to a structure. |
For parameters of array type, the elementType directive parameter defines the array element VARTYPE. Call this element VARTYPE vtElement. The VARTYPE of this parameter is then VT_BYREF | vtElement.
A default VARTYPE is generated if elementType is not declared. See the Java and Native Array Type Mappings table for details. For parameters of type com.ms.com.Variant, if the elementType parameter directive is declared, the VARTYPE is determined as above. Otherwise, the VARTYPE is VT_BYREF | VT_VARIANT. |
R4 | float (32-bit float) | VT_R4 |
R8 | double (64-bit float) | VT_R8 |
SAFEARRAY | If the value of the vt directive parameter has the VT_BYREF bit set, the native type is a pointer to a pointer to SAFEARRAY (SAFEARRAY**). Otherwise, the native type is a pointer to SAFEARRAY (SAFEARRAY*). | VT_ARRAY | vt |
STRING | BSTR | VT_BSTR |
STRUCT | By-value structure. | N/A |
TCHAR | Native character (char, WCHAR, or TCHAR). The character's encoding (ANSI or Unicode, signed 8-bit or unsigned 16-bit values, respectively) is dependent on the struct's desired character encoding. See the @dll.struct directive parameters ansi, unicode, and auto. | N/A |
TCHAR[integer] | The native type is an embedded string; that is, an embedded character array with length integer and null termination. The character encoding used (ANSI or Unicode) is dependent on the struct's desired character encoding. See the @dll.struct directive parameters ansi, unicode, and auto. Valid only for fields of type java.lang.String (asserted by the Microsoft VM). | N/A |
U1 | unsigned char (unsigned 8-bit integer) | VT_UI1 |
U2 | unsigned short (unsigned 16-bit integer) | VT_I4 |
U4 | unsigned long (unsigned 32-bit integer) | VT_I4 |
U8 | unsigned __int64 (unsigned 64-bit integer) | N/A |
VARIANT | By-value VARIANT | Determined directly by VARIANT parameter. |
Java Parameter Type | Native Type (vtable Method) | VARTYPE (dispatch Method) |
boolean | VARIANT_BOOL | VT_BOOL |
byte | char (signed 8-bit integer) | VT_UI1 |
char | WCHAR (Unicode character, unsigned 16-bit integer) | VT_I2 |
double | double (64-bit float) | VT_R8 |
float | float (32-bit float) | VT_R4 |
int | long (signed 32-bit integer) | VT_I4 |
long | __int64 (signed 64-bit integer) | N/A |
short | short (signed 16-bit integer) | VT_I2 |
java.lang.String | BSTR | VT_BSTR |
com.ms.com.Variant | VARIANT | VT_VARIANT |
OtherObjectType | N/A | VT_UNKNOWN |
ArrayType | Native array. The element type is determined by the Java and Native Array Type Mappings table. | VT_BYREF | vtElement, where vtElement is the array element VARTYPE determined by the Java and Native Array Type Mappings table. |
JAVA ARRAY ELEMENT TYPE | NATIVE ARRAY ELEMENT TYPE | DISPATCH ELEMENT VARTYPE |
boolean | VARIANT_BOOL | VT_BOOL |
byte | 8-bit signed integer | VT_UI1 |
char | 16-bit unsigned integer | VT_I2 |
short | 16-bit signed integer | VT_I2 |
int | 32-bit signed integer | VT_I4 |
long | 64-bit signed integer | N/A |
float | 32-bit float | VT_R4 |
double | 64-bit float | VT_R8 |
java.lang.String | BSTR | VT_BSTR |
com.ms.com.Variant | VARIANT | VT_VARIANT |
StructWrapperType | StructType * | VT_UNKNOWN |
java.lang.Object | IUnknown * | VT_UNKNOWN |
InterfaceWrapperType | InterfaceType * | VT_UNKNOWN |
Note All types are taken statically from the method signature (that is, compile-time types). Actual run-time types are not used. StructWrapperType represents a generic JCDW type with corresponding native type StructType, while InterfaceWrapperType represents a generic COM interface wrapper type for the COM interface InterfaceType.
COM_GuidPool | Class scope. |
COM_MethodPool | Class scope. |
To express iid_is and size_is from an @com directive, declare methods as follows:
/** @com.method(...) @com.parameters([in,type=PTR] riid, [customMarshal="com.ms.com.IIDIsMarshaler",type=CUSTOM] return) */ public IUnknown BindToObject(_Guid riid); /** @com.method(...) @com.parameters([in,type=U4] length, [in,out,customMarshal="com.ms.com.SizeIsMarshaler",type=CUSTOM] items) */ public void GetItems(int length, int[] items);
See the sample in Samples\com\iidis_sizeis for more information.
/** @com.method(vtoffset=30, dispid=301, type=METHOD, name="ClientToWindow", addFlagsVtable=4) @com.parameters([in,out,size=1,elementType=I4,type=ARRAY] pcx, [in,out,size=1,elementType=I4,type=ARRAY] pcy) */ public void ClientToWindow(int[] pcx, int[] pcy); /** @com.method(vtoffset=32, dispid=303, type=METHOD, name="GetProperty") @com.parameters([in,type=STRING] Property, [type=VARIANT] return) */ public com.ms.com.Variant GetProperty(java.lang.String Property); /** @com.method(vtoffset=12, dispid=200, type=PROPGET, name="Application") @com.parameters([iid=00020400-0000-0000-C000-000000000046,thread=AUTO,type=DISPATCH] return) */ public java.lang.Object getApplication();