public final class Native extends java.lang.Object implements Version
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.
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(java.lang.String)
, 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).
loadLibrary(Class)
may be found in
several locations.Library
Modifier and Type | Class and Description |
---|---|
static interface |
Native.ffi_callback |
Modifier and Type | Field and Description |
---|---|
static int |
BOOL_SIZE
Size of a native
bool type (C99 and later), in bytes. |
(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 boolean |
DEBUG_JNA_LOAD |
static boolean |
DEBUG_LOAD |
static java.lang.String |
DEFAULT_ENCODING |
(package private) static java.lang.String |
JNA_TMPLIB_PREFIX |
(package private) static java.lang.String |
jnidispatchPath |
static int |
LONG_SIZE
Size of a native
long type, in bytes. |
(package private) static int |
MAX_ALIGNMENT |
(package private) static int |
MAX_PADDING |
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. |
VERSION, VERSION_NATIVE
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,
java.lang.reflect.Method method,
java.lang.Class<?>[] parameterTypes,
java.lang.Class<?> returnType,
int callingConvention,
int flags,
java.lang.String encoding)
Create a native trampoline to delegate execution to the Java callback.
|
(package private) static boolean |
deleteLibrary(java.io.File lib)
Remove any automatically unpacked native library.
|
static void |
detach(boolean detach)
Indicate whether the JVM should detach the current native thread when
the current Java code finishes execution.
|
static java.io.File |
extractFromResourcePath(java.lang.String name)
Attempt to extract a native library from the current resource path,
using the current thread context class loader.
|
static java.io.File |
extractFromResourcePath(java.lang.String name,
java.lang.ClassLoader loader)
Attempt to extract a native library from the resource path using the
given class loader.
|
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 java.lang.Class<?> |
findDirectMappedClass(java.lang.Class<?> cls)
Find the nearest enclosing class with native methods.
|
(package private) static java.lang.Class<?> |
findEnclosingLibraryClass(java.lang.Class<?> cls)
Find the library interface corresponding to the given class.
|
(package private) static long |
findSymbol(long handle,
java.lang.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(Pointer pointer,
long baseaddr,
long offset) |
(package private) static byte[] |
getBytes(java.lang.String s) |
(package private) static byte[] |
getBytes(java.lang.String s,
java.lang.String encoding) |
static Callback.UncaughtExceptionHandler |
getCallbackExceptionHandler() |
(package private) static java.lang.Class<?> |
getCallingClass()
Try to determine the class context in which a
register(String) call
was made. |
(package private) static char |
getChar(Pointer pointer,
long baseaddr,
long offset) |
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 java.lang.String |
getDefaultStringEncoding() |
static Pointer |
getDirectBufferPointer(java.nio.Buffer b)
Convert a direct
Buffer into a Pointer . |
static java.nio.ByteBuffer |
getDirectByteBuffer(long addr,
long length)
Deprecated.
Use
Pointer.getByteBuffer(long, long) (since 4.3.0) |
(package private) static java.nio.ByteBuffer |
getDirectByteBuffer(Pointer pointer,
long addr,
long offset,
long length) |
(package private) static double |
getDouble(Pointer pointer,
long baseaddr,
long offset) |
(package private) static float |
getFloat(Pointer pointer,
long baseaddr,
long offset) |
(package private) static int |
getInt(Pointer pointer,
long baseaddr,
long offset) |
static int |
getLastError()
Retrieve last error set by the OS.
|
static java.util.Map<java.lang.String,java.lang.Object> |
getLibraryOptions(java.lang.Class<?> type)
Return the preferred native library configuration options for the given
class.
|
(package private) static long |
getLong(Pointer pointer,
long baseaddr,
long offset) |
static int |
getNativeSize(java.lang.Class<?> cls)
Returns the native size for a given Java class.
|
static int |
getNativeSize(java.lang.Class<?> type,
java.lang.Object value) |
(package private) static Pointer |
getPointer(long addr) |
static boolean |
getPreserveLastError()
Deprecated.
Last error is always preserved and available via
getLastError() |
(package private) static short |
getShort(Pointer pointer,
long baseaddr,
long offset) |
(package private) static java.lang.String |
getSignature(java.lang.Class<?> cls) |
(package private) static java.lang.String |
getString(Pointer pointer,
long offset) |
(package private) static java.lang.String |
getString(Pointer pointer,
long offset,
java.lang.String encoding) |
(package private) static byte[] |
getStringBytes(Pointer pointer,
long baseaddr,
long offset) |
static java.lang.String |
getStringEncoding(java.lang.Class<?> cls) |
static int |
getStructureAlignment(java.lang.Class<?> cls) |
(package private) static java.io.File |
getTempDir()
Obtain a directory suitable for writing JNA-specific temporary files.
|
(package private) static Pointer |
getTerminationFlag(java.lang.Thread t) |
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.
|
(package private) static java.lang.String |
getWideString(Pointer pointer,
long baseaddr,
long offset) |
(package private) static long |
getWindowHandle0(java.awt.Component c) |
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. |
(package private) static long |
indexOf(Pointer pointer,
long baseaddr,
long offset,
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(Function function,
long fp,
int callFlags,
java.lang.Object[] args)
Call the native function.
|
(package private) static float |
invokeFloat(Function function,
long fp,
int callFlags,
java.lang.Object[] args)
Call the native function.
|
(package private) static int |
invokeInt(Function function,
long fp,
int callFlags,
java.lang.Object[] args)
Call the native function.
|
(package private) static long |
invokeLong(Function function,
long fp,
int callFlags,
java.lang.Object[] args)
Call the native function.
|
(package private) static java.lang.Object |
invokeObject(Function function,
long fp,
int callFlags,
java.lang.Object[] args)
Call the native function, returning a Java
Object . |
(package private) static long |
invokePointer(Function function,
long fp,
int callFlags,
java.lang.Object[] args)
Call the native function.
|
(package private) static Structure |
invokeStructure(Function function,
long fp,
int callFlags,
java.lang.Object[] args,
Structure s)
Call the native function, returning a struct by value.
|
(package private) static void |
invokeVoid(Function function,
long fp,
int callFlags,
java.lang.Object[] args)
Call the native function.
|
(package private) static boolean |
isCompatibleVersion(java.lang.String expectedVersion,
java.lang.String nativeVersion)
Version string must have the structure
|
static boolean |
isProtected()
Returns whether protection is enabled.
|
static boolean |
isSupportedNativeType(java.lang.Class<?> cls) |
(package private) static boolean |
isUnpacked(java.io.File file)
Identify temporary files unpacked from classpath jar files.
|
static <T> T |
loadLibrary(java.lang.Class<T> interfaceClass)
Map a library interface to the current process, providing
the explicit interface class.
|
static <T> T |
loadLibrary(java.lang.Class<T> interfaceClass,
java.util.Map<java.lang.String,?> options)
Map a library interface to the current process, providing
the explicit interface class.
|
static <T> T |
loadLibrary(java.lang.String name,
java.lang.Class<T> interfaceClass)
Map a library interface to the given shared library, providing
the explicit interface class.
|
static <T> T |
loadLibrary(java.lang.String name,
java.lang.Class<T> interfaceClass,
java.util.Map<java.lang.String,?> 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(java.lang.String[] args)
Prints JNA library details to the console.
|
static long |
malloc(long size)
Call the real native malloc
|
(package private) static void |
markTemporaryFile(java.io.File file)
Perform cleanup of automatically unpacked native shared library.
|
(package private) static long |
open(java.lang.String name)
Open the requested native library with default options.
|
(package private) static long |
open(java.lang.String name,
int flags)
Open the requested native library with the specified platform-specific
otions.
|
static float |
parseVersion(java.lang.String v)
Deprecated.
|
(package private) static void |
read(Pointer pointer,
long baseaddr,
long offset,
byte[] buf,
int index,
int length) |
(package private) static void |
read(Pointer pointer,
long baseaddr,
long offset,
char[] buf,
int index,
int length) |
(package private) static void |
read(Pointer pointer,
long baseaddr,
long offset,
double[] buf,
int index,
int length) |
(package private) static void |
read(Pointer pointer,
long baseaddr,
long offset,
float[] buf,
int index,
int length) |
(package private) static void |
read(Pointer pointer,
long baseaddr,
long offset,
int[] buf,
int index,
int length) |
(package private) static void |
read(Pointer pointer,
long baseaddr,
long offset,
long[] buf,
int index,
int length) |
(package private) static void |
read(Pointer pointer,
long baseaddr,
long offset,
short[] buf,
int index,
int length) |
static void |
register(java.lang.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(java.lang.Class<?> cls,
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 |
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 boolean |
registered(java.lang.Class<?> cls) |
(package private) static void |
removeTemporaryFiles()
Remove all marked temporary files in the given directory.
|
(package private) static java.lang.String |
replace(java.lang.String s1,
java.lang.String s2,
java.lang.String str) |
(package private) static void |
setByte(Pointer pointer,
long baseaddr,
long offset,
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(Pointer pointer,
long baseaddr,
long offset,
char value) |
(package private) static void |
setDouble(Pointer pointer,
long baseaddr,
long offset,
double value) |
(package private) static void |
setFloat(Pointer pointer,
long baseaddr,
long offset,
float value) |
(package private) static void |
setInt(Pointer pointer,
long baseaddr,
long offset,
int value) |
static void |
setLastError(int code)
Set the OS last error code.
|
(package private) static void |
setLong(Pointer pointer,
long baseaddr,
long offset,
long value) |
(package private) static void |
setMemory(Pointer pointer,
long baseaddr,
long offset,
long length,
byte value) |
(package private) static void |
setPointer(Pointer pointer,
long baseaddr,
long offset,
long value) |
static void |
setPreserveLastError(boolean enable)
Deprecated.
Last error is always preserved and available via
getLastError() |
static void |
setProtected(boolean enable)
Set whether native memory accesses are protected from invalid
accesses.
|
(package private) static void |
setShort(Pointer pointer,
long baseaddr,
long offset,
short value) |
(package private) static void |
setWideString(Pointer pointer,
long baseaddr,
long offset,
java.lang.String value) |
static Library |
synchronizedLibrary(Library library)
Returns a synchronized (thread-safe) library backed by the specified
library.
|
static byte[] |
toByteArray(java.lang.String s) |
static byte[] |
toByteArray(java.lang.String s,
java.lang.String encoding) |
static char[] |
toCharArray(java.lang.String s) |
static java.lang.String |
toString(byte[] buf)
Obtain a Java String from the given native byte array.
|
static java.lang.String |
toString(byte[] buf,
java.lang.String encoding)
Obtain a Java String from the given native byte array, using the given
encoding.
|
static java.lang.String |
toString(char[] buf)
Obtain a Java String from the given native wchar_t array.
|
static java.util.List<java.lang.String> |
toStringList(char[] buf)
Converts a "list" of strings each null terminated
into a
List of String values. |
static java.util.List<java.lang.String> |
toStringList(char[] buf,
int offset,
int len)
Converts a "list" of strings each null terminated
into a
List of String values. |
static void |
unregister()
Remove all native mappings for the calling class.
|
static void |
unregister(java.lang.Class<?> cls)
Remove all native mappings for the given class.
|
(package private) static void |
write(Pointer pointer,
long baseaddr,
long offset,
byte[] buf,
int index,
int length) |
(package private) static void |
write(Pointer pointer,
long baseaddr,
long offset,
char[] buf,
int index,
int length) |
(package private) static void |
write(Pointer pointer,
long baseaddr,
long offset,
double[] buf,
int index,
int length) |
(package private) static void |
write(Pointer pointer,
long baseaddr,
long offset,
float[] buf,
int index,
int length) |
(package private) static void |
write(Pointer pointer,
long baseaddr,
long offset,
int[] buf,
int index,
int length) |
(package private) static void |
write(Pointer pointer,
long baseaddr,
long offset,
long[] buf,
int index,
int length) |
(package private) static void |
write(Pointer pointer,
long baseaddr,
long offset,
short[] buf,
int index,
int length) |
public static final java.lang.String DEFAULT_ENCODING
public static boolean DEBUG_LOAD
public static boolean DEBUG_JNA_LOAD
static java.lang.String jnidispatchPath
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.public static final int BOOL_SIZE
bool
type (C99 and later), in bytes.static final int MAX_ALIGNMENT
static final int MAX_PADDING
static final java.lang.String JNA_TMPLIB_PREFIX
static final int CB_HAS_INITIALIZER
static final int CB_OPTION_DIRECT
static final int CB_OPTION_IN_DLL
@Deprecated public static float parseVersion(java.lang.String v)
static boolean isCompatibleVersion(java.lang.String expectedVersion, java.lang.String nativeVersion)
expectedVersion
- nativeVersion
- static boolean deleteLibrary(java.io.File lib)
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.@Deprecated public static void setPreserveLastError(boolean enable)
getLastError()
getLastError()
@Deprecated public static boolean getPreserveLastError()
getLastError()
true
getLastError()
public static long getWindowID(java.awt.Window w) throws java.awt.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.java.awt.HeadlessException
- if the current VM is running headlesspublic static long getComponentID(java.awt.Component c) throws java.awt.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.java.awt.HeadlessException
- if the current VM is running headlesspublic static Pointer getWindowPointer(java.awt.Window w) throws java.awt.HeadlessException
Window
as a Pointer
value. This method is primarily for
w32, which uses the HANDLE
type (actually
void *
) to identify windows.java.awt.HeadlessException
- if the current VM is running headlesspublic static Pointer getComponentPointer(java.awt.Component c) throws java.awt.HeadlessException
Component
as a Pointer
value. This method is primarily
for w32, which uses the HWND
type (actually
void *
) to identify windows.java.awt.HeadlessException
- if the current VM is running headlessstatic long getWindowHandle0(java.awt.Component c)
public static Pointer getDirectBufferPointer(java.nio.Buffer b)
Buffer
into a Pointer
.java.lang.IllegalArgumentException
- if the buffer is not direct.public static java.lang.String toString(byte[] buf)
getDefaultStringEncoding()
.buf
- The buffer containing the encoded bytestoString(byte[], String)
public static java.lang.String toString(byte[] buf, java.lang.String encoding)
Usage note: This function assumes, that buf
holds a char
array. This means only single-byte encodings are
supported.
buf
- The buffer containing the encoded bytesencoding
- The encoding name - if null
then the platform
default encoding will be usedpublic static java.lang.String toString(char[] buf)
buf
- The buffer containing the characterspublic static java.util.List<java.lang.String> toStringList(char[] buf)
List
of String
values. The end of the
list is signaled by an extra NULL value at the end or by the
end of the buffer.buf
- The buffer containing the stringsList
of all the strings in the buffertoStringList(char[], int, int)
public static java.util.List<java.lang.String> toStringList(char[] buf, int offset, int len)
List
of String
values. The end of the
list is signaled by an extra NULL value at the end or by the
end of the data.buf
- The buffer containing the stringsoffset
- Offset to start parsinglen
- The total characters to parseList
of all the strings in the bufferpublic static <T> T loadLibrary(java.lang.Class<T> interfaceClass)
T
- Type of expected wrapperinterfaceClass
- The implementation wrapper interfacejava.lang.UnsatisfiedLinkError
- if the library cannot be found or
dependent libraries are missing.public static <T> T loadLibrary(java.lang.Class<T> interfaceClass, java.util.Map<java.lang.String,?> options)
T
- Type of expected wrapperinterfaceClass
- The implementation wrapper interfaceoptions
- Map of library optionsjava.lang.UnsatisfiedLinkError
- if the library cannot be found or
dependent libraries are missing.loadLibrary(String, Class, Map)
public static <T> T loadLibrary(java.lang.String name, java.lang.Class<T> interfaceClass)
name
is null, attempts to map onto the current process.
Native libraries loaded via this method may be found in
several locations.T
- Type of expected wrappername
- Library base nameinterfaceClass
- The implementation wrapper interfacejava.lang.UnsatisfiedLinkError
- if the library cannot be found or
dependent libraries are missing.loadLibrary(String, Class, Map)
public static <T> T loadLibrary(java.lang.String name, java.lang.Class<T> interfaceClass, java.util.Map<java.lang.String,?> options)
If name
is null, attempts to map onto the current process.
Native libraries loaded via this method may be found in
several locations.
T
- Type of expected wrappername
- Library base nameinterfaceClass
- The implementation wrapper interfaceoptions
- Map of library optionsjava.lang.UnsatisfiedLinkError
- if the library cannot be found or
dependent libraries are missing.static java.lang.Class<?> findEnclosingLibraryClass(java.lang.Class<?> cls)
Library
.cls
- The given classpublic static java.util.Map<java.lang.String,java.lang.Object> getLibraryOptions(java.lang.Class<?> type)
OPTIONS
(a Map
), TYPE_MAPPER
(a TypeMapper
),
STRUCTURE_ALIGNMENT
(an Integer
), and
STRING_ENCODING
(a String
).type
- The type classpublic static TypeMapper getTypeMapper(java.lang.Class<?> cls)
TypeMapper
for the given native interface.
See Library.OPTION_TYPE_MAPPER
.public static java.lang.String getStringEncoding(java.lang.Class<?> cls)
cls
- The native interface typegetDefaultStringEncoding()
.Library.OPTION_STRING_ENCODING
public static java.lang.String getDefaultStringEncoding()
jna.encoding
or DEFAULT_ENCODING
.public static int getStructureAlignment(java.lang.Class<?> cls)
cls
- The native interface typeLibrary.OPTION_STRUCTURE_ALIGNMENT
static byte[] getBytes(java.lang.String s)
s
- The input stringgetDefaultStringEncoding()
.static byte[] getBytes(java.lang.String s, java.lang.String encoding)
s
- The stringencoding
- The encoding - if null
then the default platform
encoding is usedpublic static byte[] toByteArray(java.lang.String s)
s
- The stringgetDefaultStringEncoding()
.toByteArray(String, String)
public static byte[] toByteArray(java.lang.String s, java.lang.String encoding)
s
- The stringgetBytes(String, String)
public static char[] toCharArray(java.lang.String s)
s
- The stringstatic boolean isUnpacked(java.io.File file)
public static java.io.File extractFromResourcePath(java.lang.String name) throws java.io.IOException
name
- 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)
.java.io.IOException
- if resource not foundpublic static java.io.File extractFromResourcePath(java.lang.String name, java.lang.ClassLoader loader) throws java.io.IOException
name
- 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)
.loader
- Class loader to use to load resourcesjava.io.IOException
- if resource not foundpublic 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.
An alternative method of obtaining the last error result is
to declare your mapped method to throw LastErrorException
instead. If a method's signature includes a throw of LastErrorException
, the last error will be set to zero before the
native call and a LastErrorException
will be raised if the last
error value is non-zero after the call, regardless of the actual
returned value from the native function.
public static void setLastError(int code)
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 java.lang.String getWebStartLibraryPath(java.lang.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.
java.lang.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(java.io.File file)
static java.io.File getTempDir() throws java.io.IOException
jna.tmpdir
java.io.IOException
static void removeTemporaryFiles() throws java.io.IOException
java.io.IOException
public static int getNativeSize(java.lang.Class<?> type, java.lang.Object value)
type
- The Java class for which the native size is to be determinedvalue
- an instance of said class (if available)public static int getNativeSize(java.lang.Class<?> cls)
struct
pointers unless they implement
Structure.ByValue
.cls
- The Java classpublic static boolean isSupportedNativeType(java.lang.Class<?> cls)
cls
- The Java classtrue
whether the given class is supported as a native argument type.public static void setCallbackExceptionHandler(Callback.UncaughtExceptionHandler eh)
null
, the default
handler will be reinstated.eh
- The default handlerpublic static Callback.UncaughtExceptionHandler getCallbackExceptionHandler()
public static void register(java.lang.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 java.lang.Class<?> findDirectMappedClass(java.lang.Class<?> cls)
static java.lang.Class<?> getCallingClass()
register(String)
call
was made.public static void setCallbackThreadInitializer(Callback cb, CallbackThreadInitializer initializer)
cb
- The callback to invokeinitializer
- The thread initializer indicates desired thread configuration when the
given Callback is invoked on a native thread not yet attached to the VM.public static void unregister()
public static void unregister(java.lang.Class<?> cls)
public static boolean registered(java.lang.Class<?> cls)
cls
- The type Class
static java.lang.String getSignature(java.lang.Class<?> cls)
static java.lang.String replace(java.lang.String s1, java.lang.String s2, java.lang.String str)
public static void register(java.lang.Class<?> cls, java.lang.String libName)
jna.library.path
.cls
- Class with native methods to registerlibName
- name of or path to native library to which functions
should be boundpublic static void register(java.lang.Class<?> cls, NativeLibrary lib)
cls
- Class with native methods to registerlib
- 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(java.lang.String[] args)
static void freeNativeCallback(long ptr)
static long createNativeCallback(Callback callback, java.lang.reflect.Method method, java.lang.Class<?>[] parameterTypes, java.lang.Class<?> returnType, int callingConvention, int flags, java.lang.String encoding)
static int invokeInt(Function function, long fp, int callFlags, java.lang.Object[] args)
function
- Present to prevent the GC to collect the Function object
prematurelyfp
- function pointercallFlags
- calling convention to be usedargs
- Arguments to pass to the native functionstatic long invokeLong(Function function, long fp, int callFlags, java.lang.Object[] args)
function
- Present to prevent the GC to collect the Function object
prematurelyfp
- function pointercallFlags
- calling convention to be usedargs
- Arguments to pass to the native functionstatic void invokeVoid(Function function, long fp, int callFlags, java.lang.Object[] args)
function
- Present to prevent the GC to collect the Function object
prematurelyfp
- function pointercallFlags
- calling convention to be usedargs
- Arguments to pass to the native functionstatic float invokeFloat(Function function, long fp, int callFlags, java.lang.Object[] args)
function
- Present to prevent the GC to collect the Function object
prematurelyfp
- function pointercallFlags
- calling convention to be usedargs
- Arguments to pass to the native functionstatic double invokeDouble(Function function, long fp, int callFlags, java.lang.Object[] args)
function
- Present to prevent the GC to collect the Function object
prematurelyfp
- function pointercallFlags
- calling convention to be usedargs
- Arguments to pass to the native functionstatic long invokePointer(Function function, long fp, int callFlags, java.lang.Object[] args)
function
- Present to prevent the GC to collect the Function object
prematurelyfp
- function pointercallFlags
- calling convention to be usedargs
- Arguments to pass to the native functionstatic Structure invokeStructure(Function function, long fp, int callFlags, java.lang.Object[] args, Structure s)
function
- Present to prevent the GC to collect the Function object
prematurelyfp
- function pointercallFlags
- calling convention to be usedargs
- Arguments to pass to the native functionstatic java.lang.Object invokeObject(Function function, long fp, int callFlags, java.lang.Object[] args)
Object
.function
- Present to prevent the GC to collect the Function object
prematurelyfp
- function pointercallFlags
- calling convention to be usedargs
- Arguments to pass to the native functionObject
static long open(java.lang.String name)
static long open(java.lang.String name, int flags)
static void close(long handle)
static long findSymbol(long handle, java.lang.String name)
static long indexOf(Pointer pointer, long baseaddr, long offset, byte value)
static void read(Pointer pointer, long baseaddr, long offset, byte[] buf, int index, int length)
static void read(Pointer pointer, long baseaddr, long offset, short[] buf, int index, int length)
static void read(Pointer pointer, long baseaddr, long offset, char[] buf, int index, int length)
static void read(Pointer pointer, long baseaddr, long offset, int[] buf, int index, int length)
static void read(Pointer pointer, long baseaddr, long offset, long[] buf, int index, int length)
static void read(Pointer pointer, long baseaddr, long offset, float[] buf, int index, int length)
static void read(Pointer pointer, long baseaddr, long offset, double[] buf, int index, int length)
static void write(Pointer pointer, long baseaddr, long offset, byte[] buf, int index, int length)
static void write(Pointer pointer, long baseaddr, long offset, short[] buf, int index, int length)
static void write(Pointer pointer, long baseaddr, long offset, char[] buf, int index, int length)
static void write(Pointer pointer, long baseaddr, long offset, int[] buf, int index, int length)
static void write(Pointer pointer, long baseaddr, long offset, long[] buf, int index, int length)
static void write(Pointer pointer, long baseaddr, long offset, float[] buf, int index, int length)
static void write(Pointer pointer, long baseaddr, long offset, double[] buf, int index, int length)
static byte getByte(Pointer pointer, long baseaddr, long offset)
static char getChar(Pointer pointer, long baseaddr, long offset)
static short getShort(Pointer pointer, long baseaddr, long offset)
static int getInt(Pointer pointer, long baseaddr, long offset)
static long getLong(Pointer pointer, long baseaddr, long offset)
static float getFloat(Pointer pointer, long baseaddr, long offset)
static double getDouble(Pointer pointer, long baseaddr, long offset)
static Pointer getPointer(long addr)
static java.lang.String getWideString(Pointer pointer, long baseaddr, long offset)
static java.lang.String getString(Pointer pointer, long offset)
static java.lang.String getString(Pointer pointer, long offset, java.lang.String encoding)
static byte[] getStringBytes(Pointer pointer, long baseaddr, long offset)
static void setMemory(Pointer pointer, long baseaddr, long offset, long length, byte value)
static void setByte(Pointer pointer, long baseaddr, long offset, byte value)
static void setShort(Pointer pointer, long baseaddr, long offset, short value)
static void setChar(Pointer pointer, long baseaddr, long offset, char value)
static void setInt(Pointer pointer, long baseaddr, long offset, int value)
static void setLong(Pointer pointer, long baseaddr, long offset, long value)
static void setFloat(Pointer pointer, long baseaddr, long offset, float value)
static void setDouble(Pointer pointer, long baseaddr, long offset, double value)
static void setPointer(Pointer pointer, long baseaddr, long offset, long value)
static void setWideString(Pointer pointer, long baseaddr, long offset, java.lang.String value)
static java.nio.ByteBuffer getDirectByteBuffer(Pointer pointer, long addr, long offset, long length)
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.@Deprecated public static java.nio.ByteBuffer getDirectByteBuffer(long addr, long length)
Pointer.getByteBuffer(long, long)
(since 4.3.0)addr
- base address of the JNA-originated memorylength
- Length of ByteBufferpublic static void detach(boolean detach)
Indicate whether the JVM should detach the current native thread when the current Java code finishes execution. Generally this is used to avoid detaching native threads when it is known that a given thread will be relatively long-lived and call back to Java code frequently.
This call is lightweight; it only results in an additional JNI crossing if the desired state changes from its last setting.java.lang.IllegalStateException
- if detach(true)
is
called on a thread created by the JVM.static Pointer getTerminationFlag(java.lang.Thread t)