Microsoft SDK for Java

NAT_L

The NAT_L (Native Link) attribute specifies the dynamic-link library (DLL) name and DLL entry point (method) name associated with a J/Direct Java method, as well as the calling convention (ansi, Unicode, ole, or raw native) and other semantics.

Attribute Level Generated By Directives
Class or method @dll.import

NAT_L_attribute {
  u2 attribute_name_index;
  u4 attribute_length;
  u1 linktype;
  u1 Flags;
  u2 LibName_CPIndex;
  u2 EntryName_CPIndex;
}

The @dll.import directive that generates this attribute has the following syntax:

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

If the DLL name is specified at the global level (a global @dll.import directive) in a class, this parameter may be omitted in subsequent @dll.import directives at the method level. The entrypoint name must be omitted in a global @dll.import directive.

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. Its purpose is to specify default values for any methods declared by the class.

When used with some parameters specified, this directive might look like the following:

/** @dll.import("KERNEL32",AUTO, setLastError) */

When used with minimal parameters, this directive might look like the following:

/** @dll.import("KERNEL32") */

Attribute Elements

attribute_name_index

This value must be a valid index into the constant_pool table. The constant_pool entry at that index must be the CONSTANT_Utf8_info structure representing the string "NAT_L".

attribute_length

This value indicates the length of this attribute, excluding the initial six bytes, and may be six.

linktype

This value indicates the calling convention, which can be specified as ansi, auto, Unicode, raw, or OLE corresponding to the @dll.import parameters. If the linktype is set in a global @dll.import directive, this value will become the default linktype for all methods in the class unless it is overridden. If the linktype is omitted in a global dll.import directive, the default calling convention is set to ANSI for the methods of the Java class.

Flags

This value has a single option and indicates whether the setLastError parameter was used in the @dll.import directive. If this parameter was set, the Flags option has a value of 0x01 (NLF_LASTWIN32ERRORSAVE); otherwise, it is 0 (zero).

LibName_CPIndex

This value must be a valid index into the constant_pool table. The constant_pool entry at that index must be the CONSTANT_Utf8_info structure representing the DLL library name. The Microsoft VM will call LoadLibrary on this DLL name.

If this index is set with a global @dll.import directive, the DLL library name defaults to this value for all methods in the class and this parameter can be omitted from subsequent @dll.import directives for each method. When the DLL name is omitted from the @dll.import directive, a LibName_CPIndex of zero is stored in the NAT_L attribute.

EntryName_CPIndex

This value must be a valid index into the constant_pool table. The constant_pool entry at that index must be the CONSTANT_Utf8_info structure representing the entry point name of the function to call in the DLL. The Java compiler need not add this "A" or "W" to this method name to signify the ANSI or Unicode version of these functions. When a @dll.import directive applies to an individual method, the EntryName can be omitted if the Java method name exactly corresponds with the entrypoint name in the DLL. When this entrypoint is omitted from the @dll.import directive, an EntryName_CPINdex of zero is stored in the NAT_L attribute.

Possible Values of linktype

Parameter Name Value Comments
NLT_RAW 0 The Microsoft VM will link using RNI.
NLT_INHERIT 1 None of the LinkType parameter keywords were specified in the @dll.import directive.

At the global level, when no parameter keyword (for example, ole) is specified, a LinkType of NLT_INHERIT is equivalent to setting the LinkType to NLT_ANSI (use the ANSI calling convention by default).

At the method level, when no parameter keyword is entered, a linktype of 1 causes the method to use the linktype specified at the global level or the ANSI calling convention if linktype was omitted at the global level.

NLT_ANSI 2 The ANSI keyword was specified for the linktype in the @dll.import directive. The Microsoft VM will convert all characters and strings to ANSI and link to the ANSI entrypoint (suffixed by "A") when available.
NLT_UNICODE 3 The Unicode keyword was specified for the linktype in the @dll.import directive. The Microsoft VM will convert all characters and strings to Unicode and link to the Unicode entrypoint (suffixed by "W") when available.
NLT_DUAL 4 The AUTO keyword was specified for the linktype in the @dll.import directive. The Microsoft VM will automatically handle the calling convention and will choose between NLT_ANSI and NLT_unicode at runtime. The Microsoft VM will choose NLT_ANSI on Windows 95 and NLT_unicode on Windows NT.
NLT_OLE 5 The ole keyword was specified for the linktype in the @dll.import directive. The Microsoft VM will use the ole calling convention for this platform.

Possible Values for Flags

Flag Names Value Comments
NLF_LASTWIN32ERRORUNDECL 0x00 The setLastError keyword was not specified in the @dll.import directive. The Microsoft VM will not save the value of the last Microsoft® Win32® error.
NLF_LASTWIN32ERRORSAVE 0x01 The setLastError keyword was specified in the @dll.import directive. The Microsoft VM will save the value of the last Win32 error.
NLF_LASTWIN32ERRORIGNORE 0x02 The Microsoft VM will ignore the value of the last Win32 error.

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