The COM_MapsTo attribute denotes that the data for the field is actually stored in externally allocated memory. This attribute describes how the fields of a JCDW or JCW map to offsets in the underlying data structure.
Attribute Level | Generated By Directives |
Field | @com.struct @com.structmap @dll.struct @dll.structmap |
COM_MapsTo_attribute { u2 attribute_name_index; u4 attribute_length; u2 Flags; u2 wPad; u4 dwOffset; MCTypeDesc typedesc; }
The C structures MCMapsTo and MCTypeDesc, declared in comattr.h, define the layout of this attribute for use in C/C++ programs.
The access flags for the field must be a subset of ACC_PUBLIC, ACC_PRIVATE, ACC_PROTECTED, or ACC_FINAL.
attribute_name_index
This value must be a valid index into the constant_pool table. The constant_pool entry at that index must be the CONSTANT_Utf8_info structure representing the string "COM_MapsTo".
attribute_length
This value indicates the length of this attribute, excluding the initial six bytes, and must be 12.
Flags
The Flags for the COM_MapsTo attribute are as follows.
Flag | Meaning |
MTF_AUTOOFFSET | If this flag is set, dwOffset must be 0 and the offset will be computed by the Microsoft 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. A current offset is kept while determining the offset of fields. It is initialized to zero. |
wPad | Must be 0 (zero). |
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. |
MCTypeDesc typedesc | Describes the native type of the field. |
The @com.struct directive that generates this attribute has the following syntax:
/** @com.struct([ansi | unicode | auto], [pack=1 | 2 | 4 | 8], [noAutoOffset], [safe], [safeAddFlags=integer]) */
The COM_MapsTo attribute uses an MCTypeDesc structure to indicate the type of the field and other attributes. The MCTypeDesc structure does not attempt to describe the type of the corresponding Java data types. This same structure is also used by other attributes (describing parameters and return values for methods, for example) and some values and interpretations are attribute-specific.
The possible values for the Type enumeration applicable to the COM_MapsTo attribute describing a field are shown in the following table.
Type Enumeration | Value | Comments |
TD_I1 | 0x01 | A signed 8-bit integer. |
TD_I2 | 0x02 | A signed 16-bit integer. |
TD_I4 | 0x03 | A signed 32-bit integer. |
TD_I8 | 0x04 | A signed 64-bit integer. |
TD_U1 | 0x05 | An unsigned 8-bit integer. |
TD_U2 | 0x06 | An unsigned 16-bit integer. |
TD_U4 | 0x07 | An unsigned 32-bit integer. |
TD_U8 | 0x08 | An unsigned 64-bit integer. |
TD_R4 | 0x09 | A 32-bit IEEE floating value. |
TD_R8 | 0x0a | A 64-bit IEEE floating value. |
TD_PTR | 0x0b | A pointer to some data structure. |
TD_INTF | 0x0d | An interface (an IUnknown derivative). |
TD_JSTR | 0x0e | A Java string. |
TD_CUSTOM | 0x11 | A custom data type. |
TD_CUSTOMBYREF | 0x12 | A custom data type passed by reference. |
TD_CUSTOMBYVAL | 0x13 | A custom data type passed by value. |
TD_SYSCHAR | 0x15 | A Unicode character or an ANSI character, depending on platform setting. |
TD_SYSFIXEDSTRING | 0x16 | A fixed ANSI or Unicode string. The SizeIndex item of the MCTypeDesc structure must be set to the number of characters, including the null terminator. |
TD_FIXEDARRAY | 0x17 | A fixed size array of scalars. The SizeIndex item of the MCTypeDesc structure must be set to the number of elements in the array. |
TD_OBJECT | 0x18 | A field type of L<something>. This field should be treated as embedded struct and must be a JCDW class. |
The Flags item represents a bitmask of options. The possible values for these options applicable to the MCTypeDesc structure used in the COM_MapsTo attribute are shown in the following table.
Flags Options | Value | Comments |
TDF_AUTOMARSHAL | 0x04 | When marshaling an interface field from native memory to a Java representation (JCW field), the current thread will become the home thread for the created JCW. Subsequent access to COM methods invoked through JCW methods on the created JCW will be marshaled by the Microsoft VM to the home thread. This allows non-threadsafe COM objects to be invoked from multiple Java threads without explicit marshaling.
This option is meaningful only for the TD_INTF type. For all others, it must be set to 0 (zero). |
TDF_NOMARSHAL | 0x08 | When marshaling an interface field from native memory to a Java representation (a JCW field), the created JCW will be marked as being free-threaded. COM methods invoked through JCW methods on the created JCW 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.
This option is meaningful only for the TD_INTF type. For all others, it must be set to 0 (zero). |
TDF_USER2 | 0x40 | User-defined. |
TDF_USER1 | 0x80 | User-defined. |
The marshaling mode is a property of an instance of a JCW class, not of the JCW class itself. In certain cases, the Microsoft VM may produce a Java object that assumes a different marshaling mode than this option 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 Microsoft VM itself created the incoming interface pointer (these interface pointers are all thread-safe).