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