Microsoft SDK for Java

@dll.import

The @dll.import directive maps a C function from the specified DLL to a Java method. If the entrypoint parameter is not used, the Microsoft virtual machine assumes that the Java method name is exactly the same as the exported DLL function name (case-sensitive). The Microsoft VM will make various attempts to find the method, such as by appending A (for ANSI) or W (for Unicode).

If this directive is used at the class level, every method prototype specified with the native keyword will, by default, have the same @dll.import tag. However, a method can override the global @dll.import tag by specifying its own @dll.import directive. The global @dll.import is not required if individual @dll.import directives are used for every native J/Direct method specified in the Java class.

You can specify the DLL to use for static native methods in a whole class by putting the directive immediately above the class declaration. Alternatively, you can specify which DLL to use on a method-by-method basis, as shown in the J/Direct Message Box example. The @dll.import directive also has parameters to allow you to link to ordinals, use an alias for the function name, and modify the calling convention.

The Java data types that you choose for the parameters and for the return value of the method should be types that map to the types of the DLL function parameters and return value. For more information about how Java data types map to native types, see How Data Types are Marshaled.

The directive parameters ansi, auto, unicode, and ole determine the native character encoding (ANSI or Unicode) that the Microsoft VM will use when converting Java string and character parameters to their native counterparts. In operating systems that use ANSI as their base character encoding, such as Microsoft® Windows® 95 or Microsoft® Windows® 98, ANSI strings and characters are generally required in structures and parameters. In Unicode-based operating systems, such as Microsoft® Windows NT® and Microsoft® Windows® 2000, Unicode strings and characters are generally desirable. The auto parameter causes the Microsoft VM to choose the correct encoding type at runtime, depending on the base character encoding of the operating system that the class is used on. If ole is specified, the Unicode character encoding will be used. The auto parameter also determines how methods will be linked by adding the appropriate A (ANSI) or W (Unicode) suffix. See Calling Different Versions of DLL Functions for details.

At most one of the directive parameters ansi, auto, unicode, ole, and raw can be specified in a given @dll.import directive. If none are specified at the method level, the value specified at the class level is used. If none are specified at the class level, the default is ansi.

Syntax

@dll.import([string], [entrypoint=string], [ansi | auto | unicode | ole | raw], [setLastError], [linktype=integer])

Parameters

string

This parameter is required.

Indicates the DLL file name that the function is imported from. Don't include the .dll file extension. The DLL to be loaded must be in the system path when the method is invoked. This directive parameter must be declared at the class or method level.
entrypoint=
string
Specifies the exported DLL function name. The Java method is mapped to this method in the DLL.

A secondary form can be used to link to DLL exports by ordinal. In this case, the string must have the form "#integer", where the integer is a 16-bit decimal representation of the ordinal number.

ansi Specifies that the VM should use an ANSI character encoding when converting Java string and character parameters to their native counterparts.

Dependency: Cannot be used with auto, unicode, ole, or raw.

auto Specifies that the character encoding that the Microsoft VM should use when converting Java string and character parameters to their native counterparts should be determined at runtime. Specifically, the base character encoding of the operating system will be used.

Dependency: Cannot be used with ansi, unicode, ole, or raw.

unicode Specifies that the Microsoft VM should use the Unicode character encoding when converting Java string and character parameters to their native counterparts.

Dependency: Cannot be used with ansi, auto, ole, or raw.

ole Specifies that the method will be mapped to an OLE-compatible native function. The native function must return an HRESULT value, and all string and character parameters will be in Unicode. Generally, the last parameter is a return value. This causes the Java method to throw a com.ms.comComFailException (if there is a non-zero HRESULT) rather than return an HRESULT from the Java method. Because the last function parameter is a pointer to the location where the result of the function call should be placed, the return value from the Java method can generally be the last parameter to the native function.

This parameter is used to make COM function mappings (and other functions that follow the OLE calling convention) more similar to Java methods. Strings or characters are mapped to Unicode native values.

Dependency: Cannot be used with ansi, auto, unicode, or raw.

raw Specifies that the method is a standard Java native method (that is, one using RNI or JNI) and should be marshaled accordingly.

Dependency: Cannot be used with ansi, auto, unicode, or ole.

setLastError Indicates that the imported function provides error information to the application through the Win32 GetLastError function. Because the VM is running this method for the Java application, manually calling GetLastError from Java may return the last error the Microsoft VM caused rather than the error from the J/Direct function call. Specifying setLastError in the @dll.import directive causes the VM to hold the error code from the function call. The client can retrieve the error code by using com.ms.dll.DllLib.getLastWin32Error.
linktype=integer The integer value can be one of NLT_RAW, NLT_INHERIT, NLT_ANSI, NLT_UNICODE, NLT_DUAL, or NLT_OLE and becomes the value of the m_LinkType field in the NAT_L attribute. See the linktype values table for possible values of this field.

This is a more extensible way of setting the link type, as compared with ansi, auto, unicode, ole, and raw.

Dependency: Cannot be used with ansi, auto, unicode, ole, or raw.


Attributes

NAT_L Method scope.

Related Directives

@dll.structmap (and @com.structmap)

@dll.struct (and @com.struct)

See Also

Specifying @dll.import for an Entire Class

Examples

The @dll.import directive must precede a non-synchronized, static native method, or the class keyword. A @dll.import directive that precedes the class keyword is interpreted as a global @dll.import. It specifies default values for any methods declared by the class.

/** @dll.import(auto, "KERNEL32") */
public static native void DebugBreak();

The @dll.import tag shown here is applied to an entire class.

/** @dll.import("advapi32", setLastError) */
public class Advapi32{
  public static native boolean StartServiceCtrlDispatcher(...);
  public static native boolean ReportEvent(...);
}

Use the ole parameter to make imported functions more Java-like by mapping the last C parameter to the Java return value. The Microsoft VM automatically throws the HRESULT error codes as ComFailExceptions.

The C function prototype:

HRESULT CoGetMalloc(DWORD dwMemContext, ImMalloc **ppMalloc);

The Java method:

/** @dll.import("ole32") */
public static native IMalloc CoGetMalloc( int dwMemContext );

The following table presents the @dll.import syntax for several situations.

Situation Required syntax Remarks
Calling Win 32 DLLs /**@dll.import
("LibName")*/
 
Calling OLE APIs /**@dll.import
("LibName",ole)*/
Aliasing /**@dll.import
("LibName", entrypoint=
"DLLFunctionName")*/
In the method declaration, use the Java name that you selected.
Linking by Ordinal /**@dll.import
("LibName",
entrypoint="#ordinal")*/
"#ordinal" is a 16-bit decimal integer indicating the DLL function you are importing.

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