Microsoft SDK for Java

DllLib Class

The DllLib class of the com.ms.dll package contains methods for linking to dynamic-link libraries (DLLs).

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 copyUni(int psrc, char jadst[], int elemidx, 
    int nelems);
  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 ObjectgetPinnedObject(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 void prelinkAll(Class cls);
  public static native void propagateStructFields(Object structObj,
    boolean fromNative);
  public static String ptrToString(int ptr);
  public static String ptrToStringAnsi(int ptr);
  public static String ptrToStringUni(int ptr);
  public static native Object ptrToStruct(Class structClass, int ptr,
    boolean fFreeIndirectNativeMemory);
  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);
}

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

There are other situations where the ptrToStruct method can be helpful. Because 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 Obtaining the Error Code Set By a DLL Function.

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.


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