com.sun.jna

Interface Library

All Known Subinterfaces:

Advapi32, BaseTSD, Carbon, CoreDLL, Crypt32, DBT, DsGetDC, Dxva2, GDI32, GL, Kernel32, LMAccess, LMCons, LMErr, LMJoin, MacFileUtils.FileManager, Msi, Netapi32, NtDll, NTSecApi, Ole32, OleAuto, OpenGL32, Pdh, Psapi, Rasapi32, Secur32, SetupApi, Shell32, ShellAPI, Sspi, StdCallLibrary, SystemB, Tlhelp32, User32, VerRsrc, Version, W32APIOptions, Wdm, WinBase, WinCrypt, WinDef, WinGDI, Winioctl, WinNT, WinRas, WinReg, Winspool, Winsvc, WinUser, Wtsapi32, X11, X11.Xevie, X11.Xext, X11.Xrender, X11.XTest, XAttr

All Known Implementing Classes:

AccCtrl, Kernel32Util

public interface Library

Derive from this interface for all native library definitions. Define an instance of your library like this:

 MyNativeLibrary INSTANCE = (MyNativeLibrary)
     Native.loadLibrary("mylib", MyNativeLibrary.class);
 

By convention, method names are identical to the native names, although you can map java names to different native names by providing a FunctionMapper as a value for key OPTION_FUNCTION_MAPPER in the options map passed to the Native.loadLibrary(String, Class, Map) call.

Although the names for structures and structure fields may be chosen arbitrarily, they should correspond as closely as possible to the native definitions. The same is true for parameter names.

This interface supports multiple, concurrent invocations of any library methods on the Java side. Check your library documentation for its multi-threading requirements on the native side. If a library is not safe for simultaneous multi-threaded access, consider using Native.synchronizedLibrary(com.sun.jna.Library) to prevent simultaneous multi-threaded access to the native code.

Optional fields
Interface options will be automatically propagated to structures defined within the library provided a call to Native.loadLibrary(String,Class,Map) is made prior to instantiating any of those structures. One common way of ensuring this is to declare an INSTANCE field in the interface which holds the loadLibrary result.

OPTIONS (an instance of Map), TYPE_MAPPER (an instance of TypeMapper), STRUCTURE_ALIGNMENT (one of the alignment types defined in Structure), and STRING_ENCODING (a String) may also be defined. If no instance of the interface has been instantiated, these fields will be used to determine customization settings for structures and methods defined within the interface.

Author:

Todd Fast, todd.fast@sun.com, Timothy Wall, twalljava@dev.java.net

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	Library.Handler

Field Summary

Fields

Modifier and Type	Field and Description
static String	OPTION_ALLOW_OBJECTS Option key for a boolean flag to allow any Java class instance as a parameter.
static String	OPTION_CALLING_CONVENTION Calling convention for the entire library.
static String	OPTION_CLASSLOADER Class loader to use when searching for native libraries on the resource path (classpath).
static String	OPTION_FUNCTION_MAPPER Option key for a FunctionMapper for the library.
static String	OPTION_INVOCATION_MAPPER Option key for an InvocationMapper for the library.
static String	OPTION_OPEN_FLAGS Flags to use when opening the native library (see Native.open(String,int))
static String	OPTION_STRING_ENCODING Option key for per-library String encoding.
static String	OPTION_STRUCTURE_ALIGNMENT Option key for structure alignment type (Integer), which should be one of the predefined alignment types in Structure.
static String	OPTION_TYPE_MAPPER Option key for a TypeMapper for the library.

Field Detail

OPTION_TYPE_MAPPER

static final String OPTION_TYPE_MAPPER

Option key for a TypeMapper for the library.

See Also:

Constant Field Values

OPTION_FUNCTION_MAPPER

static final String OPTION_FUNCTION_MAPPER

Option key for a FunctionMapper for the library.

See Also:

Constant Field Values

OPTION_INVOCATION_MAPPER

static final String OPTION_INVOCATION_MAPPER

Option key for an InvocationMapper for the library.

See Also:

Constant Field Values

OPTION_STRUCTURE_ALIGNMENT

static final String OPTION_STRUCTURE_ALIGNMENT

Option key for structure alignment type (Integer), which should be one of the predefined alignment types in Structure.

See Also:

Constant Field Values

OPTION_STRING_ENCODING

static final String OPTION_STRING_ENCODING

Option key for per-library String encoding. This affects conversions between Java unicode and native (const char*) strings (as arguments or Structure fields).

Defaults to Native.getDefaultStringEncoding().

See Also:

Constant Field Values

OPTION_ALLOW_OBJECTS

static final String OPTION_ALLOW_OBJECTS

Option key for a boolean flag to allow any Java class instance as a parameter. If no type mapper is found, the object is passed as a pointer. NOTE: This is for use with raw JNI interactions via the JNIEnv data structure.

See Also:

Constant Field Values

OPTION_CALLING_CONVENTION

static final String OPTION_CALLING_CONVENTION

Calling convention for the entire library.

See Also:

Constant Field Values

OPTION_OPEN_FLAGS

static final String OPTION_OPEN_FLAGS

Flags to use when opening the native library (see Native.open(String,int))

See Also:

Constant Field Values

OPTION_CLASSLOADER

static final String OPTION_CLASSLOADER

Class loader to use when searching for native libraries on the resource path (classpath). If not provided the current thread's context class loader is used.

If extracted from the resource path (i.e. bundled in a jar file), the loaded library's lifespan will mirror that of the class loader, which means you can use the same library in isolated contexts without conflict.

See Also:

Constant Field Values