J/Direct Information

Microsoft® J/Direct™ is a very powerful mechanism that allows Java code to call functions exported from any Windows DLLs. The code in the DLLs need not be aware of the Java environment. The most obvious use of this scheme is to call Win32 APIs or APIs in third party DLLs. This mechanism automatically translates common data types, such as strings and structures to forms typically expected by C functions. This dramatically reduces any glue code or wrapper DLLs that need to be written. In short J/Direct exposes the richness of the Windows platform to the Java programmer. It also makes calling functions in DLLs as simple as possible.

Any class that uses J/Direct calls requires permissions for maximum trust from the system. This is best explained by looking at the various scenarios:

• An applet can use J/Direct calls only if it is signed and has "fully trusted" permissions.
• An untrusted applet cannot resolve to a class that uses J/Direct calls, unless that class has been appropriately marked as a class that can protect itself from malicious use. Please see the "Security Issues" section of the "About J/Direct" article for more information on how to mark your class as safe for use from an untrusted applet.
• A class on the CLASSPATH, or a package managed class with the "fully trusted" permission, can be a wrapper class that protects another class that uses J/Direct calls from malicious use. Such a wrapper or proxy class can be called from an applet.

A J/Direct call should be treated as a native call. Do not expose access to J/Direct functionality any more freely than access to native code. Security checks should be made through the security manager when exposing J/Direct functionally to untrusted code.

Please refer to the articles "Mixing Java and Native Code" and "About J/Direct" in the SDK for Java documentation for more information.

Win32 API Classes for J/Direct

The Win32 API Classes for J/Direct (the com.ms.win32.* package) provide direct, low-overhead access to commonly used Windows APIs. These classes use the new J/Direct feature and therefore require either Internet Explorer 4.0, or the Microsoft SDK for Java version 3.0 pre-release 2.

The Win32 API Classes for J/Direct are an optional component in the SDK install. When these classes are installed the com.ms.win32 package is copied into the %windir%\java\classes directory. The sources (.java files) for these classes are also provided as part of the Microsoft SDK for Java version 3.0 pre-release 2.

If your application requires an api not covered in these classes, J/Direct makes it very easy to write declarations on your own. Complete documentation and samples on using J/Direct can be found in the Microsoft SDK for Java version 3.0 pre-release 2.

Packages included in this CAB:

com.ms.win32 J/Direct declarations for common Win32 APIs and constants

Classes included in this CAB:

The classes included in com.ms.win32 package fall into three main categories:

Constants

The win class contains the numeric constants used in Win32. For example, the system path length limit (MAX_PATH) can be accessed from Java as follows:

import com.ms.win32.*;

System.out.println("MAX_PATH = " + win.MAX_PATH);

Performance tip:

Do not include the win class in the extends or implements clause of your application's classes. This trick is commonly used to avoid having to type the class name in front of each constant usage. The price for this convenience is that the win class will need to be loaded at runtime, which can significantly impact application start up time. To avoid this overhead, use the qualified name for each constant reference. The Microsoft compiler for Java will inline constant references and will not create a runtime dependency on the win class.

Functions

The Win32 APIs are divided into classes according to the DLL they are exported from.

Structures

Win32 structures are represented by Java classes that bear the same name as the structure.

Known Issues

If the Win32 API classes for J/Direct were installed as part of the SDK for Java version 3.0 pre-release 2, they would reside in %windir%\java\classes\com\ms\win32. The SDK setup does not delete these older classes. Please feel free to delete them with a command of the form:

	c:
	cd %windir%\java\classes
	deltree com