JNA API 3.5.2

com.sun.jna
Class Native

java.lang.Object
  extended by com.sun.jna.Native

public final class Native
extends Object

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 Structures, which would require every Structure which requires custom mapping or alignment to define a constructor and pass parameters to the superclass. To avoid lots of boilerplate, the base Structure constructor figures out these properties based on its enclosing interface.

Library Loading

When JNA classes are loaded, the native shared library (jnidispatch) is loaded as well. An attempt is made to load it from the any paths defined in jna.boot.library.path (if defined), then the system library path using System.loadLibrary(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).

Native Library Loading

Native libraries loaded via loadLibrary(Class) may be found in several locations.

Author:
Todd Fast, todd.fast@sun.com, twall@users.sf.net
See Also:
Library

Nested Class Summary
static interface Native.ffi_callback
           
 
Field Summary
(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.
(package private) static String JNA_TMPLIB_PREFIX
           
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)
          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.
(package private) static boolean deleteLibrary(File lib)
          Remove any automatically unpacked native library.
static void detach(boolean detach)
          Indicate the desired attachment state for the current thread.
(package private) static File extractFromResourcePath(String name)
          Attempt to extract a native library from the current resource path.
(package private) static File extractFromResourcePath(String name, String resourcePrefix, ClassLoader loader)
          Attempt to extract a native library from the current resource path.
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)
          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)
           
static String getNativeLibraryResourcePrefix()
          Generate a canonical String prefix based on the current OS type/arch/name.
static String getNativeLibraryResourcePrefix(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)
          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.
(package private) static boolean isUnpacked(File file)
          Identify temporary files unpacked from classpath jar files.
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)
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

POINTER_SIZE

public static final int POINTER_SIZE
The size of a native pointer (void*) on the current platform, in bytes.


LONG_SIZE

public static final int LONG_SIZE
Size of a native long type, in bytes.


WCHAR_SIZE

public static final int WCHAR_SIZE
Size of a native wchar_t type, in bytes.


SIZE_T_SIZE

public static final int SIZE_T_SIZE
Size of a native size_t type, in bytes.


JNA_TMPLIB_PREFIX

static final String JNA_TMPLIB_PREFIX
See Also:
Constant Field Values

CB_HAS_INITIALIZER

static final int CB_HAS_INITIALIZER
Indicates whether the callback has an initializer.

See Also:
Constant Field Values

CB_OPTION_DIRECT

static final int CB_OPTION_DIRECT
Use direct mapping for callback.

See Also:
Constant Field Values

CB_OPTION_IN_DLL

static final int CB_OPTION_IN_DLL
Return a DLL-resident fucntion pointer.

See Also:
Constant Field Values
Method Detail

deleteLibrary

static boolean deleteLibrary(File lib)
Remove any automatically unpacked native library. This will fail on windows, which disallows removal of any file that is still in use, so an alternative is required in that case. Mark the file that could not be deleted, and attempt to delete any temporaries on next startup. Do NOT force the class loader to unload the native library, since that introduces issues with cleaning up any extant JNA bits (e.g. Memory) which may still need use of the library before shutdown.


setProtected

public static void setProtected(boolean enable)
Set whether native memory accesses are protected from invalid accesses. This should only be set true when testing or debugging, and should not be considered reliable or robust for applications where JNA native calls are occurring on multiple threads. Protected mode will be automatically set if the system property 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.


isProtected

public static boolean isProtected()
Returns whether protection is enabled. Check the result of this method after calling setProtected(true) to determine if this platform supports protecting memory accesses.


setPreserveLastError

public 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.

Set whether the system last error result is captured after every native invocation. Defaults to true (false for direct-mapped calls).


getPreserveLastError

public static boolean getPreserveLastError()
Deprecated. The preferred method of obtaining the last error result is to declare your mapped method to throw LastErrorException instead.

Indicates whether the system last error result is preserved after every invocation.


getWindowID

public static long getWindowID(Window w)
                        throws HeadlessException
Utility method to get the native window ID for a Java Window as a long value. This method is primarily for X11-based systems, which use an opaque XID (usually long int) to identify windows.

Throws:
HeadlessException - if the current VM is running headless

getComponentID

public static long getComponentID(Component c)
                           throws HeadlessException
Utility method to get the native window ID for a heavyweight Java Component as a long value. This method is primarily for X11-based systems, which use an opaque XID (usually long int) to identify windows.

Throws:
HeadlessException - if the current VM is running headless

getWindowPointer

public static Pointer getWindowPointer(Window w)
                                throws HeadlessException
Utility method to get the native window pointer for a Java Window as a Pointer value. This method is primarily for w32, which uses the HANDLE type (actually void *) to identify windows.

Throws:
HeadlessException - if the current VM is running headless

getComponentPointer

public static Pointer getComponentPointer(Component c)
                                   throws HeadlessException
Utility method to get the native window pointer for a heavyweight Java Component as a Pointer value. This method is primarily for w32, which uses the HWND type (actually void *) to identify windows.

Throws:
HeadlessException - if the current VM is running headless

getWindowHandle0

static long getWindowHandle0(Component c)

getDirectBufferPointer

public static Pointer getDirectBufferPointer(Buffer b)
Convert a direct Buffer into a Pointer.

Throws:
IllegalArgumentException - if the buffer is not direct.

toString

public static String toString(byte[] buf)
Obtain a Java String from the given native byte array. If there is no NUL terminator, the String will comprise the entire array. If the system property jna.encoding is set, its value will override the platform default encoding (if supported).


toString

public static String toString(byte[] buf,
                              String encoding)
Obtain a Java String from the given native byte array, using the given encoding. If there is no NUL terminator, the String will comprise the entire array. If the encoding parameter is null, the platform default encoding will be used.


toString

public static String toString(char[] buf)
Obtain a Java String from the given native wchar_t array. If there is no NUL terminator, the String will comprise the entire array.


loadLibrary

public static Object loadLibrary(Class interfaceClass)
Map a library interface to the current process, providing the explicit interface class.

Parameters:
interfaceClass -
Returns:
an instance of the requested interface, mapped to the current process.
Throws:
UnsatisfiedLinkError - if the library cannot be found or dependent libraries are missing.

loadLibrary

public static Object loadLibrary(Class interfaceClass,
                                 Map options)
Map a library interface to the current process, providing the explicit interface class.

Parameters:
interfaceClass -
options - Map of library options
Returns:
an instance of the requested interface, mapped to the current process.
Throws:
UnsatisfiedLinkError - if the library cannot be found or dependent libraries are missing.

loadLibrary

public static Object loadLibrary(String name,
                                 Class interfaceClass)
Map a library interface to the given shared library, providing the explicit interface class. If name is null, attempts to map onto the current process.

Parameters:
name -
interfaceClass -
Returns:
an instance of the requested interface, mapped to the indicated native library.
Throws:
UnsatisfiedLinkError - if the library cannot be found or dependent libraries are missing.

loadLibrary

public 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. If no library options are detected the map is interpreted as a map of Java method names to native function names.

If name is null, attempts to map onto the current process. Native libraries loaded via this method may be found in several locations.

Parameters:
name -
interfaceClass -
options - Map of library options
Returns:
an instance of the requested interface, mapped to the indicated native library.
Throws:
UnsatisfiedLinkError - if the library cannot be found or dependent libraries are missing.

findEnclosingLibraryClass

static Class findEnclosingLibraryClass(Class cls)
Find the library interface corresponding to the given class. Checks all ancestor classes and interfaces for a declaring class which implements Library.


getLibraryOptions

public static Map getLibraryOptions(Class type)
Return the preferred native library configuration options for the given class.

See Also:
Library

getTypeMapper

public static TypeMapper getTypeMapper(Class cls)
Return the preferred TypeMapper for the given native interface. See Library.OPTION_TYPE_MAPPER.


getStructureAlignment

public static int getStructureAlignment(Class cls)
Return the preferred structure alignment for the given native interface. See Library.OPTION_STRUCTURE_ALIGNMENT.


getBytes

static byte[] getBytes(String s)
Return a byte array corresponding to the given String. If the system property jna.encoding is set, its value will override the default platform encoding (if supported).


getBytes

static byte[] getBytes(String s,
                       String encoding)
                throws UnsupportedEncodingException
Return a byte array corresponding to the given String, using the given encoding.

Throws:
UnsupportedEncodingException

toByteArray

public 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.


toByteArray

public static byte[] toByteArray(String s,
                                 String encoding)
                          throws UnsupportedEncodingException
Obtain a NUL-terminated byte buffer equivalent to the given String, using the given encoding.

Throws:
UnsupportedEncodingException

toCharArray

public static char[] toCharArray(String s)
Obtain a NUL-terminated wide character buffer equivalent to the given String.


getNativeLibraryResourcePrefix

public static String getNativeLibraryResourcePrefix()
Generate a canonical String prefix based on the current OS type/arch/name.


getNativeLibraryResourcePrefix

public static String getNativeLibraryResourcePrefix(int osType,
                                                    String arch,
                                                    String name)
Generate a canonical String prefix based on the given OS type/arch/name.

Parameters:
osType - from Platform
arch - from os.arch System property
name - from os.name System property

isUnpacked

static boolean isUnpacked(File file)
Identify temporary files unpacked from classpath jar files.


extractFromResourcePath

static File extractFromResourcePath(String name)
                             throws IOException
Attempt to extract a native library from the current resource path. Expects native libraries to be stored under the path returned by getNativeLibraryResourcePrefix(), and reachable by the current thread context class loader.

Parameters:
name - Base name of native library to extract
Returns:
File indicating extracted resource on disk
Throws:
IOException - if resource not found

extractFromResourcePath

static File extractFromResourcePath(String name,
                                    String resourcePrefix,
                                    ClassLoader loader)
                             throws IOException
Attempt to extract a native library from the current resource path. Expects native libraries to be stored under the path returned by getNativeLibraryResourcePrefix(int, String, String).

Parameters:
name - Base name of native library to extract
loader - Class loader to use to load resources
resourcePrefix - prefix to use when looking for the resource
Returns:
File indicating extracted resource on disk
Throws:
IOException - if resource not found

getLastError

public static int getLastError()
Retrieve the last error set by the OS. This corresponds to 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.


setLastError

public static void setLastError(int code)
Set the OS last error code. Whether the setting is per-thread or global depends on the underlying OS.


updateLastError

static void updateLastError(int e)
Update the last error value (called from native code).


synchronizedLibrary

public static Library synchronizedLibrary(Library library)
Returns a synchronized (thread-safe) library backed by the specified library. This wrapping will prevent simultaneous invocations of any functions mapped to a given NativeLibrary. Note that the native library may still be sensitive to being called from different threads.

Parameters:
library - the library to be "wrapped" in a synchronized library.
Returns:
a synchronized view of the specified library.

getWebStartLibraryPath

public static String getWebStartLibraryPath(String libName)
If running web start, determine the location of a given native library. This value may be used to properly set 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.

Returns:
null if unable to query the web start loader.
Throws:
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.

markTemporaryFile

static void markTemporaryFile(File file)
Perform cleanup of automatically unpacked native shared library.


getTempDir

static File getTempDir()
Obtain a directory suitable for writing JNA-specific temporary files. Override with jna.tmpdir


removeTemporaryFiles

static void removeTemporaryFiles()
Remove all marked temporary files in the given directory.


getNativeSize

public static int getNativeSize(Class type,
                                Object value)
Returns the native size of the given class, in bytes. For use with arrays.


getNativeSize

public static int getNativeSize(Class cls)
Returns the native size for a given Java class. Structures are assumed to be struct pointers unless they implement Structure.ByValue.


isSupportedNativeType

public static boolean isSupportedNativeType(Class cls)
Indicate whether the given class is supported as a native argument type.


setCallbackExceptionHandler

public static void setCallbackExceptionHandler(Callback.UncaughtExceptionHandler eh)
Set the default handler invoked when a callback throws an uncaught exception. If the given handler is null, the default handler will be reinstated.


getCallbackExceptionHandler

public static Callback.UncaughtExceptionHandler getCallbackExceptionHandler()
Returns the current handler for callback uncaught exceptions.


register

public 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.

Parameters:
libName - library name to which functions should be bound

register

public 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.

Parameters:
lib - native library to which functions should be bound

getNativeClass

static Class getNativeClass(Class cls)

getCallingClass

static Class getCallingClass()

setCallbackThreadInitializer

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


unregister

public static void unregister()
Remove all native mappings for the calling class. Should only be called if the class is no longer referenced and about to be garbage collected.


unregister

public static void unregister(Class cls)
Remove all native mappings for the given class. Should only be called if the class is no longer referenced and about to be garbage collected.


replace

static String replace(String s1,
                      String s2,
                      String str)

register

public 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.

Parameters:
lib - library to which functions should be bound

ffi_prep_cif

public static long ffi_prep_cif(int abi,
                                int nargs,
                                long ffi_return_type,
                                long ffi_types)
Create a new cif structure.


ffi_call

public static void ffi_call(long cif,
                            long fptr,
                            long resp,
                            long args)
Make an FFI function call.


ffi_prep_closure

public static long ffi_prep_closure(long cif,
                                    Native.ffi_callback cb)

ffi_free_closure

public static void ffi_free_closure(long closure)

initialize_ffi_type

static int initialize_ffi_type(long type_info)
Returns the size (calculated by libffi) of the given type.


main

public static void main(String[] args)
Prints JNA library details to the console.


freeNativeCallback

static void freeNativeCallback(long ptr)
Free the given callback trampoline.


createNativeCallback

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.


invokeInt

static int invokeInt(long fp,
                     int callFlags,
                     Object[] args)
Call the native function being represented by this object

Parameters:
fp - function pointer
callFlags - calling convention to be used
args - Arguments to pass to the native function
Returns:
The value returned by the target native function

invokeLong

static long invokeLong(long fp,
                       int callFlags,
                       Object[] args)
Call the native function being represented by this object

Parameters:
fp - function pointer
callFlags - calling convention to be used
args - Arguments to pass to the native function
Returns:
The value returned by the target native function

invokeVoid

static void invokeVoid(long fp,
                       int callFlags,
                       Object[] args)
Call the native function being represented by this object

Parameters:
fp - function pointer
callFlags - calling convention to be used
args - Arguments to pass to the native function

invokeFloat

static float invokeFloat(long fp,
                         int callFlags,
                         Object[] args)
Call the native function being represented by this object

Parameters:
fp - function pointer
callFlags - calling convention to be used
args - Arguments to pass to the native function
Returns:
The value returned by the target native function

invokeDouble

static double invokeDouble(long fp,
                           int callFlags,
                           Object[] args)
Call the native function being represented by this object

Parameters:
fp - function pointer
callFlags - calling convention to be used
args - Arguments to pass to the native function
Returns:
The value returned by the target native function

invokePointer

static long invokePointer(long fp,
                          int callFlags,
                          Object[] args)
Call the native function being represented by this object

Parameters:
fp - function pointer
callFlags - calling convention to be used
args - Arguments to pass to the native function
Returns:
The native pointer returned by the target native function

invokeStructure

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.

Parameters:
fp - function pointer
callFlags - calling convention to be used
args - Arguments to pass to the native function
Returns:
the passed-in Structure

invokeObject

static Object invokeObject(long fp,
                           int callFlags,
                           Object[] args)
Call the native function being represented by this object, returning a Java Object.

Parameters:
fp - function pointer
callFlags - calling convention to be used
args - Arguments to pass to the native function
Returns:
The returned Java Object

open

static long open(String name)
Open the requested native library with default options.


open

static long open(String name,
                 int flags)
Open the requested native library with the specified platform-specific otions.


close

static void close(long handle)
Close the given native library.


findSymbol

static long findSymbol(long handle,
                       String name)

indexOf

static long indexOf(long addr,
                    byte value)

read

static void read(long addr,
                 byte[] buf,
                 int index,
                 int length)

read

static void read(long addr,
                 short[] buf,
                 int index,
                 int length)

read

static void read(long addr,
                 char[] buf,
                 int index,
                 int length)

read

static void read(long addr,
                 int[] buf,
                 int index,
                 int length)

read

static void read(long addr,
                 long[] buf,
                 int index,
                 int length)

read

static void read(long addr,
                 float[] buf,
                 int index,
                 int length)

read

static void read(long addr,
                 double[] buf,
                 int index,
                 int length)

write

static void write(long addr,
                  byte[] buf,
                  int index,
                  int length)

write

static void write(long addr,
                  short[] buf,
                  int index,
                  int length)

write

static void write(long addr,
                  char[] buf,
                  int index,
                  int length)

write

static void write(long addr,
                  int[] buf,
                  int index,
                  int length)

write

static void write(long addr,
                  long[] buf,
                  int index,
                  int length)

write

static void write(long addr,
                  float[] buf,
                  int index,
                  int length)

write

static void write(long addr,
                  double[] buf,
                  int index,
                  int length)

getByte

static byte getByte(long addr)

getChar

static char getChar(long addr)

getShort

static short getShort(long addr)

getInt

static int getInt(long addr)

getLong

static long getLong(long addr)

getFloat

static float getFloat(long addr)

getDouble

static double getDouble(long addr)

getPointer

static Pointer getPointer(long addr)

getString

static String getString(long addr,
                        boolean wide)

setMemory

static void setMemory(long addr,
                      long length,
                      byte value)

setByte

static void setByte(long addr,
                    byte value)

setShort

static void setShort(long addr,
                     short value)

setChar

static void setChar(long addr,
                    char value)

setInt

static void setInt(long addr,
                   int value)

setLong

static void setLong(long addr,
                    long value)

setFloat

static void setFloat(long addr,
                     float value)

setDouble

static void setDouble(long addr,
                      double value)

setPointer

static void setPointer(long addr,
                       long value)

setString

static void setString(long addr,
                      String value,
                      boolean wide)

malloc

public static long malloc(long size)
Call the real native malloc

Parameters:
size - size of the memory to be allocated
Returns:
native address of the allocated memory block; zero if the allocation failed.

free

public static void free(long ptr)
Call the real native free

Parameters:
ptr - native address to be freed; a value of zero has no effect, passing an already-freed pointer will cause pain.

getDirectByteBuffer

public static ByteBuffer getDirectByteBuffer(long addr,
                                             long length)
Get a direct ByteBuffer mapped to the memory pointed to by the pointer. This method calls through to the JNA NewDirectByteBuffer method.

Parameters:
addr - base address of the JNA-originated memory
length - Length of ByteBuffer
Returns:
a direct ByteBuffer that accesses the memory being pointed to,

detach

public static void detach(boolean detach)
Indicate the desired attachment state for the current thread. This method should only be called from a callback context, and then only just prior to returning to native code. Executing Java or native code after the invocation of this method may interfere with the intended detach state.

Note: errno/SetLastError is used to signal the desired state; this is a hack to make use of built-in thread-local storage to avoid having to re-implement it on certain platforms.

Warning: avoid calling detach(true) on threads spawned by the JVM; the resulting behavior is not defined.


JNA API 3.5.2

Copyright © 2007-2013 Timothy Wall. All Rights Reserved.