Working with MS VM
 In this topic

*Data Type Sizes and Alignment

 

Microsoft VM    PreviousVM
Overview of COM Attributes for Java Class Files     Previous VM

 


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.

ParameterDescription
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).

ParameterDescription
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.

ParameterDescription
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.

ParameterDescription
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.

ParameterDescription
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.

ParameterDescription
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.

ParameterDescription
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.

ParameterDescription
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.

ParameterDescription
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.

ParameterDescription
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.

ParameterDescription
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.

ParameterDescription
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

Top © 1998 Microsoft Corporation. All rights reserved. Terms of use.