Microsoft SDK for Java

@com.parameters

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.

Syntax

@com.parameters([parameters] methodParamName1, [parameters] methodParamName2, … [[parameters] return])

Parameters

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.
com.UniStringMarshaller"

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 Values for @com.parameters and @dll.structmap

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.

Default Native Types for Java Parameters

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 and Native Array Type Mappings

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.

Attributes

COM_GuidPool Class scope.
COM_MethodPool Class scope.

Related Directives

@com.method

Support for iid_is and size_is

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.

Examples

/** @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();

© 1999 Microsoft Corporation. All rights reserved. Terms of use.