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.
All unused bits in Flag fields must be zero.
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.
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.
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
|
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.
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.
|
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.
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.
|
|
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
|
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.
|
|
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.
typedef struct _COM_ExposedAs {
WORD Flags;
WORD MethodPoolIndex;
} CEA;
Each ExposedAs structure causes the Java method to be exposed as a COM method.
typedef struct _COM_ProxiesTo {
WORD CP_Flags;
WORD MethodPoolIndex;
} CPT_Attr;
Denotes that the Java method is implemented using COM.
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
|
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
|