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 Component Object Model (COM) object from Java or expose a Java object as a COM object.

The following attributes must be present.

Level	Name	Description
Class	COM_ClassType	Denotes the implementation language
Class	COM_GuidPool	Stores IIDs and class identifiers (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 unsigned and stored in the .class file 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
Flags	This field must be zero.
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.
CLSIDIndex	If ClassType is not CCTCT_JCW, the contents of the field must be 0xffff. If ClassType is CCTCT_JCW, and the CLSIDIndex is not 0xffff, it must indicate a valid index into the GuidPool. The globally unique identifier (GUID) corresponding to this index will be used as the CLSID of the Component Object Model (COM) object to load when you create an instance of this class by using the new operator.

Restrictions:

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

ACC_ABSTRACT

ACC_FINAL

ACC_PUBLIC

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

ACC_FINAL (required)

ACC_PUBLIC

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;

Stores IIDs and class identifiers (CLSIDs).

Parameter	Description
nGuids	Indicates the number of GUIDs defined in this table.
aGuid	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.

Remarks:

This attribute stores IIDs and CLSIDs that are referenced by index from the MethodPool. Valid indexes 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 65,535 globally unique identifiers (GUIDs).

Restrictions:

The class access flags must be a subset of:

ACC_ABSTRACT

ACC_FINAL

ACC_INTERFACE

ACC_PUBLIC

COM_MethodPool

typedef struct {
    WORD        nFuncs;         // # of functions in table
    // CFuncDesc aCFunc[nFuncs]
} CMP_Attr;

Stores distilled typelib information.

Parameter	Description
nFuncs	Indicates the number of CFuncDesc structures defined in this table.
aCFunc	Stores the actual CFuncDesc structures. The CFuncDesc structures are variable-sized structures.

Remarks:

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 indexes range from 0 inclusive to nFuncs exclusive. The index 0xffff is reserved to indicate the "null" index.

Restrictions:

The class access flags must be a subset of:

ACC_ABSTRACT

ACC_FINAL

ACC_INTERFACE

ACC_PUBLIC

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
Type	Must a member of the following TD_* enumeration. 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.
Flags	Flags are grouped into in/out flags and thread-model flags. In/out: If you use CTypeDesc 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 you use CTypeDesc 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 Java-callable wrapper (JCW), this subflag must be have the value 0. The Virtual Machine supports two marshaling modes: 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. 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. 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 this subflag indicates. This can happen if the interface pointer was previously marshaled to Java through another method whose parameter was flagged with the less-restrictive marshaling mode. It can also happen if the Virtual Machine itself created the incoming interface pointer (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;

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
IIDIndex	Valid index into the GuidPool that describes the IID of the COM interface that implements this method. 0xffff is not valid here.
VtblIndex	Denotes which vtable element the method occupies. The values 0, 1, and 2 are not legal here, because these correspond to the IUnknown interface methods that cannot be overridden. In addition, if the method pool contains CDispMethod structures using the same IID, values 3, 4, 5, and 6 must be avoided (because they correspond to IDispatch interface methods that the Microsoft VM supplies).
nArguments	Number of parameters in the aParamType member. This count does not include the automatic this parameter passed to all COM methods. If the wRetValParameter member 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.
wRetValParameter	If this member contains a value other than 0xffff, it must contain a value between 0 (inclusive) and nArguments (exclusive). This indicates that the parameter whose index equals wRetValParameter is actually a pointer through which the method returns its "true" return value. The aParamType member 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 you use Java 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).
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.
aParamType	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 booleans	TD_JARR	No
array of java.lang.String	TD_JARR	No
array of objects	TD_JARR	No	[2]
[1] You cannot use JCDWs that have embedded Java object types as return types.
[2] You must declare the Java object type 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_BOOL

VTD_BSTR

VTD_CY

VTD_DATE

VTD_DISPATCH

VTD_EMPTY

VTD_ERROR

VTD_I2

VTD_I4

VTD_NULL

VTD_R4

VTD_R8

VTD_UI1

VTD_UNKNOWN

VTD_VARIANT

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

VTD_ARRAY

VTD_BYREF

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 interface method.

Parameter	Description
type	Contains a "compressed VARTYPE" value, defined by the VTD_* values.
optname	If nonzero, this field must be a constant-pool index to a CP_Utf8 that gives the parameter's name. This field is optional.
Flags	One of these values: CMDF_DISPATCH This flag indicates that the function is a Dispatch method. CMDF_HRESULT_RETVAL This flag cannot be used 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.

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;

Describes an OLE Automation method or property.

Parameter	Description
IIDIndex	Must be a valid index into the GUID pool and denotes the IID (typically IID_IDispatch, but can be any interface that derives from the IDispatch interface) through which this method is exposed.
disptype	Describes the dispmember type. One of: DISPATCH_METHOD DISPATCH_PROPERTYGET DISPATCH_PROPERTYPUT DISPATCH_PROPERTYPUTREF
dispname	If this field is nonzero, it must be a valid index into the constant pool and the index must reference a CP_Utf8 that provides the name of the method. This field is required only if CDispMethod is referenced by an ExposedAs_Group attribute.
nArguments	Number of arguments.
RetType	Describes the type of the return value.
aParamType	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;

Describes a single method in the method pool.

Parameter	Description
cbSize	Size of CFuncDesc (including the cbSize member), in bytes.
Flags	One of these values: CMDF_DISPATCH Indicates that the function is a Dispatch method. CMDF_HRESULT_RETVAL This flag cannot be used 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
Flags	Must be zero.
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_ABSTRACT

ACC_FINAL

ACC_NATIVE

ACC_PRIVATE

ACC_PROTECTED

ACC_PUBLIC

ACC_SYNCHRONIZED

The class cannot 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
Flags	Must be zero.
MethodPoolIndex	Must be a valid index into the MethodPool.

COM_ProxiesTo

typedef struct _COM_ProxiesTo {
    WORD        CP_Flags;
    WORD        MethodPoolIndex;
} CPT_Attr;

Denotes that the Java method is implemented using COM.

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

Restrictions:

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

ACC_ABSTRACT (on interfaces only)

ACC_FINAL

ACC_NATIVE (required)

ACC_PRIVATE

ACC_PROTECTED

ACC_PUBLIC

COM_MapsTo

typedef struct _COM_MapsTo {
    WORD        Flags;      // MTF_* values
    WORD        wPad;
    DWORD       dwOffset;
    CTypeDesc   typedesc;
} CMT_Attr;

Denotes that data for the field is stored in externally allocated memory.

Parameter	Description
Flags	Can be this value: MTF_AUTOOFFSET: If this flag is set, dwOffset must be zero and the Virtual Machine will compute the offset 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.
wPad	Must be zero.
dwOffset	Offset in bytes within the external data structure. If MTF_AUTOOFFSET is on, this field has no meaning and must be set to zero.
typedesc	Describes the native type of the field.

Restrictions:

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

ACC_FINAL

ACC_PRIVATE

ACC_PROTECTED

ACC_PUBLIC