About com.ms.dll

The com.ms.dll package helps you link your Java code with dynamic-link libraries (DLLs). You can use the methods in the com.ms.dll package along with Microsoft® J/Direct™ technology to call functions located in Win32 DLLs, OLE API functions, and third-party DLLs. For more information on J/Direct technology and on how to use the @dll.import compiler directive that J/Direct provides, see About J/Direct.

Overview

The DllLib class offers a variety of methods that are used in conjunction with the @dll.import directive. The ptrToXXX methods can be used to treat a parameter as a LPTSTR. Several copy methods, as well as read and write methods, allow your Java code to read and write data from raw pointers. The ptrToStruct method provides another way to read and write data through a raw pointer by wrapping the raw pointer in an instance of a class that was declared with the @dll.struct directive. For more information on how and when to declare a Java class with the @dll.struct directive, see the Structures section of the About J/Direct article. DllLib also contains methods that copy strings to native memory blocks, convert native strings to Java String objects, and free and allocate native memory blocks.

You can extend the Callback class to create Callback objects in Java. Your derived Callback class must contain one non-static method whose name is callback (all lowercase). The callback method has limited return types, and all the parameters must be of type int. After the Callback class has been created, you can use the @dll.import compiler directive to call a Win32 function that takes a Callback as a parameter.

The Root class provides a way for you to protect a Java object from garbage collection by creating a 32-bit root handle for the object. This is helpful when you have created a Callback object that will be used across function calls. By wrapping the Callback inside a root handle, you can keep the Callback from being reclaimed by garbage collection. When you no longer need the Callback, you should explicitly free its root handle using the dll.Root.free method.

You can use the Win32Exception class to create objects that contain error descriptions for error codes set by Win32 functions. When you call Win32 functions using the @dll.import compiler directive, you can use the setLastError modifier to tell the VM to capture the error code immediately after the function is called. You can then use the dll.dllLib.getLastWin32Error method to obtain the error code, and you can wrap it in a Java Win32Exception object that describes the error.

The following class in com.ms.dll is used by internal operations and must be installed on your host system for the com.ms.dll package to work correctly. However, the Java applications you create never need to call this class directly.

StringMarshaler

Converts a LPCSTR to a java.lang.String object.

Classes

Class ArrayWithOffset

This class is used to encapsulate a pointer into an array, for use with Microsoft® J/Direct™ methods.

Class Callback

This class creates a native callback for Win32 APIs such as EnumWindows.

Class DllLib

This class contains methods for linking to dynamic-link libraries (DLLs).

Class ParameterCountMismatchError

This class represents objects that contain the number of parameters expected and the number of objects actually passed to a method.

Class Root

This class allows you to create an opaque 32-bit root handle to any Java object.

Class Win32Exception

This class provides access to objects that contain error codes and error descriptions for errors set by Microsoft® Win32® functions.

Hierarchy

Object
  |
  +--Callback
  |
  +--DllLib
  |
  +--Root

RuntimeException
  |
  +--ParameterCountMismatchError
  |
  +--Win32Exception