Attribute Reference

Overview of COM Attributes for Java Class Files

Previous

Virtual Machine

Attribute Reference

This section describes, at the bit level, the details of the attributes that must be present in any .CLASS file that is to be used to invoke a COM object from Java, or expose a Java object as a COM object.

There are the following attributes:

Level Name Description

Class COM_ClassType Denotes the implementation language

Class COM_GuidPool Stores IIDs and CLSIDs

Class COM_MethodPool Stores distilled typelib information

Method COM_ExposedAs_Group Exposes a Java method to COM

Method COM_ProxiesTo Exposes a COM method to Java

Field COM_MapsTo Exposes external data to Java

All unused bits in Flag fields must be zero.

Data Type Sizes and Alignment

Except where noted, BYTEs, WORDs and DWORDs are all unsigned and stored in the .CLASS in Big-Endian format.

BYTE 8 bits
WORD 16 bits
DWORD 32 bits

There is no implicit padding between the fields of the structures, or any padding after the last field of any structure.

COM_ClassType

typedef struct {
    WORD        Flags;          // Must be zero. Reserved for future use.
    WORD        ClassType;      // CCTCT_JCW or CCTCT_JCDW
    WORD        CLSIDIndex;     // Optional index to CLSID (-1 for none)
} CCT_Attr;
This attribute, of attribute level Class, denotes the implementation language.

Parameter Description

WORD Flags This field must be zero.
WORD ClassType The only legal values are CCTCT_JCW and CCTCT_JCDW.
The actual type of a class is determined as follows:
If the class has a ClassType of type "CCTCT_JCW", the class type is "JCW."
If the class has a ClassType of type "CCTCT_JCDW", the class type is "JCDW."
All other situations are illegal.

WORD CLSIDIndex If ClassType is not CCTCT_JCW, the contents of the field must 0xffff.
If the ClassType is CCTCT_JCW, and the CLSIDIndex is not 0xffff, it must indicate a valid index into the GuidPool. The GUID corresponding to this index will be used as the CLSID of the COM object to load when an instance of this class is created using the "new" operator.

Restrictions:
If the class type is CCTCT_JCW, the access flags for the class must be a subset of:

ACC_PUBLIC
ACC_FINAL
ACC_ABSTRACT

If the class type is CCTCT_JCDW, the access flags for the class must be a subset of:

ACC_PUBLIC
ACC_FINAL (required)

The class's superclass must be java.lang.Object.
If the class type is CCTCT_JCDW, the ACC_FINAL access flag must be present, and all fields defined by the class must have a COM_MapsTo.

COM_GuidPool

typedef struct {
    WORD        nGuids;         // # of guids in table
    // GUID     aGuid[nGuids];
} CGP_Attr;
This attribute, or attribute level Class, stores IIDs and CLSIDs.
This attribute stores IIDs and CLSIDs that are referenced by index from the MethodPool. Valid indices range from 0 inclusive to nGuids exclusive. The index 0xffff is reserved to indicate the "null" index. Hence, the GuidPool can contain a maximum of 65535 guids.
Parameter Description

WORD nGuids This field indicates the number of GUIDs defined in this table.
GUID aGuid[nGuids]
This array stores the actual GUID representations. A GUID is a 16-byte integer that is subdivided into fields as follows:
struct _GUID { DWORD Data1; WORD Data2; WORD Data3; BYTE Data4[8]; }

Each field is stored in LITTLE-ENDIAN format in the class file. This is an exception from the normal rule that all integers are stored in Big-Endian.
Restrictions:
The class access flags must be a subset of:

ACC_PUBLIC
ACC_FINAL
ACC_INTERFACE
ACC_ABSTRACT

COM_MethodPool

typedef struct {
    WORD        nFuncs;         // # of functions in table
    // CFuncDesc aCFunc[nFuncs]
} CMP_Attr;
This attribute, of attribute level Class, stores distilled typelib information.
This attribute stores the "method signatures" of the COM methods that are invoked by and implemented by the Java methods in the .CLASS file. These "signatures" (CFuncDesc structures) are referenced by index by other attributes in the class. Valid indices range from 0 inclusive to nFuncs exclusive. The index 0xffff is reserved to indicate the "null" index.

Parameter Description

WORD nFuncs; This field indicates the number of CFuncDesc structures defined in this table.
CFuncDesc aFuncDesc[nFuncs] This array stores the actual CFuncDesc structures. The CFuncDesc structures are variable-sized structures.

Restrictions:
The class access flags must be a subset of:

ACC_PUBLIC
ACC_FINAL
ACC_INTERFACE
ACC_ABSTRACT

Though the CFuncDesc structure allows you to specify an IID for individual CFuncDesc, the Virtual Machine requires that all CFuncDesc structures in a .CLASS file reference the same IID in the CGuidPool.
(This restriction does not apply to IIDs embedded in the CTypeDesc structures within the parameter arrays and return types of the CFuncDesc structures.)

CTypeDesc

typedef struct {
    BYTE        Type;       //TD_* value
    BYTE        Flags;      //TDF_* flags
    union {
        WORD    IIDIndex;   // (for TD_INTF only)
        WORD    SizeIndex;  // (for TD_STRUCT only)
    };
} CTypeDesc;
This structure describes the type of a parameter or return value of a COM method.
Parameter Description

BYTE Type Must a member of the TD_* enumeration below. Supported types are grouped as follows:

Void

TD_VOID No value. Only valid as a return type.

Integral

TD_I1 Signed 8-bit

TD_I2 Signed 16-bit

TD_I4 Signed 32-bit

TD_I8 Signed 64-bit

TD_U1 Unsigned 8-bit

TD_U2 Unsigned 16-bit

TD_U4 Unsigned 32-bit

TD_U8 Unsigned 64-bit

Floating point

TD_R4 32-bit float

TD_R8 64-bit float

Pointer

TD_PTR Value is a pointer to some data structure.

Struct

TD_STRUCT Value is a structure that is being passed by value.

Interface

TD_INTF Value is an IUnknown derivative.

String

TD_JSTR Value is a BSTR (OLE Automation.)

Array

TD_JARR Value points to the first element of a fixed-sized array.
BYTE Flags
The flags are grouped into in/out flags and thread-model flags.
In/Out:
If the CTypeDesc is used to describe a parameter, the flags must specify one of TD_IN, TD_OUT or TD_INOUT. For all types other than TD_PTR, TD_JSTR and TD_JARR, the value of this subflag must be TD_IN.
If the CTypeDesc is used to describe a return value or a MapsTo type, this subflag must be set to zero.
Thread Marshaling Mode:
This subflag is meaningful only for the TD_INTF type. For all others, it must be set to zero. This subflag indicates the desired thread marshaling mode of the interface pointer. If the Virtual Machine creates a JCW to represent this COM interface, it will do the appropriate marshaling. If this TypeDesc is being used to marshal to a Java class that is not a JCW, this subflag must be have the value 0.
The Virtual Machine supports two marshaling modes:

TDF_NOMARSHAL COM methods invoked through JCW methods will occur on the calling thread. This mode is most suitable for thread-safe COM objects. If the object is not thread-safe, and this mode is used, the caller must restrict calls to the JCW to the thread on which the JCW was received.
TDF_AUTOMARSHAL COM methods invoked through JCW methods will be marshaled by the Virtual Machine to the thread on which the JCW was created. This allows non-threadsafe COM objects to be invoked from multiple Java threads without explicit marshaling.

The marshaling mode is a property of an instance of a JCW class, not of the JCW class itself.
In certain cases, the Virtual Machine may produce a Java object that assumes a different marshaling mode than is indicated by this subflag. This can happen if the interface pointer had been previously marshaled to Java through another method whose parameter was flagged with the less restrictive marshaling mode. It can also happen if the incoming interface pointer was created by the Virtual Machine itself (these interface pointers are all thread-safe.)
union { WORD IIDIndex; WORD SizeIndex; }

For types other than TD_STRUCT, TD_JARR and TD_INTF, this union must be set to zero.
If the type is TD_STRUC, this field must be set to an index into the constant-pool: the constant pool item must be type CP_Integer and must indicate the size of the struct in bytes.
If the type is TD_JARR, this field must contain the expected number of elements in the array. TD_JARR cannot be used to pass variable-sized arrays.
If the type is TD_INTF, this field must be set to a valid index into the GuidPool. 0xffff (the "null" index) is not valid.

CVtblMethod

typedef struct {
    WORD        IIDIndex;
    WORD        VtblIndex;
    WORD        nArguments;
    WORD        wRetValParameter;   // -1 means none
    CTypeDesc   RetType;
    // Followed by array of CTypeDesc's for parameters
    CTypeDesc   aParamType[1];
} CVtblMethod;
This structure describes a vtable-based method in a COM interface. References to this structure can appear in both ExposedAs_Group attributes and ProxiesTo attributes.

Parameter Description

WORD IIDIndex A valid index into the GuidPool that describes the IID of the COM interface that implements this method. 0xffff is not valid here.
WORD VtblIndex Denotes which vtable element the method occupies. The values 0, 1 and 2 are not legal here since these correspond to the IUnknown methods which cannot be overridden. In addition, if the method pool contains CDispMethod structures using the same IID, values 3,4,5,6 must be avoided (as they correspond to IDispatch methods which are supplied by the Virtual Machine.)
WORD nArguments The number of parameters in the aParamType element. This count does not include the automatic "this" parameter passed to all COM methods.
If the wRetValParameter element is 0xffff, this count must match the number of parameters in the corresponding Java signature exactly. Otherwise, the count must be exactly one greater than the corresponding Java signature.
WORD wRetValParameter If this element contains a value other than 0xffff, it must contains a value between 0 (inclusive) and nArguments (exclusive). This indicates that the parameter whose index is equal to wRetValParameter is actually a pointer through which the method returns its "true" return value. The aParamType for this parameter must indicate the type of the buffer (the "pointer to" is implicit), and the RetType must be TD_VOID. In addition, the return type of the Java method sig must be compatible with the retval parameter.
If this COM method is invoked from Java, the Virtual Machine will supply a return value buffer of the appropriate type to the COM method. Upon a successful return from the COM method, (see CFuncDesc.Flags for what constitutes a successful return).
If Java is used to implement this COM method, the Virtual Machine will remove the retval pointer parameter from the list of arguments presented to the Java method. When the Java method returns, the Virtual Machine will convert the Java method's return value to COM representation, then write it to the retval buffer passed in from COM. The Virtual Machine will then create a COM return value that indicates success (see CFuncDesc.Flags for what constitutes a successful return.)
CTypeDesc RetType Describes the return type. This type must be TD_VOID if wRetValParameter contains a value other than 0xffff, or if CFuncDesc.Flags has the CMDF_HRESULT_RETVAL bit set.
CTypeDesc aParamType[nArguments] Describes the parameter of each COM method.

Remarks:
For vtable methods, the Virtual Machine supports the following pairings between Java and COM types.

Java COM As return type Restrictions

Any integral Any integral Yes

Boolean TD_I4 or TD_U4 Yes

float TD_R4 Yes

double TD_R8 Yes

JCDW TD_PTR Yes [1]

JCDW TD_STRUCT No

java.lang.String TD_JSTR Yes

object TD_INTF Yes [2]

array of integrals TD_JARR No

array of floats TD_JARR No

array of bools TD_JARR No

array of java.lang.String TD_JARR No

array of objects TD_JARR No [2]

[1] JCDWs that have embedded Java object types may not be used as return types.

[2] The Java object type must be declared as a Java interface, JCW class or java.lang.Object.

These values intentionally match the VT_* enum values that are allowed in a VARIANT.

VTD_EMPTY
VTD_NULL
VTD_I2
VTD_I4
VTD_R4
VTD_R8
VTD_CY
VTD_DATE
VTD_BSTR
VTD_DISPATCH
VTD_ERROR
VTD_BOOL
VTD_VARIANT
VTD_UNKNOWN
VTD_UI1

Modifiers to VTD_ types. These do not have the same values as their VT_* equivalents because those values don't fit in a byte.

VTD_BYREF
VTD_ARRAY

CVarTypeDesc

typedef struct {
    BYTE        type;         //VTD_* value
    WORD        optname;      //(0 or constant-pool index to utf8)
    BYTE        Flags;        // TDF_* values
} CVarTypeDesc;
Describes the type of a single parameter or return value to an IDispatch method.

Parameter Description

BYTE type This field contains a "compressed VARTYPE" value, defined by the VTD_* values.
WORD optname If nonzero, this field must be a constant-pool index to a CP_Utf8 which gives the name of the parameter. This field is optional.
WORD Flags See the description for CFuncDesc.Flags. The same values and semantics apply.

CDispMethod

typedef struct {
    WORD           IIDIndex;
    DWORD          Dispid;
    WORD           disptype;    
    WORD           dispname;    
    WORD           nArguments;
    CVarTypeDesc   RetType;
    // Followed by array of CVarTypeDesc's for parameters
    CVarTypeDesc   aParamType[1];
} CDispMethod;
This structure describes an OLE Automation method or property.

Parameter Description

WORD IIDIndex This field must be a valid index into the GUID pool and denotes the IID (typically IID_IDispatch, but can be any interface that derives from IDispatch) through which this method is exposed.
WORD disptype Describes the dispmember type. One of:

DISPATCH_PROPERTYGET
DISPATCH_PROPERTYPUT
DISPATCH_PROPERTYPUTREF
DISPATCH_METHOD

WORD dispname If this field is nonzero, it must be a valid index into constant-pool and the index must reference a CP_Utf8 which provides the name of the method. This field is required only if the CDispMethod is referenced by an ExposedAs_Group attribute.
WORD nArguments Number of arguments.
CVarTypeDesc RetType Describes the type of the return value.
CVarTypeDesc aParamType[nArguments] Describes the type of the return value.

Remarks:
For Dispatch methods, the Virtual Machine supports the following pairings between Java and COM types. Because IDispatch::Invoke relies on VariantChangeType to convert a wide variety of types to another, the actual possibilities are larger than are represented here.

Java Variant As return type

Any integral Any integral Yes

Any float Any float Yes

One element array of:

  short VT_BYREF|VT_I2 No

  int VT_BYREF|VT_I4 No

  float VT_BYREF|VT_R4 No

  double VT_BYREF|VT_R8 No

  byte VT_BYREF|VT_UI1 No

Object/interface VT_BYREF|VT_UNKNOWN No

Object/interface VT_BYREF|VT_DISPATCH No

java.lang.String VT_BYREF|VT_BSTR No

Object or interface VT_UNKNOWN Yes

Object or interface VT_DISPATCH Yes

java.lang.String VT_BSTR Yes

CFuncDesc

typedef struct {
    WORD        cbSize;         // size of entire CFuncDesc in bytes
    WORD        Flags;          // CMDF_* values
    union {
        CVtblMethod mvm;
        CDispMethod mdm;
    };
} CFuncDesc;
This structure describes a single method in the method pool.

Parameter Description

WORD cbSize The size of the entire CFuncDesc (including the cbSize field) in bytes.
WORD Flags One of these values:

CMDF_DISPATCH This flag indicates that the function is a Dispatch method.
CMDF_HRESULT_RETVAL This flag may not be used together with CMDF_DISPATCH. This flag indicates that the return type of the method is an HRESULT and that it is to be mapped to an exception on the Java side.
If this flag is used, the declared type of the RetVal must be TD_VOID.
When this flag is on, the Virtual Machine will treat all return values from COM objects as hresults and will throw a Java exception (details TBD) if the hresult is not S_OK.
Conversely, the Virtual Machine will map all uncaught exceptions from Java code into a failing HRESULT, and will supply a return value of S_OK otherwise.

COM_ExposedAs_Group

typedef struct _COM_ExposedAs_Group {
    WORD       Flags;           //none defined
    WORD       nExposedAs;
    // followed by array of CExposedAs's.
} CEAG_Attr;
This attribute, of attribute level Method, is a collection of ExposedAs structures, each of which causes the Java method to be exposed as a COM method.

Parameter Description

WORD Flags Must be 0.
WORD nExposedAs Number of ExposedAs attributes that follow.
CEA ExposedAs[nExposedAs] Array of exposed as.

Restrictions:
The access flags for the method must be a subset of:

ACC_PUBLIC
ACC_PRIVATE
ACC_PROTECTED
ACC_FINAL
ACC_SYNCHRONIZED
ACC_NATIVE
ACC_ABSTRACT

The class may not have a ClassType attribute.

_COM_ExposedAs

typedef struct _COM_ExposedAs {
    WORD        Flags;
    WORD        MethodPoolIndex;
} CEA;
Each ExposedAs structure causes the Java method to be exposed as a COM method.

Parameter Description

WORD Flags Must be 0.
WORD MethodPoolIndex Must be a valid index into the MethodPool.

COM_ProxiesTo

typedef struct _COM_ProxiesTo {
    WORD        CP_Flags;
    WORD        MethodPoolIndex;
} CPT_Attr;
This attribute, of attribute level Method, denotes that the Java method is implemented using COM.

Parameter Description

WORD CP_Flags Must be 0.
WORD MethodPoolIndex Must be a valid index into the MethodPool.

Restrictions:
The access flags for the method must be a subset of:

ACC_PUBLIC
ACC_PRIVATE
ACC_PROTECTED
ACC_FINAL
ACC_NATIVE (required)
ACC_ABSTRACT (on interfaces only)

COM_MapsTo

typedef struct _COM_MapsTo {
    WORD        Flags;      // MTF_* values
    WORD        wPad;
    DWORD       dwOffset;
    CTypeDesc   typedesc;
} CMT_Attr;
This attribute, of attribute level Field, denotes that the data for the field is actually stored in externally allocated memory.

Parameter Description

WORD Flags Can be this value:

MTF_AUTOOFFSET: If this flag is set, dwOffset must be 0 and the offset will be computed by the Virtual Machine for the hosting platform. This allows the structure definition to move freely between platforms.

Every MapsTo in a .CLASS file must use the same setting for MTF_AUTOOFFSET.
The auto-packing algorithm for the x86 platform is the ZP4 (DWORD-aligned) packing order.
WORD wPad Must be 0
DWORD dwOffset The offset in bytes within the external data structure. If MTF_AUTOOFFSET is on, this field has no meaning and must be set to 0.
CTypeDesc typedesc Describes the native type of the field..

Restrictions:
The access flags for the field must be a subset of:

ACC_PUBLIC
ACC_PRIVATE
ACC_PROTECTED
ACC_FINAL

Level	Name	Description
Class	COM_ClassType	Denotes the implementation language
Class	COM_GuidPool	Stores IIDs and CLSIDs
Class	COM_MethodPool	Stores distilled typelib information
Method	COM_ExposedAs_Group	Exposes a Java method to COM
Method	COM_ProxiesTo	Exposes a COM method to Java
Field	COM_MapsTo	Exposes external data to Java

Parameter	Description
WORD Flags	This field must be zero.
WORD ClassType	The only legal values are CCTCT_JCW and CCTCT_JCDW. The actual type of a class is determined as follows: If the class has a ClassType of type "CCTCT_JCW", the class type is "JCW." If the class has a ClassType of type "CCTCT_JCDW", the class type is "JCDW." All other situations are illegal.
WORD CLSIDIndex	If ClassType is not CCTCT_JCW, the contents of the field must 0xffff. If the ClassType is CCTCT_JCW, and the CLSIDIndex is not 0xffff, it must indicate a valid index into the GuidPool. The GUID corresponding to this index will be used as the CLSID of the COM object to load when an instance of this class is created using the "new" operator.

Parameter	Description
WORD nGuids	This field indicates the number of GUIDs defined in this table.
GUID aGuid[nGuids]	This array stores the actual GUID representations. A GUID is a 16-byte integer that is subdivided into fields as follows: struct _GUID { DWORD Data1; WORD Data2; WORD Data3; BYTE Data4[8]; } Each field is stored in LITTLE-ENDIAN format in the class file. This is an exception from the normal rule that all integers are stored in Big-Endian.

Parameter	Description
WORD nFuncs;	This field indicates the number of CFuncDesc structures defined in this table.
CFuncDesc aFuncDesc[nFuncs]	This array stores the actual CFuncDesc structures. The CFuncDesc structures are variable-sized structures.

Parameter	Description
WORD IIDIndex	A valid index into the GuidPool that describes the IID of the COM interface that implements this method. 0xffff is not valid here.
WORD VtblIndex	Denotes which vtable element the method occupies. The values 0, 1 and 2 are not legal here since these correspond to the IUnknown methods which cannot be overridden. In addition, if the method pool contains CDispMethod structures using the same IID, values 3,4,5,6 must be avoided (as they correspond to IDispatch methods which are supplied by the Virtual Machine.)
WORD nArguments	The number of parameters in the aParamType element. This count does not include the automatic "this" parameter passed to all COM methods. If the wRetValParameter element is 0xffff, this count must match the number of parameters in the corresponding Java signature exactly. Otherwise, the count must be exactly one greater than the corresponding Java signature.
WORD wRetValParameter	If this element contains a value other than 0xffff, it must contains a value between 0 (inclusive) and nArguments (exclusive). This indicates that the parameter whose index is equal to wRetValParameter is actually a pointer through which the method returns its "true" return value. The aParamType for this parameter must indicate the type of the buffer (the "pointer to" is implicit), and the RetType must be TD_VOID. In addition, the return type of the Java method sig must be compatible with the retval parameter. If this COM method is invoked from Java, the Virtual Machine will supply a return value buffer of the appropriate type to the COM method. Upon a successful return from the COM method, (see CFuncDesc.Flags for what constitutes a successful return). If Java is used to implement this COM method, the Virtual Machine will remove the retval pointer parameter from the list of arguments presented to the Java method. When the Java method returns, the Virtual Machine will convert the Java method's return value to COM representation, then write it to the retval buffer passed in from COM. The Virtual Machine will then create a COM return value that indicates success (see CFuncDesc.Flags for what constitutes a successful return.)
CTypeDesc RetType	Describes the return type. This type must be TD_VOID if wRetValParameter contains a value other than 0xffff, or if CFuncDesc.Flags has the CMDF_HRESULT_RETVAL bit set.
CTypeDesc aParamType[nArguments]	Describes the parameter of each COM method.

Java	COM	As return type	Restrictions
Any integral	Any integral	Yes
Boolean	TD_I4 or TD_U4	Yes
float	TD_R4	Yes
double	TD_R8	Yes
JCDW	TD_PTR	Yes	[1]
JCDW	TD_STRUCT	No
java.lang.String	TD_JSTR	Yes
object	TD_INTF	Yes	[2]
array of integrals	TD_JARR	No
array of floats	TD_JARR	No
array of bools	TD_JARR	No
array of java.lang.String	TD_JARR	No
array of objects	TD_JARR	No	[2]
[1] JCDWs that have embedded Java object types may not be used as return types.
[2] The Java object type must be declared as a Java interface, JCW class or java.lang.Object.

Parameter	Description
BYTE type	This field contains a "compressed VARTYPE" value, defined by the VTD_* values.
WORD optname	If nonzero, this field must be a constant-pool index to a CP_Utf8 which gives the name of the parameter. This field is optional.
WORD Flags	See the description for CFuncDesc.Flags. The same values and semantics apply.

Java	Variant	As return type
Any integral	Any integral	Yes
Any float	Any float	Yes
One element array of:
short	VT_BYREF\|VT_I2	No
int	VT_BYREF\|VT_I4	No
float	VT_BYREF\|VT_R4	No
double	VT_BYREF\|VT_R8	No
byte	VT_BYREF\|VT_UI1	No
Object/interface	VT_BYREF\|VT_UNKNOWN	No
Object/interface	VT_BYREF\|VT_DISPATCH	No
java.lang.String	VT_BYREF\|VT_BSTR	No
Object or interface	VT_UNKNOWN	Yes
Object or interface	VT_DISPATCH	Yes
java.lang.String	VT_BSTR	Yes

Parameter	Description
WORD CP_Flags	Must be 0.
WORD MethodPoolIndex	Must be a valid index into the MethodPool.