Class DllLib

public class DllLib
{
  // Fields
  public static final int systemDefaultCharSize;

  // Methods
  public static int addrOf(int root);
  public static int addrOfPinnedObject(int nHandleIndex);
  public static int allocCoTaskMem(int cb);
  public static int allocHGlobal(int cb);
  public static void copy(byte jasrc[], int elemidx, int pdst,
        int nelems);
  public static void copy(char jasrc[], int elemidx, int pdst,
        int nelems);
  public static void copy(short jasrc[], int elemidx, int pdst, int
        nelems);
  public static void copy(int jasrc[], int elemidx, int pdst,
        int nelems);
  public static void copy(long jasrc[], int elemidx, int pdst,
        int nelems);
  public static void copy(float jasrc[], int elemidx, int pdst, int
        nelems);
  public static void copy(double jasrc[], int elemidx, int pdst,
        int nelems);
  public static void copy(Object jasrc, int ofs, int pdst, int cb);
  public static void copy(int psrc, byte jadst[], int elemidx,
        int nelems);
  public static void copy(int psrc, char jadst[], int elemidx,
        int nelems);
  public static void copy(int psrc, short jadst[], int elemidx, int
        nelems);
  public static void copy(int psrc, int jadst[], int elemidx,
        int nelems);
  public static void copy(int psrc, long jadst[], int elemidx,
        int nelems);
  public static void copy(int psrc, float jadst[], int elemidx, int
        nelems);
  public static void copy(int psrc, double jadst[], int elemidx,
        int nelems);
  public static void copy(int psrc, Object jadst, int ofs, int cb);
  public static void freeCoTaskMem(int ptr);
  public static void freeHGlobal(int hglobal);
  public static final int getLastWin32Error();
  public static void freePinnedHandle(int nHandleIndex);
  public static int getPinnedHandle(Object obj);
  public static Object getPinnedObject(int nHandleIndex);
  public static boolean isStruct(Class structCls);
  public native static boolean isStruct(Field structField);
  public static int numParamBytes(Method m);
  public native static int offsetOf(Field structField);
  public static int offsetOf(Class structCls,
        String fieldName) throws SecurityException;
  public static native void prelink(Method method);
  public static native void propagateStructFields(Object structObj, boolean fromNative);
  public static void prelinkAll(Class cls);
  public static String ptrToString(int ptr);
  public static String ptrToStringAnsi(int ptr);
  public static String ptrToStringUni(int ptr);
  public static Object ptrToStruct(Class structClass, int ptr);
  public static native byte read1(Object ptr, int ofs);
  public static native byte read1(int ptr, int ofs);
  public static byte read1(int ptr);
  public static native short read2(Object ptr, int ofs);
  public static native short read2(int ptr, int ofs);
  public static short read2(int ptr);
  public static native int read4(Object ptr, int ofs);
  public static native int read4(int ptr, int ofs);
  public static int read4(int ptr);
  public static native long read8(Object ptr, int ofs);
  public static native long read8(int ptr, int ofs);
  public static long read8(int ptr);
  public static native void release(Object o);
  public native static void resize(Object structObj, int newsize);
  public static int sizeOf(Class structCls);
  public native static int sizeOf(Object structObj);
  public static int stringToCoTaskMem(String s);
  public static int stringToCoTaskMemAnsi(String s);
  public static int stringToCoTaskMemUni(String s);
  public static int stringToHGlobal(String s);
  public static int stringToHGlobalAnsi(String s);
  public static int stringToHGlobalUni(String s);
  public static final void throwWin32Exception();
  public static native void write1(Object ptr, int ofs, byte val);
  public static native void write1(int ptr, int ofs, byte val);
  public static void write1(int ptr, byte val);
  public static native void write2(Object ptr, int ofs, short val);
  public static native void write2(int ptr, int ofs, short val);
  public static void write2(int ptr, short val);
  public static native void write2(Object ptr, int ofs, char val);
  public static native void write2(int ptr, int ofs, char val);
  public static void write2(int ptr, char val);
  public static native void write4(Object ptr, int ofs, int val);
  public static native void write4(int ptr, int ofs, int val);
  public static void write4(int ptr, int val);
  public static native void write8(Object ptr, int ofs, long val);
  public static native void write8(int ptr, int ofs, long val);
  public static void write8(int ptr, long val);
}

This class contains methods for linking to dynamic-link libraries (DLLs). All methods in the DllLib class are static; therefore, you do not need to instantiate this class to use its methods. The methods and fields of the DllLib class provide support for Microsoft® J/Direct™ technology.

J/Direct allows you to specify the auto modifier with the @dll.import directive to call the optimal version of a DLL function, depending on the platform you are using. To find out what version is optimal for your platform, you can examine the systemDefaultCharSize field. This field is set to 1 for ANSI system, and 2 for Unicode systems.

There are several DllLib methods that help you read and write from raw pointers returned by DLL functions. You can use the ptrToStruct method, which casts a raw pointer to a structure, to cast the raw pointer to a reference to a class declared with @dll.struct. For an example that illustrates this technique, see the Raw Pointers section of the J/Direct article.

There are other situations where the ptrToStruct method can be helpful. Since there is no direct support for pointers inside structures, you could represent a structure with an embedded pointer by declaring the pointer field as type int and calling DLL functions to allocate the memory. Then you can call ptrToStruct to map the memory blocks onto @dll.struct classes so that you can initialize the blocks.

The DllLib methods, ptrToStringAnsi, ptrToStringUni, and ptrToString, are used to convert a string to a java.lang.String object when you want to treat a raw pointer as a pointer to a string. The following example shows how you can interpret a raw pointer as a pointer to a Unicode string.

import com.ms.dll.*;

int rawPtr = ...;  // value of rawPtr is returned by a DLL function
String s = DllLib.ptrToStringUni(rawPtr);

The addrOf method can be used to get the address of a callback. For instance, when you want to embed a callback inside a structure, you would call the com.ms.dll.Root.alloc method to wrap the Callback in a root handle. Next, you would pass the root handle to the addrOf method to obtain native address of the callback. Then, you can store the address as an integer.

The getLastWin32Error method helps you obtain the error code set by a DLL function. For an example that shows how to do this, see the Error Code section of the J/Direct article.

The copy methods in DllLib allow you to copy data between various types of Java arrays and raw pointers. You could use these methods to read or write data from raw pointers returned by DLL functions.

Methods

addrOf

public static int addrOf(int root);

Returns the address of a native structure wrapped by an @dll.struct object.

Note To use this method, you must first call the Root.alloc method to wrap the object in a root handle. Then, pass the root handle to the addrOf method. This extra step is required because of the garbage-collected nature of Java. (If the addrOf method took an object directly, there would be nothing to prevent the object from being reclaimed by garbage collection before the returned address could be used.)

Return Value:

Returns the address of the native structure.

Parameter	Description
root	A root handle obtained by calling Root.alloc.

Exceptions:

SecurityException if called by an untrusted applet.

addrOfPinnedObject

public static int addrOfPinnedObject(int nHandleIndex);

Returns the address of the object's data while an object is pinned.

While an address is pinned, it will not be reclaimed by the garbage collector and will not move in memory. You must specifically free this handle by calling freePinnedHandle. For performance reasons, objects should not be pinned for long periods of time. Generally, you will pin an array during some native I/O operation, and then unpin it.

Note Only single-dimension arrays of primitive types can be pinned.

Return Value:

Returns the address of the of the object that is encapsulated by the given pinned handle.

Parameter	Description
nHandleIndex	A pinned handle that is obtained by calling getPinnedHandle.

allocCoTaskMem

public static int allocCoTaskMem(int cb);

Allocates a native memory block by invoking the Win32 function CoTaskMemAlloc.

Return Value:

Returns a pointer to the allocated block.

Parameter	Description
cb	The required size of the memory block (in bytes).

Exceptions:

OutOfMemoryError if allocation fails.

allocHGlobal

public static int allocHGlobal(int cb);

Allocates a native memory block using GlobalAlloc (GMEM_FIXED).

Return Value:

Returns a pointer to the allocated block.

Parameter	Description
cb	The required size of the memory block (in bytes).

Exceptions:

OutOfMemoryError if allocation fails.

copy

public static void copy(byte jasrc[], int elemidx, int pdst, int nelems);

Copies a number of bytes from a Java array to the destination indicated by a raw native pointer. This copy method is range-checked.

Return Value:

No return value.

Parameter	Description
jasrc	The Java array to copy bytes from.
elemidx	The offset that indicates the location in the Java array where the first byte to be copied is located.
pdst	A raw pointer to the destination of the copy.
nelems	The number of bytes to copy.

copy

public static void copy(char jasrc[], int elemidx, int pdst, int nelems);

Copies a number of characters from a Java array to the destination indicated by a raw native pointer. This copy method is range-checked.

Return Value:

No return value.

Parameter	Description
jasrc	The Java array to copy the characters from.
elemidx	The offset that indicates the location in the Java array where the first character to be copied is located.
pdst	A raw pointer to the destination of the copy.
nelems	The number of characters to copy.

copy

public static void copy(short jasrc[], int elemidx, int pdst, int nelems);

Copies a number of short integers from a Java array to the destination indicated by a raw native pointer. This copy method is range-checked.

Return Value:

No return value.

Parameter	Description
jasrc	The Java array to copy the short integers from.
elemidx	The offset that indicates the location in the Java array where the first short integer to be copied is located.
pdst	A raw pointer to the destination of the copy.
nelems	The number of short integers to copy.

copy

public static void copy(int jasrc[], int elemidx, int pdst, int nelems);

Copies a number of integers from a Java array to the destination indicated by a raw native pointer. This copy method is range-checked.

Return Value:

No return value.

Parameter	Description
jasrc	The Java array to copy the integers from.
elemidx	The offset that indicates the location in the Java array where the first integer to be copied is located.
pdst	A raw pointer to the destination of the copy.
nelems	The number of integers to copy.

copy

public static void copy(long jasrc[], int elemidx, int pdst, int nelems);

Copies a number of long integers from a Java array to the destination indicated by a raw native pointer. This copy method is range-checked.

Return Value:

No return value.

Parameter	Description
jasrc	The Java array to copy the long integers from.
elemidx	The offset that indicates the location in the Java array where the first long integer to be copied is located.
pdst	A raw pointer to the destination of the copy.
nelems	The number of long integers to copy.

copy

public static void copy(float jasrc[], int elemidx, int pdst, int nelems);

Copies 32-bit floating-point numbers from a Java array to the destination indicated by a raw native pointer. This copy method is range-checked.

Return Value:

No return value.

Parameter	Description
jasrc	The Java array to copy the floating-point numbers from.
elemidx	The offset that indicates the location in the Java array where the first floating-point number to be copied is located.
pdst	A raw pointer to the destination of the copy.
nelems	The number of floating-point numbers to copy.

copy

public static void copy(double jasrc[], int elemidx, int pdst, int nelems);

Copies 64-bit floating-point numbers (doubles) from a Java array to the destination indicated by a raw native pointer. This copy method is range-checked.

Return Value:

No return value.

Parameter	Description
jasrc	The Java array to copy the doubles from.
elemidx	The offset that indicates the location in the Java array where the first double to be copied is located.
pdst	A raw pointer to the destination of the copy.
nelems	The number of doubles to copy.

copy

public static void copy(Object jasrc, int ofs, int pdst, int cb);

Copies a native structure to the destination indicated by a raw native pointer. The Java object that represents the native structure must have been declared using the @dll.struct compiler directive.

Return Value:

No return value.

Parameter	Description
jasrc	The native structure to copy from.
ofs	The offset that indicates where in the object the first byte to copy is located.
pdst	A raw pointer to the destination of the copy.
cb	The number of bytes to copy.

copy

public static void copy(int psrc, byte jadst[], int elemidx, int nelems);

Copies a number of bytes to a Java array from the source indicated by a raw native pointer. This copy method is range-checked.

Return Value:

No return value.

Parameter	Description
psrc	A raw pointer to the source of the copy.
jadst	The Java array to copy the bytes to.
elemidx	The offset that indicates the location in the Java array where the first byte is copied to.
nelems	The number of bytes to copy.

copy

public static void copy(int psrc, char jadst[], int elemidx, int nelems);

Copies a number of characters to a Java array from the source indicated by a raw native pointer. This copy method is range-checked.

Return Value:

No return value.

Parameter	Description
psrc	A raw pointer to the source of the copy.
jadst	The Java array to copy the characters to.
elemidx	The offset that indicates the location in the Java array where the first character is copied to.
nelems	The number of characters to copy.

copy

public static void copy(int psrc, short jadst[], int elemidx, int nelems);

Copies a number of short integers to a Java array from the source indicated by a raw native pointer. This copy method is range-checked.

Return Value:

No return value.

Parameter	Description
psrc	A raw pointer to the source of the copy.
jadst	The Java array to copy the short integers to.
elemidx	The offset that indicates the location in the Java array where the first short integer is copied to.
nelems	The number of short integers to copy.

copy

public static void copy(int psrc, int jadst[], int elemidx, int nelems);

Copies a number of integers to a Java array from the source indicated by a raw native pointer. This copy method is range-checked.

Return Value:

No return value.

Parameter	Description
psrc	A raw pointer to the source of the copy.
jadst	The Java array to copy the integers to.
elemidx	The offset that indicates the location in the Java array where the first integer is copied to.
nelems	The number of integers to copy.

copy

public static void copy(int psrc, long jadst[], int elemidx, int nelems);

Copies a number of long integers to a Java array from the source indicated by a raw native pointer. This copy method is range-checked.

Return Value:

No return value.

Parameter	Description
psrc	A raw pointer to the source of the copy.
jadst	The Java array to copy the long integers to.
elemidx	The offset that indicates the location in the Java array where the first long integer is copied to.
nelems	The number of long integers to copy.

copy

public static void copy(int psrc, float jadst[], int elemidx, int nelems);

Copies 32-bit floating-point numbers to a Java array from the source indicated by a raw native pointer. This copy method is range-checked.

Return Value:

No return value.

Parameter	Description
psrc	A raw pointer to the source of the copy.
jadst	The Java array to copy the floats to.
elemidx	The offset that indicates the location in the Java array where the first floating-point number is copied to.
nelems	The number of floats to copy.

copy

public static void copy(int psrc, double jadst[], int elemidx, int nelems);

Copies 64-bit floating-point numbers (doubles) to a Java array from the source indicated by a raw native pointer. This copy method is range-checked.

Return Value:

No return value.

Parameter	Description
psrc	A raw pointer to the source of the copy.
jadst	The Java array to copy the doubles to.
elemidx	The offset that indicates the location in the Java array where the first double is copied to.
nelems	The number of doubles to copy.

copy

public static void copy(int psrc, Object jadst, int ofs, int cb);

Copies a number of bytes to a native structure from the source indicated by a raw native pointer. The Java object that represents the native structure must be declared using the @dll.struct compiler directive.

Return Value:

No return value.

Parameter	Description
psrc	A raw pointer to the source of the copy.
jadst	The native structure to copy to.
ofs	The offset that indicates the location in the object where the first byte is copied to.
cb	The number of bytes to copy.

freeCoTaskMem

public static void freeCoTaskMem(int ptr);

Frees a native memory block by invoking the Win32 function CoTaskMemFree. Any global memory handle that has a zero high-order word is safely ignored.

Return Value:

No return value.

Parameter	Description
ptr	The memory block to free.

freeHGlobal

public static void freeHGlobal(int hglobal);

Frees a native memory block by invoking the Win32 function GlobalFree. Any global memory handle that has a zero high-order word is safely ignored.

Return Value:

No return value.

Parameter	Description
hglobal	The global memory handle to free.

freePinnedHandle

public static void freePinnedHandle(int nHandleIndex);

Frees a previously-allocated pinned handle. This necessarily unpins the object (unless it has been pinned multiple times) and invalidates the address (if any) returned by addrOfPinnedHandle for this handle.

Return Value:

No return value.

Parameter	Description
nHandleIndex	The handle of the pinned object to free.

getLastWin32Error

public static final int getLastWin32Error();

Returns the Microsoft® Win32® error code set by the last DLL-imported method (declared with the setLastError modifier) invoked on the current thread.

Note Only DLL methods declared with the setLastError modifier can set error codes.

Return Value:

Returns the last saved Win32 error code.

getPinnedHandle

public static int getPinnedHandle(Object obj);

Pins an object. After pinning an object, you can legally call addrOfPinnedObject to obtain the address of the object's data. While an object is pinned, it will not be reclaimed by the garbage collector and will not move in memory.

You must specifically free this handle via freePinnedHandle. For performance reasons, objects should not be pinned for long periods of time. Generally, you will pin an array during some native I/O operation, and then unpin it.

Note Only single-dimension arrays of primitive types can be pinned.

Return Value:

Returns a handle to the pinned object.

Parameter	Description
obj	The object to be pinned.

getPinnedHandle

public static int getPinnedHandle(Object obj);

Pins an object. After pinning an object, you can legally call addrOfPinnedObject() to obtain the address of the object's data. While an object is pinned, it will not be reclaimed by the GC and will not move in memory.

You must specifically free this handle via freePinnedHandle(). For performance reasons, objects should not be pinned for long amounts of time. Generally, you will pin an array during some native I/O operation, and then unpin it.

Note Only single-dimension arrays of primitive type may be pinned.

Return Value:

Returns a handle to the pinned object.

Parameter	Description
obj	The object to be pinned.

getPinnedHandle

public static int getPinnedHandle(Object obj);

Pins an object. After pinning an object, you can legally call addrOfPinnedObject() to obtain the address of the object's data. While an object is pinned, it will not be reclaimed by the GC and will not move in memory.

You must specifically free this handle via freePinnedHandle(). For performance reasons, objects should not be pinned for long amounts of time. Generally, you will pin an array during some native I/O operation, and then unpin it.

Note Only single-dimension arrays of primitive type may be pinned.

Return Value:

Returns a handle to the pinned object.

Parameter	Description
obj	The object to be pinned.

getPinnedHandle

public static int getPinnedHandle(Object obj);

Pins an object, returning a handle.

After pinning an object, you can legally call addrOfPinnedObject() to obtain the address of the object's data. While an object is pinned, it will not be reclaimed by the GC and will not move in memory.

You must specifically free this handle via freePinnedHandle(). For performance reasons, objects should not be pinned for long amounts of time. Generally, you will pin an array during some native I/O operation, and then unpin it.

Note Only single-dimension arrays of primitive type may be pinned.

Return Value:

Returns a handle to the pinned object.

Parameter	Description
obj	The object to be pinned.

getPinnedObject

public static int getPinnedObject(int handle);

Retrieves the object that is encapsulated by a pinned handle.

Return Value:

Returns the object that is encapsulated by a pinned handle.

Parameter	Description
handle	The pinned handle of the object.

isStruct

public static boolean isStruct(Class structCls);

Determines whether a class represents a native structure.

Return Value:

Returns true if the class represents a native structure; otherwise, returns false.

Parameter	Description
structCls	The class to examine.

isStruct

public native static boolean isStruct(Field structField);

Determines whether a field represents a field in a native structure.

Return Value:

Returns true if the field represents a field in a native structure; otherwise, returns false.

Parameter	Description
structField	The field to examine.

numParamBytes

public static int numParamBytes(Method m);

Prelinks the specified method and returns the number of bytes of memory required to store the method's parameters.

Return Value:

Returns the number of bytes of memory required to store the method's parameters.

Parameter	Description
m	The method to be prelinked.

offsetOf

public native static int offsetOf(Field structField);

Returns the offset (measured in bytes) of a member of a native structure. The class, which is represented by structField.getClass, must have been declared using the @dll.struct compiler directive (or @com.struct).

Note The getClass method is from the java.lang.Object class.

Return Value:

Returns the size of the native structure (in bytes).

Parameter	Description
structField	The field to obtain the offset of.

offsetOf

public static int offsetOf(Class structCls, String fieldName)
        throws SecurityException;

Returns the offset (measured in bytes) of a member of a native structure. The class, which is represented by structCls, must have been declared using the @dll.struct compiler directive (or @com.struct).

Return Value:

Returns the size of the native structure in bytes.

Parameter	Description
structCls	The class declared by using @dll.struct.
fieldName	The name of the field to examine.

Exceptions:

SecurityException if the caller lacks permissions to use the java.lang.reflect API.

prelink

public static native void prelink(Method method);

Preloads the native library and performs a type analysis on an @dll.import method to ensure that the types are compatible with DLL calling. If this method is called multiple times on the same method (or on a method that does not link to a DLL), the call is safely ignored.

Return Value:

No return value.

Parameter	Description
method	The method to prelink.

Remarks:

This work is normally performed on the first call to the @dll.import method. The prelink method can be used to force the type analysis to be done before the first call to the @dll.import method. This can help with performance tuning, debugging, or both.

prelinkAll

public static void prelinkAll(Class cls);

Calls the prelink method on all methods of a class. This method is provided primarily for debugging purposes because it can expose errors in DLL-linked methods.

Return Value:

No return value.

Parameter	Description
cls	The class to prelink.

propagateStructFields

public static native void propagateStructFields(Object structObj, boolean fromNative);

Propagates the fields from the native memory block to the Java object or from the Java object to the native memory block. The contents of some complex field types, such as arrays, are cached in GC memory, so writes or reads of these fields do not access the native memory block. By calling this method, the contents of the native memory block and the Java object are synchronized.

Parameter	Description
structObj	The object declared using @dll.struct.
fromNative	The direction in which to propagate the fields.

ptrToString

public static String ptrToString(int ptr);

Converts a native string to a java.lang.String object. The native string is assumed to be in ANSI format if the auto mode is ANSI; otherwise, Unicode format is assumed. A string that has the high-order word set to zero is allowed and is converted to null.

Return Value:

Returns the Java string that represents the native string.

Parameter	Description
ptr	The native string to convert.

ptrToStringAnsi

public static String ptrToStringAnsi(int ptr);

Converts a native string in ANSI format to a java.lang.String object. A string that has the high-order word set to zero is legal and is converted to null.

Return Value:

Returns the Java string that represents the native string.

Parameter	Description
ptr	The string pointer to convert.

ptrToStringUni

public static String ptrToStringUni(int ptr);

Converts a native string in Unicode format to a java.lang.String object. A string that has the high-order word set to zero is legal and is converted to null.

Return Value:

Returns the Java string that represents the native string.

Parameter	Description
ptr	The string pointer to convert.

ptrToStruct

public static Object ptrToStruct(Class structClass, int ptr);

Maps a raw pointer onto a structure. This method simulates a C-style cast of an arbitrary pointer to a structure.

Return Value:

Returns an instance of structClass.

Parameter	Description
structClass	The structure to map the raw pointer to. This class must have been declared using @dll.struct.
ptr	The raw pointer to be mapped.

read1

public static native byte read1(Object ptr, int ofs);

Reads one byte of data from the memory location that is specified by a base address and an offset.

Return Value:

Returns the byte that is read.

Parameter	Description
ptr	The base address to write to.
ofs	The offset from the base address.

read1

public static native byte read1(int ptr, int ofs);

Reads one byte of data from the memory location that is specified by a base address and an offset.

Return Value:

Returns the byte that is read.

Parameter	Description
ptr	The base address to write to.
ofs	The offset from the base address.

read1

public static byte read1(int ptr);

Reads a byte from a specified memory location.

Return Value:

Returns the byte that is read.

Parameter	Description
ptr	The address in memory where the byte to be read is located.

read2

public static native short read2(Object ptr, int ofs);

Reads two bytes of data from the memory location that is specified by a base address and an offset.

Return Value:

Returns the bytes that are read.

Parameter	Description
ptr	The base address to write to.
ofs	The offset from the base address.

read2

public static native short read2(int ptr, int ofs);

Reads two bytes of data from the memory location that is specified by a base address and an offset.

Return Value:

Returns the bytes that are read.

Parameter	Description
ptr	The base address to write to.
ofs	The offset from the base address.

read2

public static short read2(int ptr);

Reads a short integer from a specified memory location.

Return Value:

Returns the short integer that is read.

Parameter	Description
ptr	The address in memory where the short integer to be read is located.

read4

public static native int read4(Object ptr, int ofs);

Reads four bytes of data from the memory location that is specified by a base address and an offset.

Return Value:

Returns the bytes that are read.

Parameter	Description
ptr	The base address to write to.
ofs	The offset from the base address.

read4

public static native int read4(int ptr, int ofs);

Reads four bytes of data from the memory location that is specified by a base address and an offset.

Return Value:

Returns the bytes that are read.

Parameter	Description
ptr	The base address to write to.
ofs	The offset from the base address.

read4

public static int read4(int ptr);

Reads an integer from a specified memory location.

Return Value:

Returns the integer that is read.

Parameter	Description
ptr	The address in memory where the integer to be read is located.

read8

public static native long read8(Object ptr, int ofs);

Reads eight bytes of data from the memory location that is specified by a base address and an offset.

Return Value:

Returns the bytes that are read.

Parameter	Description
ptr	The base address to write to.
ofs	The offset from the base address.

read8

public static native long read8(int ptr, int ofs);

Reads eight bytes of data from the memory location that is specified by a base address and an offset.

Return Value:

Returns the bytes that are read.

Parameter	Description
ptr	The base address to write to.
ofs	The offset from the base address.

read8

public static long read8(int ptr);

Reads a long integer from a specified memory location.

Return Value:

Returns the long integer that is read.

Parameter	Description
ptr	The address in memory where the long integer to be read is located.

release

public static native void release(Object o);

This method frees the native memory associated with an object declared using the @dll.struct compiler directive, if that memory would normally have been released by garbage collection. If the object is not declared using @dll.struct, or if the native memory associated with the object is not owned by the garbage-collector, this method does nothing.

Return Value:

No return value.

Parameter	Description
o	The object to be freed.

resize

public native static void resize(Object structObj, int newsize);

Reallocates the native memory block represented by an object declared using the @dll.struct directive. The object must have been created by executing "new" from Java (as opposed to being created to wrap an external pointer). The new block will preserve the contents of the old block as much as possible. If the new block is larger than the old block, the remaining portion will be zero-initialized.

This method is normally invoked from a constructor and can be used to implement structures that vary in size.

Return Value:

No return value.

Parameter	Description
structObj	The structure to resize.
newsize	The new size (in bytes).

sizeOf

public static int sizeOf(Class structCls);

Returns the size in bytes of the native structure represented by the specified class. The class must have been declared using the @dll.struct compiler directive (or @com.struct).

Return Value:

Returns the size of the native structure (in bytes).

Parameter	Description
structCls	The class to examine.

sizeOf

public native static int sizeOf(Object structObj);

Returns the size in bytes of an instance of a J/Direct structure. You can use this method to declare a self-describing structure that will be used in a DLL call, as in the following example.

/** @dll.struct() */
class STARTUPINFO
{
  public int cb = DllLib.sizeOf(this);
  public int lpReserved;
  public int lpDesktop;
  ...
}

// now you can use an instance of STARTUPINFO in a DLL call

Return Value:

Returns the size of the object.

Parameter	Description
structObj	The object whose size is being determined.

stringToCoTaskMem

public static int stringToCoTaskMem(String s);

Copies a string into a native memory block by using either ANSI or Unicode format depending on the auto mode setting. The memory block is allocated by using the Win32 function CoTaskMemAlloc.

Return Value:

Returns a pointer to the block that contains the string in the specified format.

Parameter	Description
s	The string to copy.

Remarks:

You can use the freeCoTaskMem method to release the block from Java.

Important Note:

On Windows NT, if you use the stringToCoTaskMem method with the Comctl32.ListView_InsertColumn function, you may not get the results you expect. Instead, you should use the stringToCoTaskMemAnsi method as shown in the following example.

lvc1.pszText = DllLib.stringToCoTaskMemAnsi("C Column"); // Notice the Ansi suffix 
int1 = Comctl32.ListView_InsertColumn(hWindLV1, 1, lvc1); 

stringToCoTaskMemAnsi

public static int stringToCoTaskMemAnsi(String s);

Copies a string into a native memory block in ANSI format. The memory block is allocated by using the Win32 function CoTaskMemAlloc.

Return Value:

Returns a pointer to the block that contains the specified string in ANSI format.

Parameter	Description
s	The string to copy.

Remarks:

You can use the freeCoTaskMem method to release the block from Java.

stringToCoTaskMemUni

public static int stringToCoTaskMemUni(String s);

Copies a string into a native memory block in Unicode format. The memory block is allocated by using the Win32 function CoTaskMemAlloc.

Return Value:

Returns a pointer to the block that contains the specified string in Unicode format.

Parameter	Description
s	The string to copy.

Remarks:

You can use the freeCoTaskMem method to release the block from Java.

stringToHGlobal

public static int stringToHGlobal(String s);

Copies a string into a native memory block, using either ANSI or Unicode format, depending on the auto mode setting. The memory block is allocated by using GlobalAlloc (GMEM_FIXED).

Return Value:

Returns a pointer to the block that contains the specified string.

Parameter	Description
s	The string to copy.

Remarks:

You can use the freeHGlobal method to release the block from Java.

stringToHGlobalAnsi

public static int stringToHGlobalAnsi(String s);

Copies a string into a native memory block in ANSI format. The memory block is allocated by using GlobalAlloc (GMEM_FIXED).

Return Value:

Returns a pointer to the block that contains the specified string in ANSI format.

Parameter	Description
s	The string to copy.

Remarks:

You can use the freeHGlobal method to release the block from Java.

stringToHGlobalUni

public static int stringToHGlobalUni(String s);

Copies a string into a native memory block in Unicode format. The memory block is allocated by using GlobalAlloc (GMEM_FIXED).

Return Value:

Returns a pointer to the block that contains the specified string in Unicode format.

Parameter	Description
s	The string to copy.

Remarks:

You can use the freeHGlobal method to release the block from Java.

throwWin32Exception

public static final void throwWin32Exception();

Throws a Win32Exception using the error code set by the last DLL-imported method (declared with the setLastError modifier) that is invoked on the current thread.

Note Only DLL methods declared with the setLastError modifier can set error codes.

Return Value:

No return value.

write1

public static native void write1(Object ptr, int ofs, byte val);

Writes one byte of data to the memory location that is specified by a base address and an offset.

Return Value:

No return value.

Parameter	Description
ptr	The base address to write to.
ofs	The offset from the base address.
val	The value to write.

write1

public static native void write1(int ptr, int ofs, byte val);

Writes one byte of data to the memory location that is specified by a base address and an offset.

Return Value:

No return value.

Parameter	Description
ptr	The base address to write to.
ofs	The offset from the base address.
val	The value to write.

write1

public static void write1(int ptr, byte val);

Writes a byte to the specified memory location.

Return Value:

No return value.

Parameter	Description
ptr	The address in memory where the byte will be written.
val	The value to write.

write2

public static native void write2(Object ptr, int ofs, short val);

Writes two bytes of data to the memory location that is specified by a base address and an offset.

Return Value:

No return value.

Parameter	Description
ptr	The base address to write to.
ofs	The offset from the base address.
val	The value to write.

write2

public static native void write2(int ptr, int ofs, short val);

Writes two bytes of data to the memory location that is specified by a base address and an offset.

Return Value:

No return value.

Parameter	Description
ptr	The base address to write to.
ofs	The offset from the base address.
val	The value to write.

write2

public static void write2(int ptr, short val);

Writes a short integer to the specified memory location.

Return Value:

No return value.

Parameter	Description
ptr	The address in memory where the short integer will be written.
val	The value to write.

write2

public static native void write2(Object ptr, int ofs, char val);

Writes two bytes of data to the memory location that is specified by a base address and an offset.

Return Value:

No return value.

Parameter	Description
ptr	The base address to write to.
ofs	The offset from the base address.
val	The value to write.

write2

public static native void write2(int ptr, int ofs, char val);

Writes two bytes of data to the memory location that is specified by a base address and an offset.

Return Value:

No return value.

Parameter	Description
ptr	The base address to write to.
ofs	The offset from the base address.
val	The value to write.

write2

public static void write2(int ptr, char val);

Writes a character to the specified memory location.

Return Value:

No return value.

Parameter	Description
ptr	The address in memory where the character will be written.
val	The value to write.

write4

public static native void write4(Object ptr, int ofs, int val);

Writes four bytes of data to the memory location that is specified by a base address and an offset.

Return Value:

No return value.

Parameter	Description
ptr	The base address to write to.
ofs	The offset from the base address.
val	The value to write.

write4

public static native void write4(int ptr, int ofs, int val);

Writes four bytes of data to the memory location that is specified by a base address and an offset.

Return Value:

No return value.

Parameter	Description
ptr	The base address to write to.
ofs	The offset from the base address.
val	The value to write.

write4

public static void write4(int ptr, int val);

Writes an integer to the specified memory location.

Return Value:

No return value.

Parameter	Description
ptr	The address in memory where the integer will be written.
val	The value to write.

write8

public static native void write8(Object ptr, int ofs, long val);

Writes eight bytes of data to the memory location that is specified by a base address and an offset.

Return Value:

No return value.

Parameter	Description
ptr	The base address to write to.
ofs	The offset from the base address.
val	The value to write.

write8

public static native void write8(int ptr, int ofs, long val);

Writes eight bytes of data to the memory location that is specified by a base address and an offset.

Return Value:

No return value.

Parameter	Description
ptr	The base address to write to.
ofs	The offset from the base address.
val	The value to write.

write8

public static void write8(int ptr, long val);

Writes a long integer to the specified memory location.

Return Value:

No return value.

Parameter	Description
ptr	The address in memory where the long integer will be written.
val	The value to write.

Fields

systemDefaultCharSize

Contains the preferred character size of the host system (1 for ANSI, 2 for Unicode). The value of this class variable indicates the mode that a DLL-imported method will link in when the auto modifier is used with the @dll.import compiler directive.