Microsoft SDK for Java

COM_MapsTo

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.

Restrictions

The access flags for the field must be a subset of ACC_PUBLIC, ACC_PRIVATE, ACC_PROTECTED, or ACC_FINAL.

Attribute Elements

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]) */

Remarks

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

© 1999 Microsoft Corporation. All rights reserved. Terms of use.