JNA API 3.1.0

com.sun.jna
Class Native

java.lang.Object
  extended by com.sun.jna.Native

public final class Native
extends java.lang.Object

Provides generation of invocation plumbing for a defined native library interface. Also provides various utilities for native operations.

getTypeMapper(java.lang.Class) and getStructureAlignment(java.lang.Class) are provided to avoid having to explicitly pass these parameters to Structures, which would require every Structure which requires custom mapping or alignment to define a constructor and pass parameters to the superclass. To avoid lots of boilerplate, the base Structure constructor figures out these properties based on its enclosing interface.

Library Loading

When JNA classes are loaded, the native shared library (jnidispatch) is loaded as well. An attempt is made to load it from the system library path using System.loadLibrary(java.lang.String). If not found, the appropriate library will be extracted from the class path into a temporary directory and loaded from there. If your system has additional security constraints regarding execution or load of files (SELinux, for example), you should probably install the native library in an accessible location and configure your system accordingly, rather than relying on JNA to extract the library from its own jar file.

Author:
Todd Fast, todd.fast@sun.com, twall@users.sf.net
See Also:
Native.DeleteNativeLibrary

Nested Class Summary
static class Native.DeleteNativeLibrary
          For internal use only.
 
Field Summary
static int LONG_SIZE
          Size of a native long type, in bytes.
static int POINTER_SIZE
          The size of a native pointer (void*) on the current platform, in bytes.
static int SIZE_T_SIZE
          Size of a native size_t type, in bytes.
static int WCHAR_SIZE
          Size of a native wchar_t type, in bytes.
 
Method Summary
(package private) static java.lang.Class findCallbackClass(java.lang.Class type)
          Find the first instance of an interface which implements the Callback interface or an interface derived from Callback.
(package private) static java.lang.Class findEnclosingLibraryClass(java.lang.Class cls)
          Find the library interface corresponding to the given class.
static Pointer getByteBufferPointer(java.nio.ByteBuffer b)
          Deprecated. Use getDirectBufferPointer(java.nio.Buffer) instead.
(package private) static byte[] getBytes(java.lang.String s)
          Return a byte array corresponding to the given String.
static Callback.UncaughtExceptionHandler getCallbackExceptionHandler()
          Returns the current handler for callback uncaught exceptions.
static long getComponentID(java.awt.Component c)
          Utility method to get the native window ID for a heavyweight Java Component as a long value.
static Pointer getComponentPointer(java.awt.Component c)
          Utility method to get the native window pointer for a heavyweight Java Component as a Pointer value.
static Pointer getDirectBufferPointer(java.nio.Buffer b)
          Convert a direct Buffer into a Pointer.
static int getLastError()
          Retrieve the last error set by the OS.
static java.util.Map getLibraryOptions(java.lang.Class type)
          Return the preferred native library configuration options for the given class.
static int getNativeSize(java.lang.Class cls)
          Returns the native size for a given Java class.
static boolean getPreserveLastError()
          Indicates whether the system last error result is preserved after every invocation.
static int getStructureAlignment(java.lang.Class cls)
          Return the preferred structure alignment for the given native interface.
static TypeMapper getTypeMapper(java.lang.Class cls)
          Return the preferred TypeMapper for the given native interface.
static java.lang.String getWebStartLibraryPath(java.lang.String libName)
          If running web start, determine the location of a given native library.
static long getWindowID(java.awt.Window w)
          Utility method to get the native window ID for a Java Window as a long value.
static Pointer getWindowPointer(java.awt.Window w)
          Utility method to get the native window pointer for a Java Window as a Pointer value.
static boolean isProtected()
          Returns whether protection is enabled.
static boolean isSupportedNativeType(java.lang.Class cls)
          Indicate whether the given class is supported as a native argument type.
static java.lang.Object loadLibrary(java.lang.String name, java.lang.Class interfaceClass)
          Load a library interface from the given shared library, providing the explicit interface class.
static java.lang.Object loadLibrary(java.lang.String name, java.lang.Class interfaceClass, java.util.Map libOptions)
          Load a library interface from the given shared library, providing the explicit interface class and a map of options for the library.
static void main(java.lang.String[] args)
          Prints JNA library details to the console.
static void register(NativeLibrary lib)
          When called from a class static initializer, maps all native methods found within that class to native libraries via the JNA raw calling interface.
static void register(java.lang.String libName)
          When called from a class static initializer, maps all native methods found within that class to native libraries via the JNA raw calling interface.
static void setCallbackExceptionHandler(Callback.UncaughtExceptionHandler eh)
          Set the default handler invoked when a callback throws an uncaught exception.
static void setLastError(int code)
          Set the OS last error code.
static void setPreserveLastError(boolean enable)
          Set whether the system last error result is captured after every native invocation.
static void setProtected(boolean enable)
          Set whether native memory accesses are protected from invalid accesses.
static Library synchronizedLibrary(Library library)
          Returns a synchronized (thread-safe) library backed by the specified library.
static byte[] toByteArray(java.lang.String s)
          Obtain a NUL-terminated byte buffer equivalent to the given String.
static char[] toCharArray(java.lang.String s)
          Obtain a NUL-terminated wide character buffer equivalent to the given String.
static java.lang.String toString(byte[] buf)
          Obtain a Java String from the given native byte array.
static java.lang.String toString(char[] buf)
          Obtain a Java String from the given native wchar_t array.
(package private) static void updateLastError(int e)
          Update the last error value (called from native code).
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

POINTER_SIZE

public static final int POINTER_SIZE
The size of a native pointer (void*) on the current platform, in bytes.


LONG_SIZE

public static final int LONG_SIZE
Size of a native long type, in bytes.


WCHAR_SIZE

public static final int WCHAR_SIZE
Size of a native wchar_t type, in bytes.


SIZE_T_SIZE

public static final int SIZE_T_SIZE
Size of a native size_t type, in bytes.

Method Detail

setProtected

public static void setProtected(boolean enable)
Set whether native memory accesses are protected from invalid accesses. This should only be set true when testing or debugging, and should not be considered reliable or robust for multithreaded applications. Protected mode will be automatically set if the system property jna.protected has a value of "true" when the JNA library is first loaded.

If not supported by the underlying platform, this setting will have no effect.

NOTE: When protected mode is enabled, you should make use of the jsig library, if available (see Signal Chaining). In short, set the environment vaiable LD_PRELOAD to the path to libjsig.so in your JRE lib directory (usually ${java.home}/lib/${os.arch}/libjsig.so) before launching your Java application.


isProtected

public static boolean isProtected()
Returns whether protection is enabled. Check the result of this method after calling setProtected(true) to determine if this platform supports protecting memory accesses.


setPreserveLastError

public static void setPreserveLastError(boolean enable)
Set whether the system last error result is captured after every native invocation. Defaults to true.


getPreserveLastError

public static boolean getPreserveLastError()
Indicates whether the system last error result is preserved after every invocation.


getWindowID

public static long getWindowID(java.awt.Window w)
                        throws java.awt.HeadlessException
Utility method to get the native window ID for a Java Window as a long value. This method is primarily for X11-based systems, which use an opaque XID (usually long int) to identify windows.

Throws:
java.awt.HeadlessException - if the current VM is running headless

getComponentID

public static long getComponentID(java.awt.Component c)
                           throws java.awt.HeadlessException
Utility method to get the native window ID for a heavyweight Java Component as a long value. This method is primarily for X11-based systems, which use an opaque XID (usually long int) to identify windows.

Throws:
java.awt.HeadlessException - if the current VM is running headless

getWindowPointer

public static Pointer getWindowPointer(java.awt.Window w)
                                throws java.awt.HeadlessException
Utility method to get the native window pointer for a Java Window as a Pointer value. This method is primarily for w32, which uses the HANDLE type (actually void *) to identify windows.

Throws:
java.awt.HeadlessException - if the current VM is running headless

getComponentPointer

public static Pointer getComponentPointer(java.awt.Component c)
                                   throws java.awt.HeadlessException
Utility method to get the native window pointer for a heavyweight Java Component as a Pointer value. This method is primarily for w32, which uses the HANDLE type (actually void *) to identify windows.

Throws:
java.awt.HeadlessException - if the current VM is running headless

getByteBufferPointer

public static Pointer getByteBufferPointer(java.nio.ByteBuffer b)
Deprecated. Use getDirectBufferPointer(java.nio.Buffer) instead.

Convert a direct Buffer into a Pointer.

Throws:
java.lang.IllegalArgumentException - if the buffer is not direct.

getDirectBufferPointer

public static Pointer getDirectBufferPointer(java.nio.Buffer b)
Convert a direct Buffer into a Pointer.

Throws:
java.lang.IllegalArgumentException - if the buffer is not direct.

toString

public static java.lang.String toString(byte[] buf)
Obtain a Java String from the given native byte array. If there is no NUL terminator, the String will comprise the entire array. If the system property jna.encoding is set, its value will override the platform default encoding (if supported).


toString

public static java.lang.String toString(char[] buf)
Obtain a Java String from the given native wchar_t array. If there is no NUL terminator, the String will comprise the entire array.


loadLibrary

public static java.lang.Object loadLibrary(java.lang.String name,
                                           java.lang.Class interfaceClass)
Load a library interface from the given shared library, providing the explicit interface class.


loadLibrary

public static java.lang.Object loadLibrary(java.lang.String name,
                                           java.lang.Class interfaceClass,
                                           java.util.Map libOptions)
Load a library interface from the given shared library, providing the explicit interface class and a map of options for the library. If no library options are detected the map is interpreted as a map of Java method names to native function names.

Parameters:
name -
interfaceClass -
libOptions - Map of library options

findCallbackClass

static java.lang.Class findCallbackClass(java.lang.Class type)
Find the first instance of an interface which implements the Callback interface or an interface derived from Callback.


findEnclosingLibraryClass

static java.lang.Class findEnclosingLibraryClass(java.lang.Class cls)
Find the library interface corresponding to the given class. Checks all ancestor classes and interfaces for a declaring class which implements Native.DeleteNativeLibrary.


getLibraryOptions

public static java.util.Map getLibraryOptions(java.lang.Class type)
Return the preferred native library configuration options for the given class.

See Also:
Native.DeleteNativeLibrary

getTypeMapper

public static TypeMapper getTypeMapper(java.lang.Class cls)
Return the preferred TypeMapper for the given native interface. See Library.OPTION_TYPE_MAPPER.


getStructureAlignment

public static int getStructureAlignment(java.lang.Class cls)
Return the preferred structure alignment for the given native interface. See Library.OPTION_STRUCTURE_ALIGNMENT.


getBytes

static byte[] getBytes(java.lang.String s)
Return a byte array corresponding to the given String. If the system property jna.encoding is set, its value will override the default platform encoding (if supported).


toByteArray

public static byte[] toByteArray(java.lang.String s)
Obtain a NUL-terminated byte buffer equivalent to the given String.


toCharArray

public static char[] toCharArray(java.lang.String s)
Obtain a NUL-terminated wide character buffer equivalent to the given String.


getLastError

public static int getLastError()
Retrieve the last error set by the OS. This corresponds to GetLastError() on Windows, and errno on most other platforms. The value is preserved per-thread, but whether the original value is per-thread depends on the underlying OS. The result is undefined If getPreserveLastError() is false.


setLastError

public static void setLastError(int code)
Set the OS last error code. Whether the setting is per-thread or global depends on the underlying OS.


updateLastError

static void updateLastError(int e)
Update the last error value (called from native code).


synchronizedLibrary

public static Library synchronizedLibrary(Library library)
Returns a synchronized (thread-safe) library backed by the specified library. This wrapping will prevent simultaneous invocations of any functions mapped to a given Native.DeleteNativeLibrary. Note that the native library may still be sensitive to being called from different threads.

Parameters:
library - the library to be "wrapped" in a synchronized library.
Returns:
a synchronized view of the specified library.

getWebStartLibraryPath

public static java.lang.String getWebStartLibraryPath(java.lang.String libName)
If running web start, determine the location of a given native library. This value may be used to properly set jna.library.path so that JNA can load libraries identified by the <nativelib> tag in the JNLP configuration file. Returns null if the Web Start native library cache location can not be determined. Note that the path returned may be different for any given library name.

Use System.getProperty("javawebstart.version") to detect whether your code is running under Web Start.

Throws:
java.lang.IllegalArgumentException - if the library can't be found by the Web Start class loader, which usually means it wasn't included as a <nativelib> resource in the JNLP file.

getNativeSize

public static int getNativeSize(java.lang.Class cls)
Returns the native size for a given Java class. Structures are assumed to be struct pointers unless they implement Structure.ByValue.


isSupportedNativeType

public static boolean isSupportedNativeType(java.lang.Class cls)
Indicate whether the given class is supported as a native argument type.


setCallbackExceptionHandler

public static void setCallbackExceptionHandler(Callback.UncaughtExceptionHandler eh)
Set the default handler invoked when a callback throws an uncaught exception. If the given handler is null, the default handler will be reinstated.


getCallbackExceptionHandler

public static Callback.UncaughtExceptionHandler getCallbackExceptionHandler()
Returns the current handler for callback uncaught exceptions.


register

public static void register(java.lang.String libName)
When called from a class static initializer, maps all native methods found within that class to native libraries via the JNA raw calling interface.

Parameters:
libName - library name to which functions should be bound

register

public static void register(NativeLibrary lib)
When called from a class static initializer, maps all native methods found within that class to native libraries via the JNA raw calling interface.

Parameters:
lib - library to which functions should be bound

main

public static void main(java.lang.String[] args)
Prints JNA library details to the console.


JNA API 3.1.0

Copyright © 2007-2008 Timothy Wall. All Rights Reserved.