|
JNA API> 3.3.0 | ||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectcom.sun.jna.Native
public final class Native
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 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.
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.
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
Nested Class Summary | |
---|---|
static interface |
Native.ffi_callback
|
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 void |
close(long handle)
|
(package private) static long |
createNativeCallback(Callback callback,
Method method,
Class[] parameterTypes,
Class returnType,
int callingConvention,
boolean direct)
Create a native trampoline to delegate execution to the Java callback. |
static void |
ffi_call(long cif,
long fptr,
long resp,
long args)
|
static void |
ffi_free_closure(long closure)
|
static long |
ffi_prep_cif(int abi,
int nargs,
long ffi_return_type,
long ffi_types)
|
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)
Utility method to get the native window pointer for a heavyweight Java Component as a Pointer value. |
static Pointer |
getDirectBufferPointer(Buffer b)
Convert a direct Buffer into a Pointer . |
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)
|
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()
|
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. |
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)
Utility method to get the native window pointer for a Java Window as a Pointer value. |
(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)
|
(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. |
(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)
|
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Field Detail |
---|
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.
Method Detail |
---|
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 headlesspublic static Pointer getDirectBufferPointer(Buffer b)
Buffer
into a Pointer
.
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()
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 getNativeClass(Class cls)
static Class getCallingClass()
public static void unregister()
public static void unregister(Class cls)
static String replace(String s1, String s2, String str)
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, boolean direct)
static int invokeInt(long fp, int callFlags, Object[] args)
fp
- function pointercallFlags
- calling convention to be usedargs
- Arguments to pass to the native function
static long invokeLong(long fp, int callFlags, Object[] args)
fp
- function pointercallFlags
- calling convention to be usedargs
- Arguments to pass to the native function
static 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 function
static double invokeDouble(long fp, int callFlags, Object[] args)
fp
- function pointercallFlags
- calling convention to be usedargs
- Arguments to pass to the native function
static long invokePointer(long fp, int callFlags, Object[] args)
fp
- function pointercallFlags
- calling convention to be usedargs
- Arguments to pass to the native function
static Structure invokeStructure(long fp, int callFlags, Object[] args, Structure s)
fp
- function pointercallFlags
- calling convention to be usedargs
- Arguments to pass to the native function
static Object invokeObject(long fp, int callFlags, Object[] args)
Object
.
fp
- function pointercallFlags
- calling convention to be usedargs
- Arguments to pass to the native function
Object
static long open(String name)
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 allocated
public 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
- byte offset from pointer to start the bufferlength
- Length of ByteBuffer
|
JNA API> 3.3.0 | ||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |