Microsoft SDK for Java

How Data Types are Marshaled

The Microsoft virtual machine (Microsoft VM) infers the native type of each parameter and the return value from the declared (compile-time) Java type of the parameter. For example, a parameter declared as a Java integer is passed as a 32-bit integer; a parameter declared as a Java String object is passed as a null-terminated string, and so forth. There are no invisible attributes that provide information about the native types.

Some Java data types don't map exactly to C/C++. Built-in data types map closely, but there are some differences depending on whether the data element is a parameter to a function or a field embedded in a structure.

Strings, structures, and pointers all require special handling. Polymorphic callbacks and parameters require special handling as well. (Polymorphic types are those that are interpreted as different types depending on the situation.)

The following sections describe in detail how the Java data types map to native data types.

Marshaling Basic Scalar Types describes the mappings for int, byte, short, long, float, and double.

Marshaling Chars explains the mapping of the char data type.

Marshaling Booleans explains the mapping of the boolean data type.

Marshaling Strings explains how to pass and receive strings.

Marshaling Arrays explains how to pass arrays of scalars.

Structures and J/Direct explains how to use the @dll.struct directive to pass and receive structures and how to use @dll.structmap to embed fixed-sized arrays within structures.

Pointers and Java explains how to handle DLLs that have multiple return values and how to read and write data through raw pointers.

Polymorphic Parameters explains how to simulate polymorphic parameters.

Callbacks explains how to declare and invoke a DLL function that takes a Callback parameter and how to embed a Callback inside a structure.

The following two tables list the native type that corresponds to each Java type. The first table describes the mappings for parameters and return values in J/Direct methods. The second table shows the mappings used for fields within @dll.struct classes.

Mappings for Parameter and Return Values

Java Native Notes/Restrictions
byte BYTE or CHAR  
short SHORT or WORD
int INT, UINT, LONG, ULONG, or DWORD
char TCHAR
long __int64, DWORDLONG A C or C++ long is 32 bits; a Java long is 64 bits.
float float  
double double
boolean BOOL
String LPCTSTR Not allowed as return value, except in ole mode. In ole mode, String maps to LPWSTR. The Microsoft VM frees the string by using CoTaskMemFree.
StringBuffer LPTSTR Not allowed as return value. Set the StringBuffer capacity large enough to hold the largest string that the DLL function can generate.
byte[] BYTE*  
short[] WORD*
char[] TCHAR*
int[] DWORD*
float[] float*
double[] double*
long[] __int64*
boolean[] BOOL[]
Interface[], where Interface has an @com.interface directive. Interface ** Use jactivex or a similar tool to generate an interface file.
String[] BSTR *  
Array of @dll.struct or @com.struct classes Array of pointers to the struct
Object pointer to struct In ole mode, an IUnknown* is passed instead.
Interface, where Interface has an @com.interface directive. Interface * Use jactivex or a similar tool to generate an interface file.
com.ms.com.SafeArray SAFEARRAY* Not allowed as a return value.
com.ms.com._Guid GUID,IID,CLSID  
com.ms.com.Variant VARIANT*
@dll.struct classes pointer to struct
@com.struct classes pointer to struct
void VOID As a return value only.
com.ms.dll.Callback function pointer As a parameter only.

Most of the data type mappings are what you'd expect—byte to char, int to int, long to _int64, boolean to BOOL, and so on. But a few are different depending on whether the data is a parameter or a member of a structure declared with @dll.struct, as shown in the following table.

There are no unsigned data types (except char) in Java, so be careful when operating on unsigned values. Note that long is 64 bits in Java, not 32 as in C/C++.

When passed as parameters, arrays map to pointers to the element type. For instance, byte [] in Java maps to CHAR* in C/C++. There are restrictions on return values, especially Strings and StringBuffers.

Mappings Used with @dll.struct

Java Native
byte BYTE or CHAR.
char TCHAR.
short SHORT or WORD.
int INT, UINT, LONG, ULONG or DWORD.
long __int64.
float float.
double double.
boolean BOOL.
boolean[] Nested array of BOOL.
String Pointer to a string, or an embedded fixed-size string.
Class marked with @dll.struct Nested structure.
Class marked with @dll.struct and @dll.structmap that declares type=PTR Pointer to struct.
char[] Nested array of TCHAR.
byte[] Nested array of BYTE.
short[] Nested array of SHORT.
int[] Nested array of LONG.
long[] Nested array of __int64.
float[] Nested array of floats.
double [] Nested array of doubles.

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