public final class Native extends Object
getTypeMapper(java.lang.Class)
and getStructureAlignment(java.lang.Class)
are provided
to avoid having to explicitly pass these parameters to Structure
s,
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.
jna.boot.library.path
(if defined), then the system library
path using System.loadLibrary(java.lang.String)
, unless jna.nosys=true
.
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.
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
.
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).Library
Modifier and Type | Class and Description |
---|---|
static interface |
Native.ffi_callback |
Modifier and Type | Field and Description |
---|---|
(package private) static int |
CB_HAS_INITIALIZER
Indicates whether the callback has an initializer.
|
(package private) static int |
CB_OPTION_DIRECT
Use direct mapping for callback.
|
(package private) static int |
CB_OPTION_IN_DLL
Return a DLL-resident fucntion pointer.
|
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. |
Modifier and Type | Method and Description |
---|---|
(package private) static void |
close(long handle)
Close the given native library.
|
(package private) static long |
createNativeCallback(Callback callback,
Method method,
Class[] parameterTypes,
Class returnType,
int callingConvention,
int flags)
Create a native trampoline to delegate execution to the Java callback.
|
static void |
detach(boolean detach)
Indicate the desired attachment state for the current thread.
|
static void |
ffi_call(long cif,
long fptr,
long resp,
long args)
Make an FFI function call.
|
static void |
ffi_free_closure(long closure) |
static long |
ffi_prep_cif(int abi,
int nargs,
long ffi_return_type,
long ffi_types)
Create a new cif structure.
|
static long |
ffi_prep_closure(long cif,
Native.ffi_callback cb) |
(package private) static Class |
findEnclosingLibraryClass(Class cls)
Find the library interface corresponding to the given class.
|
(package private) static long |
findSymbol(long handle,
String name) |
static void |
free(long ptr)
Call the real native free
|
(package private) static void |
freeNativeCallback(long ptr)
Free the given callback trampoline.
|
(package private) static byte |
getByte(long addr) |
(package private) static byte[] |
getBytes(String s)
Return a byte array corresponding to the given String.
|
(package private) static byte[] |
getBytes(String s,
String encoding)
Return a byte array corresponding to the given String, using the given
encoding.
|
static Callback.UncaughtExceptionHandler |
getCallbackExceptionHandler()
Returns the current handler for callback uncaught exceptions.
|
(package private) static Class |
getCallingClass() |
(package private) static char |
getChar(long addr) |
static long |
getComponentID(Component c)
Utility method to get the native window ID for a heavyweight Java
Component as a long value. |
static Pointer |
getComponentPointer(Component c)
|
static Pointer |
getDirectBufferPointer(Buffer b)
|
static ByteBuffer |
getDirectByteBuffer(long addr,
long length)
Get a direct ByteBuffer mapped to the memory pointed to by the pointer.
|
(package private) static double |
getDouble(long addr) |
(package private) static float |
getFloat(long addr) |
(package private) static int |
getInt(long addr) |
static int |
getLastError()
Retrieve the last error set by the OS.
|
static Map |
getLibraryOptions(Class type)
Return the preferred native library configuration options for the given
class.
|
(package private) static long |
getLong(long addr) |
(package private) static Class |
getNativeClass(Class cls) |
(package private) static String |
getNativeLibraryResourcePath(int osType,
String arch,
String name)
Generate a canonical String prefix based on the given OS
type/arch/name.
|
static int |
getNativeSize(Class cls)
Returns the native size for a given Java class.
|
static int |
getNativeSize(Class type,
Object value)
Returns the native size of the given class, in bytes.
|
(package private) static Pointer |
getPointer(long addr) |
static boolean |
getPreserveLastError()
Deprecated.
The preferred method of obtaining the last error result is
to declare your mapped method to throw
LastErrorException
instead. |
(package private) static short |
getShort(long addr) |
(package private) static String |
getString(long addr,
boolean wide) |
static int |
getStructureAlignment(Class cls)
Return the preferred structure alignment for the given native interface.
|
(package private) static File |
getTempDir()
Obtain a directory suitable for writing JNA-specific temporary files.
|
static TypeMapper |
getTypeMapper(Class cls)
Return the preferred
TypeMapper for the given native interface. |
static String |
getWebStartLibraryPath(String libName)
If running web start, determine the location of a given native
library.
|
(package private) static long |
getWindowHandle0(Component c) |
static long |
getWindowID(Window w)
Utility method to get the native window ID for a Java
Window
as a long value. |
static Pointer |
getWindowPointer(Window w)
|
(package private) static long |
indexOf(long addr,
byte value) |
(package private) static int |
initialize_ffi_type(long type_info)
Returns the size (calculated by libffi) of the given type.
|
(package private) static double |
invokeDouble(long fp,
int callFlags,
Object[] args)
Call the native function being represented by this object
|
(package private) static float |
invokeFloat(long fp,
int callFlags,
Object[] args)
Call the native function being represented by this object
|
(package private) static int |
invokeInt(long fp,
int callFlags,
Object[] args)
Call the native function being represented by this object
|
(package private) static long |
invokeLong(long fp,
int callFlags,
Object[] args)
Call the native function being represented by this object
|
(package private) static Object |
invokeObject(long fp,
int callFlags,
Object[] args)
Call the native function being represented by this object, returning
a Java
Object . |
(package private) static long |
invokePointer(long fp,
int callFlags,
Object[] args)
Call the native function being represented by this object
|
(package private) static Structure |
invokeStructure(long fp,
int callFlags,
Object[] args,
Structure s)
Call the native function being represented by this object, returning
a struct by value.
|
(package private) static void |
invokeVoid(long fp,
int callFlags,
Object[] args)
Call the native function being represented by this object
|
static boolean |
isProtected()
Returns whether protection is enabled.
|
static boolean |
isSupportedNativeType(Class cls)
Indicate whether the given class is supported as a native argument
type.
|
static Object |
loadLibrary(Class interfaceClass)
Map a library interface to the current process, providing
the explicit interface class.
|
static Object |
loadLibrary(Class interfaceClass,
Map options)
Map a library interface to the current process, providing
the explicit interface class.
|
static Object |
loadLibrary(String name,
Class interfaceClass)
Map a library interface to the given shared library, providing
the explicit interface class.
|
static Object |
loadLibrary(String name,
Class interfaceClass,
Map options)
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(String[] args)
Prints JNA library details to the console.
|
static long |
malloc(long size)
Call the real native malloc
|
(package private) static void |
markTemporaryFile(File file)
Perform cleanup of automatically unpacked native shared library.
|
(package private) static long |
open(String name)
Open the requested native library with default options.
|
(package private) static long |
open(String name,
int flags)
Open the requested native library with the specified platform-specific
otions.
|
(package private) static void |
read(long addr,
byte[] buf,
int index,
int length) |
(package private) static void |
read(long addr,
char[] buf,
int index,
int length) |
(package private) static void |
read(long addr,
double[] buf,
int index,
int length) |
(package private) static void |
read(long addr,
float[] buf,
int index,
int length) |
(package private) static void |
read(long addr,
int[] buf,
int index,
int length) |
(package private) static void |
read(long addr,
long[] buf,
int index,
int length) |
(package private) static void |
read(long addr,
short[] buf,
int index,
int length) |
static void |
register(Class cls,
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(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(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.
|
(package private) static void |
removeTemporaryFiles()
Remove all marked temporary files in the given directory.
|
(package private) static String |
replace(String s1,
String s2,
String str) |
(package private) static void |
setByte(long addr,
byte value) |
static void |
setCallbackExceptionHandler(Callback.UncaughtExceptionHandler eh)
Set the default handler invoked when a callback throws an uncaught
exception.
|
static void |
setCallbackThreadInitializer(Callback cb,
CallbackThreadInitializer initializer)
Set a thread initializer for the given callback.
|
(package private) static void |
setChar(long addr,
char value) |
(package private) static void |
setDouble(long addr,
double value) |
(package private) static void |
setFloat(long addr,
float value) |
(package private) static void |
setInt(long addr,
int value) |
static void |
setLastError(int code)
Set the OS last error code.
|
(package private) static void |
setLong(long addr,
long value) |
(package private) static void |
setMemory(long addr,
long length,
byte value) |
(package private) static void |
setPointer(long addr,
long value) |
static void |
setPreserveLastError(boolean enable)
Deprecated.
The preferred method of obtaining the last error result is
to declare your mapped method to throw
LastErrorException
instead. |
static void |
setProtected(boolean enable)
Set whether native memory accesses are protected from invalid
accesses.
|
(package private) static void |
setShort(long addr,
short value) |
(package private) static void |
setString(long addr,
String value,
boolean wide) |
static Library |
synchronizedLibrary(Library library)
Returns a synchronized (thread-safe) library backed by the specified
library.
|
static byte[] |
toByteArray(String s)
Obtain a NUL-terminated byte buffer equivalent to the given String,
using
jna.encoding or the default platform encoding if
that property is not set. |
static byte[] |
toByteArray(String s,
String encoding)
Obtain a NUL-terminated byte buffer equivalent to the given String,
using the given encoding.
|
static char[] |
toCharArray(String s)
Obtain a NUL-terminated wide character buffer equivalent to the given
String.
|
static String |
toString(byte[] buf)
Obtain a Java String from the given native byte array.
|
static String |
toString(byte[] buf,
String encoding)
Obtain a Java String from the given native byte array, using the given
encoding.
|
static String |
toString(char[] buf)
Obtain a Java String from the given native wchar_t array.
|
static void |
unregister()
Remove all native mappings for the calling class.
|
static void |
unregister(Class cls)
Remove all native mappings for the given class.
|
(package private) static void |
updateLastError(int e)
Update the last error value (called from native code).
|
(package private) static void |
write(long addr,
byte[] buf,
int index,
int length) |
(package private) static void |
write(long addr,
char[] buf,
int index,
int length) |
(package private) static void |
write(long addr,
double[] buf,
int index,
int length) |
(package private) static void |
write(long addr,
float[] buf,
int index,
int length) |
(package private) static void |
write(long addr,
int[] buf,
int index,
int length) |
(package private) static void |
write(long addr,
long[] buf,
int index,
int length) |
(package private) static void |
write(long addr,
short[] buf,
int index,
int length) |
public static final int POINTER_SIZE
void*
) on the current
platform, in bytes.public static final int LONG_SIZE
long
type, in bytes.public static final int WCHAR_SIZE
wchar_t
type, in bytes.public static final int SIZE_T_SIZE
size_t
type, in bytes.static final int CB_HAS_INITIALIZER
static final int CB_OPTION_DIRECT
static final int CB_OPTION_IN_DLL
public static void setProtected(boolean enable)
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: On platforms which support signals (non-Windows), JNA uses
signals to trap errors. This may interfere with the JVM's own use of
signals. When protected mode is enabled, you should make use of the
jsig library, if available (see Signal Chaining).
In short, set the environment variable 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.
public static boolean isProtected()
setProtected(true)
to determine
if this platform supports protecting memory accesses.public static void setPreserveLastError(boolean enable)
LastErrorException
instead.true
(false
for direct-mapped calls).public static boolean getPreserveLastError()
LastErrorException
instead.public static long getWindowID(Window w) throws HeadlessException
Window
as a long
value.
This method is primarily for X11-based systems, which use an opaque
XID
(usually long int
) to identify windows.HeadlessException
- if the current VM is running headlesspublic static long getComponentID(Component c) throws HeadlessException
Component
as a long
value.
This method is primarily for X11-based systems, which use an opaque
XID
(usually long int
) to identify windows.HeadlessException
- if the current VM is running headlesspublic static Pointer getWindowPointer(Window w) throws HeadlessException
Window
as a Pointer
value. This method is primarily for
w32, which uses the HANDLE
type (actually
void *
) to identify windows.HeadlessException
- if the current VM is running headlesspublic static Pointer getComponentPointer(Component c) throws HeadlessException
Component
as a Pointer
value. This method is primarily
for w32, which uses the HWND
type (actually
void *
) to identify windows.HeadlessException
- if the current VM is running headlessstatic long getWindowHandle0(Component c)
public static Pointer getDirectBufferPointer(Buffer b)
IllegalArgumentException
- if the buffer is not direct.public static String toString(byte[] buf)
jna.encoding
is set, its value will
override the platform default encoding (if supported).public static String toString(byte[] buf, String encoding)
encoding
parameter is null,
the platform default encoding will be used.public static String toString(char[] buf)
public static Object loadLibrary(Class interfaceClass)
interfaceClass
- public static Object loadLibrary(Class interfaceClass, Map options)
interfaceClass
- options
- Map of library optionspublic static Object loadLibrary(String name, Class interfaceClass)
name
is null, attempts to map onto the current process.name
- interfaceClass
- public static Object loadLibrary(String name, Class interfaceClass, Map options)
If name
is null, attempts to map onto the current process.
name
- interfaceClass
- options
- Map of library optionsstatic Class findEnclosingLibraryClass(Class cls)
Library
.public static Map getLibraryOptions(Class type)
Library
public static TypeMapper getTypeMapper(Class cls)
TypeMapper
for the given native interface.
See Library.OPTION_TYPE_MAPPER
.public static int getStructureAlignment(Class cls)
Library.OPTION_STRUCTURE_ALIGNMENT
.static byte[] getBytes(String s)
jna.encoding
is set, its value will override
the default platform encoding (if supported).static byte[] getBytes(String s, String encoding) throws UnsupportedEncodingException
UnsupportedEncodingException
public static byte[] toByteArray(String s)
jna.encoding
or the default platform encoding if
that property is not set.public static byte[] toByteArray(String s, String encoding) throws UnsupportedEncodingException
UnsupportedEncodingException
public static char[] toCharArray(String s)
static String getNativeLibraryResourcePath(int osType, String arch, String name)
public static int getLastError()
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
.
The preferred method of obtaining the last error result is
to declare your mapped method to throw LastErrorException
instead.
public static void setLastError(int code)
static void updateLastError(int e)
public static Library synchronizedLibrary(Library library)
NativeLibrary
. Note that the
native library may still be sensitive to being called from different
threads.
library
- the library to be "wrapped" in a synchronized library.public static String getWebStartLibraryPath(String libName)
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.
UnsatisfiedLinkError
- 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.static void markTemporaryFile(File file)
static File getTempDir()
jna.tmpdir
static void removeTemporaryFiles()
public static int getNativeSize(Class type, Object value)
public static int getNativeSize(Class cls)
struct
pointers unless they implement
Structure.ByValue
.public static boolean isSupportedNativeType(Class cls)
public static void setCallbackExceptionHandler(Callback.UncaughtExceptionHandler eh)
null
, the default
handler will be reinstated.public static Callback.UncaughtExceptionHandler getCallbackExceptionHandler()
public static void register(String libName)
libName
- library name to which functions should be boundpublic static void register(NativeLibrary lib)
lib
- native library to which functions should be boundstatic Class getCallingClass()
public static void setCallbackThreadInitializer(Callback cb, CallbackThreadInitializer initializer)
public static void unregister()
public static void unregister(Class cls)
public static void register(Class cls, NativeLibrary lib)
lib
- library to which functions should be boundpublic static long ffi_prep_cif(int abi, int nargs, long ffi_return_type, long ffi_types)
public static void ffi_call(long cif, long fptr, long resp, long args)
public static long ffi_prep_closure(long cif, Native.ffi_callback cb)
public static void ffi_free_closure(long closure)
static int initialize_ffi_type(long type_info)
public static void main(String[] args)
static void freeNativeCallback(long ptr)
static long createNativeCallback(Callback callback, Method method, Class[] parameterTypes, Class returnType, int callingConvention, int flags)
static int invokeInt(long fp, int callFlags, Object[] args)
fp
- function pointercallFlags
- calling convention to be usedargs
- Arguments to pass to the native functionstatic long invokeLong(long fp, int callFlags, Object[] args)
fp
- function pointercallFlags
- calling convention to be usedargs
- Arguments to pass to the native functionstatic void invokeVoid(long fp, int callFlags, Object[] args)
fp
- function pointercallFlags
- calling convention to be usedargs
- Arguments to pass to the native functionstatic float invokeFloat(long fp, int callFlags, Object[] args)
fp
- function pointercallFlags
- calling convention to be usedargs
- Arguments to pass to the native functionstatic double invokeDouble(long fp, int callFlags, Object[] args)
fp
- function pointercallFlags
- calling convention to be usedargs
- Arguments to pass to the native functionstatic long invokePointer(long fp, int callFlags, Object[] args)
fp
- function pointercallFlags
- calling convention to be usedargs
- Arguments to pass to the native functionstatic Structure invokeStructure(long fp, int callFlags, Object[] args, Structure s)
fp
- function pointercallFlags
- calling convention to be usedargs
- Arguments to pass to the native functionstatic Object invokeObject(long fp, int callFlags, Object[] args)
Object
.fp
- function pointercallFlags
- calling convention to be usedargs
- Arguments to pass to the native functionObject
static long open(String name)
static long open(String name, int flags)
static void close(long handle)
static long findSymbol(long handle, String name)
static long indexOf(long addr, byte value)
static void read(long addr, byte[] buf, int index, int length)
static void read(long addr, short[] buf, int index, int length)
static void read(long addr, char[] buf, int index, int length)
static void read(long addr, int[] buf, int index, int length)
static void read(long addr, long[] buf, int index, int length)
static void read(long addr, float[] buf, int index, int length)
static void read(long addr, double[] buf, int index, int length)
static void write(long addr, byte[] buf, int index, int length)
static void write(long addr, short[] buf, int index, int length)
static void write(long addr, char[] buf, int index, int length)
static void write(long addr, int[] buf, int index, int length)
static void write(long addr, long[] buf, int index, int length)
static void write(long addr, float[] buf, int index, int length)
static void write(long addr, double[] buf, int index, int length)
static byte getByte(long addr)
static char getChar(long addr)
static short getShort(long addr)
static int getInt(long addr)
static long getLong(long addr)
static float getFloat(long addr)
static double getDouble(long addr)
static Pointer getPointer(long addr)
static String getString(long addr, boolean wide)
static void setMemory(long addr, long length, byte value)
static void setByte(long addr, byte value)
static void setShort(long addr, short value)
static void setChar(long addr, char value)
static void setInt(long addr, int value)
static void setLong(long addr, long value)
static void setFloat(long addr, float value)
static void setDouble(long addr, double value)
static void setPointer(long addr, long value)
static void setString(long addr, String value, boolean wide)
public static long malloc(long size)
size
- size of the memory to be allocatedpublic static void free(long ptr)
ptr
- native address to be freed; a value of zero has no effect,
passing an already-freed pointer will cause pain.public static ByteBuffer getDirectByteBuffer(long addr, long length)
addr
- base address of the JNA-originated memorylength
- Length of ByteBufferpublic static void detach(boolean detach)
detach(true)
on threads
spawned by the JVM; the resulting behavior is not defined.