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_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.
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. |
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. |