Top Description Inners Fields Constructors Methods
com.sun.jna

public final Class Native

extends Object
implements Version
Class Inheritance
All Implemented Interfaces
com.sun.jna.Version
Imports
java.awt.Component, .GraphicsEnvironment, .HeadlessException, .Window, java.io.File, .FileOutputStream, .FilenameFilter, .IOException, .InputStream, .UnsupportedEncodingException, java.lang.ref.Reference, .WeakReference, java.lang.reflect.Array, .Field, .InvocationHandler, .Method, .Modifier, .Proxy, java.net.URI, .URISyntaxException, .URL, .URLClassLoader, java.nio.Buffer, .ByteBuffer, java.nio.charset.Charset, .IllegalCharsetNameException, .UnsupportedCharsetException, java.security.AccessController, .PrivilegedAction, java.util.ArrayList, .Arrays, .Collections, .HashMap, .List, .Map, .StringTokenizer, .WeakHashMap, com.sun.jna.Callback.UncaughtExceptionHandler, .Structure.FFIType, java.util.logging.Level, .Logger

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

getTypeMapper and getStructureAlignment 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 any paths defined in jna.boot.library.path (if defined), then the system library path using System#loadLibrary, unless jna.nosys=true. If not found, the appropriate library will be extracted from the class path (into a temporary directory if found within a jar file) and loaded from there, unless jna.noclasspath=true. 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.

To avoid the automatic unpacking (in situations where you want to force a failure if the JNA native library is not properly installed on the system), set the system property jna.nounpack=true.

While this class and its corresponding native library are loaded, the system property jna.loaded will be set. The property will be cleared when native support has been unloaded (i.e. the Native class and its underlying native support has been GC'd).

Note

all native functions are provided within this class to ensure that all other JNA-provided classes and objects are GC'd and/or finalized/disposed before this class is disposed and/or removed from memory (most notably Memory and any other class which by default frees its resources in a finalizer).

Native Library Loading

Native libraries loaded via load(Class) may be found in several locations.
Authors
Todd Fast, [email protected], [email protected]
See Also
Library

Nested and Inner Type Summary

Modifier and TypeClass and Description
private static class
Native.AWT

Provides separation of JAWT functionality for the sake of J2ME ports which do not include AWT support.

private static class
public static interface

Field Summary

Modifier and TypeField and Description
private static final String
public static final int
BOOL_SIZE

Size of a native bool type (C99 and later), in bytes.

private static Callback.UncaughtExceptionHandler
pack-priv static final int
CB_HAS_INITIALIZER

Indicates whether the callback has an initializer.

pack-priv static final int
CB_OPTION_DIRECT

Use direct mapping for callback.

pack-priv static final int
CB_OPTION_IN_DLL

Return a DLL-resident fucntion pointer.

private static final int
private static final int
private static final int
private static final int
private static final int
private static final int
private static final int
private static final int
private static final int
private static final int
private static final int
private static final int
private static final int
private static final int
private static final int
private static final int
private static final int
private static final int
private static final int
private static final int
private static final int
private static final int
private static final int
private static final int
private static final int
private static final int
private static final int
private static final int
private static final int
private static final int
private static final int
public static final boolean
private static final Level
public static final boolean
public static final Charset
public static final String
private static final Callback.UncaughtExceptionHandler
private static final Object
finalizer

Force a dispose when the Native class is GC'd.

pack-priv static final String
pack-priv static String
private static final Map<Class<?>, Reference<?>>
private static final Logger
public static final int
LONG_DOUBLE_SIZE

Size of a native long double type (C99 and later), in bytes.

public static final int
LONG_SIZE

Size of a native long type, in bytes.

pack-priv static final int
pack-priv static final int
private static final Map<Thread, Pointer>
private static final ThreadLocal<Memory>
public static final int
POINTER_SIZE

The size of a native pointer (void*) on the current platform, in bytes.

private static final Map<Class<?>, long[]>
private static final Map<Class<?>, NativeLibrary>
public static final int
SIZE_T_SIZE

Size of a native size_t type, in bytes.

private static final int
private static final int
private static final int
private static final int
private static final int
private static final int
private static final Map<Class<?>, Map<String, Object>>
public static final int
WCHAR_SIZE

Size of a native wchar_t type, in bytes.

Constructor Summary

AccessConstructor and Description
private

Method Summary

Modifier and TypeMethod and Description
private static native long
private static native long
_getPointer(long addr)

private static Map<String, Object>
cacheOptions(Class<?> cls, Map<String, ?> options, Object proxy)

pack-priv static native void
close(long handle)

Close the given native library.

pack-priv static synchronized native long
createNativeCallback(Callback callback, Method method, Class<?>[] parameterTypes, Class<?> returnType, int callingConvention, int flags, String encoding)

Create a native trampoline to delegate execution to the Java callback.

pack-priv static boolean
deleteLibrary(File lib)

Remove any automatically unpacked native library.

public static void
detach(boolean detach)

Indicate whether the JVM should detach the current native thread when the current Java code finishes execution.

private static void
dispose()

Properly dispose of JNA functionality.

public static File

Returns:

File indicating extracted resource on disk
extractFromResourcePath
(String
Base name of native library to extract. May also be an absolute resource path (i.e. starts with "/"), in which case the no transformations of the library name are performed. If only the base name is given, the resource path is attempted both with and without Platform#RESOURCE_PREFIX, after mapping the library name via NativeLibrary#mapSharedLibraryName(String).
name
)

Attempt to extract a native library from the current resource path, using the current thread context class loader.

public static File

Returns:

File indicating extracted resource on disk
extractFromResourcePath
(String
Base name of native library to extract. May also be an absolute resource path (i.e. starts with "/"), in which case the no transformations of the library name are performed. If only the base name is given, the resource path is attempted both with and without Platform#RESOURCE_PREFIX, after mapping the library name via NativeLibrary#mapSharedLibraryName(String).
name
,
ClassLoader
Class loader to use to load resources
loader
)

Attempt to extract a native library from the resource path using the given class loader.

public static native void
ffi_call(long cif, long fptr, long resp, long args)

Make an FFI function call.

public static native void
ffi_free_closure(long closure)

public static native long
ffi_prep_cif(int abi, int nargs, long ffi_return_type, long ffi_types)

Create a new cif structure.

public static native long
pack-priv static Class<?>
findDirectMappedClass(Class<?> cls)

Find the nearest enclosing class with native methods.

pack-priv static Class<?>

Returns:

The enclosing class
findEnclosingLibraryClass
(Class<?>
The given class
cls
)

Find the library interface corresponding to the given class.

pack-priv static native long
findSymbol(long handle, String name)

public static native void
free(long
native address to be freed; a value of zero has no effect, passing an already-freed pointer will cause pain.
ptr
)

Call the real native free

pack-priv static synchronized native void
freeNativeCallback(long ptr)

Free the given callback trampoline.

private static NativeMapped
fromNative(Class<?> cls, Object value)

private static NativeMapped
private static Object
private static native String
pack-priv static native byte
getByte(Pointer pointer, long baseaddr, long offset)

pack-priv static byte[]

Returns:

A byte array corresponding to the given String. The encoding used is obtained from getDefaultStringEncoding().
getBytes
(String
The input string
s
)

pack-priv static byte[]

Returns:

A byte array corresponding to the given String, using the given encoding. If the encoding is not found default to the platform native encoding.
getBytes
(String
The string. Must not be null.
s
,
String
The encoding - if null then the default platform encoding is used
encoding
)

pack-priv static byte[]

Returns:

A byte array corresponding to the given String, using the given charset.
getBytes
(String
The string. Must not be null.
s
,
Charset
The charset used to encode s. Must not be null.
charset
)

public static Callback.UncaughtExceptionHandler

Returns:

the current handler for callback uncaught exceptions.
getCallbackExceptionHandler
()

pack-priv static Class<?>
getCallingClass()

Try to determine the class context in which a register(String) call was made.

pack-priv static native char
getChar(Pointer pointer, long baseaddr, long offset)

private static Charset

Returns:

The charset belonging to the given encoding or the platform default. Never null.
getCharset
(String
The encoding - if null then the default platform encoding is used.
encoding
)

Gets the charset belonging to the given encoding.

public static long
getComponentID(Component c)

Utility method to get the native window ID for a heavyweight Java Component as a long value.

public static Pointer
getComponentPointer(Component c)

Utility method to get the native window pointer for a heavyweight Java Component as a Pointer value.

private static int
getConversion(Class<?> type, TypeMapper mapper, boolean allowObjects)

public static String

Returns:

The default string encoding. Returns the value of the system property jna.encoding or Native#DEFAULT_ENCODING.
getDefaultStringEncoding
()

public static Pointer
getDirectBufferPointer(Buffer b)

Convert a direct Buffer into a Pointer.

pack-priv static native ByteBuffer
getDirectByteBuffer(Pointer pointer, long addr, long offset, long length)

pack-priv static native double
getDouble(Pointer pointer, long baseaddr, long offset)

pack-priv static native float
getFloat(Pointer pointer, long baseaddr, long offset)

pack-priv static native int
getInt(Pointer pointer, long baseaddr, long offset)

public static native int
getLastError()

Retrieve last error set by the OS.

public static Map<String, Object>

Returns:

The options map
getLibraryOptions
(Class<?>
The type class
type
)

Return the preferred native library configuration options for the given class.

pack-priv static native long
getLong(Pointer pointer, long baseaddr, long offset)

public static int

Returns:

the native size of the given class, in bytes. For use with arrays.
getNativeSize
(Class<?>
The Java class for which the native size is to be determined
type
,
Object
an instance of said class (if available)
value
)

public static int

Returns:

The native size for the class
getNativeSize
(Class<?>
The Java class
cls
)

Returns the native size for a given Java class.

private static native String
pack-priv static Pointer
getPointer(long addr)

pack-priv static native short
getShort(Pointer pointer, long baseaddr, long offset)

pack-priv static String
pack-priv static String
getString(Pointer pointer, long offset)

pack-priv static String
getString(Pointer pointer, long offset, String encoding)

pack-priv static native byte[]
getStringBytes(Pointer pointer, long baseaddr, long offset)

public static String

Returns:

The preferred string encoding for the given native interface. If there is no setting, defaults to the getDefaultStringEncoding().
getStringEncoding
(Class<?>
The native interface type
cls
)

public static int

Returns:

The preferred structure alignment for the given native interface.
getStructureAlignment
(Class<?>
The native interface type
cls
)

pack-priv static File
getTempDir()

Obtain a directory suitable for writing JNA-specific temporary files.

pack-priv static Pointer
public static TypeMapper
getTypeMapper(Class<?> cls)

Return the preferred TypeMapper for the given native interface.

public static String

Returns:

null if unable to query the web start loader.
getWebStartLibraryPath
(final String libName)

If running web start, determine the location of a given native library.

pack-priv static native String
getWideString(Pointer pointer, long baseaddr, long offset)

pack-priv static native long
public static long
getWindowID(Window w)

Utility method to get the native window ID for a Java Window as a long value.

public static Pointer
getWindowPointer(Window w)

Utility method to get the native window pointer for a Java Window as a Pointer value.

pack-priv static native long
indexOf(Pointer pointer, long baseaddr, long offset, byte value)

pack-priv static native int
initialize_ffi_type(long type_info)

Returns the size (calculated by libffi) of the given type.

private static native void
pack-priv static native double

Returns:

The value returned by the target native function
invokeDouble
(Function
Present to prevent the GC to collect the Function object prematurely
function
,
long
function pointer
fp
,
int
calling convention to be used
callFlags
,
Object[]
Arguments to pass to the native function
args
)

Call the native function.

pack-priv static native float

Returns:

The value returned by the target native function
invokeFloat
(Function
Present to prevent the GC to collect the Function object prematurely
function
,
long
function pointer
fp
,
int
calling convention to be used
callFlags
,
Object[]
Arguments to pass to the native function
args
)

Call the native function.

pack-priv static native int

Returns:

The value returned by the target native function
invokeInt
(Function
Present to prevent the GC to collect the Function object prematurely
function
,
long
function pointer
fp
,
int
calling convention to be used
callFlags
,
Object[]
Arguments to pass to the native function
args
)

Call the native function.

pack-priv static native long

Returns:

The value returned by the target native function
invokeLong
(Function
Present to prevent the GC to collect the Function object prematurely
function
,
long
function pointer
fp
,
int
calling convention to be used
callFlags
,
Object[]
Arguments to pass to the native function
args
)

Call the native function.

pack-priv static native Object

Returns:

The returned Java Object
invokeObject
(Function
Present to prevent the GC to collect the Function object prematurely
function
,
long
function pointer
fp
,
int
calling convention to be used
callFlags
,
Object[]
Arguments to pass to the native function
args
)

Call the native function, returning a Java Object.

pack-priv static native long

Returns:

The value returned by the target native function
invokePointer
(Function
Present to prevent the GC to collect the Function object prematurely
function
,
long
function pointer
fp
,
int
calling convention to be used
callFlags
,
Object[]
Arguments to pass to the native function
args
)

Call the native function.

private static native void
invokeStructure(Function
Present to prevent the GC to collect the Function object prematurely
function
,
long
function pointer
fp
,
int
calling convention to be used
callFlags
,
Object[]
Arguments to pass to the native function
args
,
long
Memory for pre-allocated structure to hold the result
memory
,
long
Native type information for the Structure
type_info
)

Call the native function, returning a struct by value.

pack-priv static Structure

Returns:

the passed-in Structure
invokeStructure
(Function
Present to prevent the GC to collect the Function object prematurely
function
,
long
function pointer
fp
,
int
calling convention to be used
callFlags
,
Object[]
Arguments to pass to the native function
args
,
Structure s)

Call the native function, returning a struct by value.

pack-priv static native void
invokeVoid(Function
Present to prevent the GC to collect the Function object prematurely
function
,
long
function pointer
fp
,
int
calling convention to be used
callFlags
,
Object[]
Arguments to pass to the native function
args
)

Call the native function.

pack-priv static boolean

Returns:

true if nativeVersion describes a version compatible to expectedVersion
isCompatibleVersion
(String expectedVersion, String nativeVersion)

Version string must have the structure <major>.

public static synchronized native boolean
isProtected()

Returns whether protection is enabled.

public static boolean

Returns:

true whether the given class is supported as a native argument type.
isSupportedNativeType
(Class<?>
The Java class
cls
)

pack-priv static boolean
isUnpacked(File file)

Identify temporary files unpacked from classpath jar files.

public static <
Type of expected wrapper
T extends Library
>
T

Returns:

an instance of the requested interface, mapped to the current process.
load
(Class<T>
The implementation wrapper interface
interfaceClass
)

Map a library interface to the current process, providing the explicit interface class.

public static <
Type of expected wrapper
T extends Library
>
T

Returns:

an instance of the requested interface, mapped to the current process.
load
(Class<T>
The implementation wrapper interface
interfaceClass
,
Map<String, ?>
Map of library options
options
)

Map a library interface to the current process, providing the explicit interface class.

public static <
Type of expected wrapper
T extends Library
>
T

Returns:

an instance of the requested interface, mapped to the indicated native library.
load
(String
Library base name
name
,
Class<T>
The implementation wrapper interface
interfaceClass
)

Map a library interface to the given shared library, providing the explicit interface class.

public static <
Type of expected wrapper
T extends Library
>
T

Returns:

an instance of the requested interface, mapped to the indicated native library.
load
(String
Library base name
name
,
Class<T>
The implementation wrapper interface
interfaceClass
,
Map<String, ?>
Map of library options
options
)

Load a library interface from the given shared library, providing the explicit interface class and a map of options for the library.

public static <T> T
loadLibrary(Class<T> interfaceClass)

Deprecated
Provided for improved compatibility between JNA 4.X and 5.X
public static <T> T
loadLibrary(Class<T> interfaceClass, Map<String, ?> options)

Deprecated
Provided for improved compatibility between JNA 4.X and 5.X
public static <T> T
loadLibrary(String name, Class<T> interfaceClass)

Deprecated
Provided for improved compatibility between JNA 4.X and 5.X
public static <T> T
loadLibrary(String name, Class<T> interfaceClass, Map<String, ?> options)

Deprecated
Provided for improved compatibility between JNA 4.X and 5.X
private static void
loadLibraryInstance(Class<?> cls)

Attempts to force initialization of an instance of the library interface by loading a public static field of the requisite type.

private static void
loadNativeDispatchLibrary()

Loads the JNA stub library.

private static void
loadNativeDispatchLibraryFromClasspath()

Attempts to load the native library resource from the filesystem, extracting the JNA stub library from jna.jar if not already available.

private static Object
lookupField(Class<?> mappingClass, String fieldName, Class<?> resultClass)

public static void
main(String[] args)

Prints JNA library details to the console.

public static native long

Returns:

native address of the allocated memory block; zero if the allocation failed.
malloc
(long
size of the memory to be allocated
size
)

Call the real native malloc

pack-priv static void
markTemporaryFile(File file)

Perform cleanup of automatically unpacked native shared library.

private static Class<?>
nativeType(Class<?> cls)

pack-priv static long
open(String name)

Open the requested native library with default options.

pack-priv static native long
open(String name, int flags)

Open the requested native library with the specified platform-specific otions.

pack-priv static native void
read(Pointer pointer, long baseaddr, long offset, byte[] buf, int index, int length)

pack-priv static native void
read(Pointer pointer, long baseaddr, long offset, short[] buf, int index, int length)

pack-priv static native void
read(Pointer pointer, long baseaddr, long offset, char[] buf, int index, int length)

pack-priv static native void
read(Pointer pointer, long baseaddr, long offset, int[] buf, int index, int length)

pack-priv static native void
read(Pointer pointer, long baseaddr, long offset, long[] buf, int index, int length)

pack-priv static native void
read(Pointer pointer, long baseaddr, long offset, float[] buf, int index, int length)

pack-priv static native void
read(Pointer pointer, long baseaddr, long offset, double[] buf, int index, int length)

public static void
register(String
library name to which functions should be bound
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.

public static void
register(NativeLibrary
native library to which functions should be bound
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.

public static void
register(Class<?>
Class with native methods to register
cls
,
String
name of or path to native library to which functions should be bound
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.

public static void
register(Class<?>
Class with native methods to register
cls
,
NativeLibrary
library to which functions should be bound
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.

public static boolean

Returns:

whether the given class's native components are registered.
registered
(Class<?>
The type Class
cls
)

private static native long
registerMethod(Class<?> cls, String name, String signature, int[] conversions, long[] closure_arg_types, long[] arg_types, int rconversion, long closure_rtype, long rtype, Method method, long fptr, int callingConvention, boolean throwLastError, ToNativeConverter[] toNative, FromNativeConverter fromNative, String encoding)

pack-priv static void
removeTemporaryFiles()

Remove all marked temporary files in the given directory.

pack-priv static String
replace(String s1, String s2, String str)

pack-priv static native void
setByte(Pointer pointer, long baseaddr, long offset, byte value)

public static void
setCallbackExceptionHandler(Callback.UncaughtExceptionHandler
The default handler
eh
)

Set the default handler invoked when a callback throws an uncaught exception.

public static void
setCallbackThreadInitializer(Callback
The callback to invoke
cb
,
CallbackThreadInitializer
The thread initializer indicates desired thread configuration when the given Callback is invoked on a native thread not yet attached to the VM.
initializer
)

Set a thread initializer for the given callback.

pack-priv static native void
setChar(Pointer pointer, long baseaddr, long offset, char value)

private static native void
setDetachState(boolean detach, long terminationFlag)

pack-priv static native void
setDouble(Pointer pointer, long baseaddr, long offset, double value)

pack-priv static native void
setFloat(Pointer pointer, long baseaddr, long offset, float value)

pack-priv static native void
setInt(Pointer pointer, long baseaddr, long offset, int value)

public static native void
setLastError(int code)

Set the OS last error code.

pack-priv static native void
setLong(Pointer pointer, long baseaddr, long offset, long value)

pack-priv static native void
setMemory(Pointer pointer, long baseaddr, long offset, long length, byte value)

pack-priv static native void
setPointer(Pointer pointer, long baseaddr, long offset, long value)

public static synchronized native void
setProtected(boolean enable)

Set whether native memory accesses are protected from invalid accesses.

pack-priv static native void
setShort(Pointer pointer, long baseaddr, long offset, short value)

pack-priv static native void
setWideString(Pointer pointer, long baseaddr, long offset, String value)

private static native int
sizeof(int type)

Initialize field and method IDs for native methods of this class.

public static Library

Returns:

a synchronized view of the specified library.
synchronizedLibrary
(final Library
the library to be "wrapped" in a synchronized library.
library
)

Returns a synchronized (thread-safe) library backed by the specified library.

public static byte[]

Returns:

A NUL-terminated byte buffer equivalent to the given String, using the encoding returned by getDefaultStringEncoding().
toByteArray
(String
The string
s
)

public static byte[]

Returns:

A NUL-terminated byte buffer equivalent to the given String, using the given encoding.
toByteArray
(String
The string. Must not be null.
s
,
String
The encoding - if null then the default platform encoding is used
encoding
)

public static byte[]

Returns:

A NUL-terminated byte buffer equivalent to the given String, using the given charset.
toByteArray
(String
The string. Must not be null.
s
,
Charset
The charset used to encode s. Must not be null.
charset
)

public static char[]

Returns:

A NUL-terminated wide character buffer equivalent to the given string.
toCharArray
(String
The string
s
)

private static Object
public static String
toString(byte[]
The buffer containing the encoded bytes
buf
)

Obtain a Java String from the given native byte array.

public static String
toString(byte[]
The buffer containing the encoded bytes. Must not be null.
buf
,
String
The encoding name - if null then the platform default encoding will be used
encoding
)

Obtain a Java String from the given native byte array, using the given encoding.

public static String
toString(byte[]
The buffer containing the encoded bytes. Must not be null.
buf
,
Charset
The charset to decode buf. Must not be null.
charset
)

Obtain a Java String from the given native byte array, using the given encoding.

public static String
toString(char[]
The buffer containing the characters
buf
)

Obtain a Java String from the given native wchar_t array.

public static List<String>

Returns:

A List of all the strings in the buffer
toStringList
(char[]
The buffer containing the strings
buf
)

Converts a "list" of strings each null terminated into a List of String values.

public static List<String>

Returns:

A List of all the strings in the buffer
toStringList
(char[]
The buffer containing the strings
buf
,
int
Offset to start parsing
offset
,
int
The total characters to parse
len
)

Converts a "list" of strings each null terminated into a List of String values.

public static void
unregister()

Remove all native mappings for the calling class.

public static void
unregister(Class<?> cls)

Remove all native mappings for the given class.

private static native void
unregister(Class<?> cls, long[] handles)

private static void
pack-priv static native void
write(Pointer pointer, long baseaddr, long offset, byte[] buf, int index, int length)

pack-priv static native void
write(Pointer pointer, long baseaddr, long offset, short[] buf, int index, int length)

pack-priv static native void
write(Pointer pointer, long baseaddr, long offset, char[] buf, int index, int length)

pack-priv static native void
write(Pointer pointer, long baseaddr, long offset, int[] buf, int index, int length)

pack-priv static native void
write(Pointer pointer, long baseaddr, long offset, long[] buf, int index, int length)

pack-priv static native void
write(Pointer pointer, long baseaddr, long offset, float[] buf, int index, int length)

pack-priv static native void
write(Pointer pointer, long baseaddr, long offset, double[] buf, int index, int length)

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait