|
JNA API> 3.1.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.
Native.DeleteNativeLibrary
Nested Class Summary | |
---|---|
static class |
Native.DeleteNativeLibrary
For internal use only. |
Field Summary | |
---|---|
static int |
LONG_SIZE
Size of a native long type, in bytes. |
static int |
POINTER_SIZE
The size of a native pointer ( void* ) on the current
platform, in bytes. |
static int |
SIZE_T_SIZE
Size of a native size_t type, in bytes. |
static int |
WCHAR_SIZE
Size of a native wchar_t type, in bytes. |
Method Summary | |
---|---|
(package private) static java.lang.Class |
findCallbackClass(java.lang.Class type)
Find the first instance of an interface which implements the Callback interface or an interface derived from Callback. |
(package private) static java.lang.Class |
findEnclosingLibraryClass(java.lang.Class cls)
Find the library interface corresponding to the given class. |
static Pointer |
getByteBufferPointer(java.nio.ByteBuffer b)
Deprecated. Use getDirectBufferPointer(java.nio.Buffer) instead. |
(package private) static byte[] |
getBytes(java.lang.String s)
Return a byte array corresponding to the given String. |
static Callback.UncaughtExceptionHandler |
getCallbackExceptionHandler()
Returns the current handler for callback uncaught exceptions. |
static long |
getComponentID(java.awt.Component c)
Utility method to get the native window ID for a heavyweight Java Component as a long value. |
static Pointer |
getComponentPointer(java.awt.Component c)
Utility method to get the native window pointer for a heavyweight Java Component as a Pointer value. |
static Pointer |
getDirectBufferPointer(java.nio.Buffer b)
Convert a direct Buffer into a Pointer . |
static int |
getLastError()
Retrieve the last error set by the OS. |
static java.util.Map |
getLibraryOptions(java.lang.Class type)
Return the preferred native library configuration options for the given class. |
static int |
getNativeSize(java.lang.Class cls)
Returns the native size for a given Java class. |
static boolean |
getPreserveLastError()
Indicates whether the system last error result is preserved after every invocation. |
static int |
getStructureAlignment(java.lang.Class cls)
Return the preferred structure alignment for the given native interface. |
static TypeMapper |
getTypeMapper(java.lang.Class cls)
Return the preferred TypeMapper for the given native interface. |
static java.lang.String |
getWebStartLibraryPath(java.lang.String libName)
If running web start, determine the location of a given native library. |
static long |
getWindowID(java.awt.Window w)
Utility method to get the native window ID for a Java Window
as a long value. |
static Pointer |
getWindowPointer(java.awt.Window w)
Utility method to get the native window pointer for a Java Window as a Pointer value. |
static boolean |
isProtected()
Returns whether protection is enabled. |
static boolean |
isSupportedNativeType(java.lang.Class cls)
Indicate whether the given class is supported as a native argument type. |
static java.lang.Object |
loadLibrary(java.lang.String name,
java.lang.Class interfaceClass)
Load a library interface from the given shared library, providing the explicit interface class. |
static java.lang.Object |
loadLibrary(java.lang.String name,
java.lang.Class interfaceClass,
java.util.Map libOptions)
Load a library interface from the given shared library, providing the explicit interface class and a map of options for the library. |
static void |
main(java.lang.String[] args)
Prints JNA library details to the console. |
static void |
register(NativeLibrary lib)
When called from a class static initializer, maps all native methods found within that class to native libraries via the JNA raw calling interface. |
static void |
register(java.lang.String libName)
When called from a class static initializer, maps all native methods found within that class to native libraries via the JNA raw calling interface. |
static void |
setCallbackExceptionHandler(Callback.UncaughtExceptionHandler eh)
Set the default handler invoked when a callback throws an uncaught exception. |
static void |
setLastError(int code)
Set the OS last error code. |
static void |
setPreserveLastError(boolean enable)
Set whether the system last error result is captured after every native invocation. |
static void |
setProtected(boolean enable)
Set whether native memory accesses are protected from invalid accesses. |
static Library |
synchronizedLibrary(Library library)
Returns a synchronized (thread-safe) library backed by the specified library. |
static byte[] |
toByteArray(java.lang.String s)
Obtain a NUL-terminated byte buffer equivalent to the given String. |
static char[] |
toCharArray(java.lang.String s)
Obtain a NUL-terminated wide character buffer equivalent to the given String. |
static java.lang.String |
toString(byte[] buf)
Obtain a Java String from the given native byte array. |
static java.lang.String |
toString(char[] buf)
Obtain a Java String from the given native wchar_t array. |
(package private) static void |
updateLastError(int e)
Update the last error value (called from native code). |
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Field Detail |
---|
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: When protected mode is enabled, you should make use of the jsig
library, if available (see Signal Chaining).
In short, set the environment vaiable LD_PRELOAD
to the
path to libjsig.so
in your JRE lib directory
(usually ${java.home}/lib/${os.arch}/libjsig.so) before launching your
Java application.
public static boolean isProtected()
setProtected(true)
to determine
if this platform supports protecting memory accesses.
public static void setPreserveLastError(boolean enable)
true
.
public static boolean getPreserveLastError()
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 HANDLE
type (actually
void *
) to identify windows.
java.awt.HeadlessException
- if the current VM is running headlesspublic static Pointer getByteBufferPointer(java.nio.ByteBuffer b)
getDirectBufferPointer(java.nio.Buffer)
instead.
Buffer
into a Pointer
.
java.lang.IllegalArgumentException
- if the buffer is not direct.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)
jna.encoding
is set, its value will
override the platform default encoding (if supported).
public static java.lang.String toString(char[] buf)
public static java.lang.Object loadLibrary(java.lang.String name, java.lang.Class interfaceClass)
public static java.lang.Object loadLibrary(java.lang.String name, java.lang.Class interfaceClass, java.util.Map libOptions)
name
- interfaceClass
- libOptions
- Map of library optionsstatic java.lang.Class findCallbackClass(java.lang.Class type)
static java.lang.Class findEnclosingLibraryClass(java.lang.Class cls)
Native.DeleteNativeLibrary
.
public static java.util.Map getLibraryOptions(java.lang.Class type)
Native.DeleteNativeLibrary
public static TypeMapper getTypeMapper(java.lang.Class cls)
TypeMapper
for the given native interface.
See Library.OPTION_TYPE_MAPPER
.
public static int getStructureAlignment(java.lang.Class cls)
Library.OPTION_STRUCTURE_ALIGNMENT
.
static byte[] getBytes(java.lang.String s)
jna.encoding
is set, its value will override
the default platform encoding (if supported).
public static byte[] toByteArray(java.lang.String s)
public static char[] toCharArray(java.lang.String s)
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
.
public static void setLastError(int code)
static void updateLastError(int e)
public static Library synchronizedLibrary(Library library)
Native.DeleteNativeLibrary
. 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.IllegalArgumentException
- if the library can't be found by the
Web Start class loader, which usually means it wasn't included as
a <nativelib>
resource in the JNLP file.public static int getNativeSize(java.lang.Class cls)
struct
pointers unless they implement
Structure.ByValue
.
public static boolean isSupportedNativeType(java.lang.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(java.lang.String libName)
libName
- library name to which functions should be boundpublic static void register(NativeLibrary lib)
lib
- library to which functions should be boundpublic static void main(java.lang.String[] args)
|
JNA API> 3.1.0 | ||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |