public class NativeLibrary
extends java.lang.Object
getProcess()
).
Library Search Paths A search for a given library will scan the following locations:
jna.library.path
User-customizable path
jna.platform.library.path
Platform-specific paths
~/Library/Frameworks
,
/Library/Frameworks
, and
/System/Library/Frameworks
will be searched for a framework
with a name corresponding to that requested. Absolute paths to frameworks
are also accepted, either ending at the framework name (sans ".framework")
or the full path to the framework shared library
(e.g. CoreServices.framework/CoreServices).
${os-prefix}/LIBRARY_FILENAME
, where ${os-prefix}
is the OS/Arch prefix returned by Platform.getNativeLibraryResourcePrefix()
. If bundled in a jar file, the
resource will be extracted to jna.tmpdir
for loading, and
later removed (but only if jna.nounpack
is false or not set).
jna.debug_load=true
to make
JNA print the steps of its library search to the console.Modifier and Type | Field and Description |
---|---|
(package private) int |
callFlags |
(package private) java.util.Map<java.lang.String,?> |
options |
Modifier and Type | Method and Description |
---|---|
static void |
addSearchPath(java.lang.String libraryName,
java.lang.String path)
Add a path to search for the specified library, ahead of any system
paths.
|
void |
dispose()
Close the native library we're mapped to.
|
(package private) static void |
disposeAll()
Close all open native libraries.
|
protected void |
finalize()
Close the library when it is no longer referenced.
|
java.io.File |
getFile()
Returns the file on disk corresponding to this NativeLibrary instance.
|
Function |
getFunction(java.lang.String functionName)
Create a new
Function that is linked with a native
function that follows the NativeLibrary's calling convention. |
Function |
getFunction(java.lang.String functionName,
int callFlags)
Create a new
Function that is linked with a native
function that follows a given calling flags. |
Function |
getFunction(java.lang.String functionName,
int callFlags,
java.lang.String encoding)
Create a new
Function that is linked with a native
function that follows a given calling flags. |
(package private) Function |
getFunction(java.lang.String name,
java.lang.reflect.Method method)
Create a new
Function that is linked with a native
function that follows the NativeLibrary's calling convention. |
Pointer |
getGlobalVariableAddress(java.lang.String symbolName)
Look up the given global variable within this library.
|
static NativeLibrary |
getInstance(java.lang.String libraryName)
Returns an instance of NativeLibrary for the specified name.
|
static NativeLibrary |
getInstance(java.lang.String libraryName,
java.lang.ClassLoader classLoader)
Returns an instance of NativeLibrary for the specified name.
|
static NativeLibrary |
getInstance(java.lang.String libraryName,
java.util.Map<java.lang.String,?> libraryOptions)
Returns an instance of NativeLibrary for the specified name.
|
java.lang.String |
getName()
Returns the simple name of this library.
|
java.util.Map<java.lang.String,?> |
getOptions() |
static NativeLibrary |
getProcess()
Returns an instance of NativeLibrary which refers to the current
process.
|
static NativeLibrary |
getProcess(java.util.Map<java.lang.String,?> options)
Returns an instance of NativeLibrary which refers to the current
process.
|
(package private) long |
getSymbolAddress(java.lang.String name)
Used by the Function class to locate a symbol
|
(package private) static java.lang.String |
mapSharedLibraryName(java.lang.String libName)
Similar to
System.mapLibraryName(java.lang.String) , except that it maps to
standard shared library formats rather than specifically JNI formats. |
(package private) static java.lang.String[] |
matchFramework(java.lang.String libraryName)
Look for a matching framework (OSX)
|
(package private) static java.lang.String |
matchLibrary(java.lang.String libName,
java.util.Collection<java.lang.String> searchPath)
matchLibrary() is very Linux specific.
|
(package private) static double |
parseVersion(java.lang.String ver) |
java.lang.String |
toString() |
static java.lang.String[] matchFramework(java.lang.String libraryName)
public static final NativeLibrary getInstance(java.lang.String libraryName)
More than one name may map to the same NativeLibrary instance; only a single instance will be provided for any given unique file path.
libraryName
- The library name to load.
This can be short form (e.g. "c"),
an explicit version (e.g. "libc.so.6"), or
the full path to the library (e.g. "/lib/libc.so.6").public static final NativeLibrary getInstance(java.lang.String libraryName, java.lang.ClassLoader classLoader)
More than one name may map to the same NativeLibrary instance; only a single instance will be provided for any given unique file path.
libraryName
- The library name to load.
This can be short form (e.g. "c"),
an explicit version (e.g. "libc.so.6"), or
the full path to the library (e.g. "/lib/libc.so.6").classLoader
- The class loader to use to load the native library.
This only affects library loading when the native library is
included somewhere in the classpath, either bundled in a jar file
or as a plain file within the classpath.public static final NativeLibrary getInstance(java.lang.String libraryName, java.util.Map<java.lang.String,?> libraryOptions)
More than one name may map to the same NativeLibrary instance; only a single instance will be provided for any given unique file path.
libraryName
- The library name to load.
This can be short form (e.g. "c"),
an explicit version (e.g. "libc.so.6" or
"QuickTime.framework/Versions/Current/QuickTime"), or
the full (absolute) path to the library (e.g. "/lib/libc.so.6").libraryOptions
- Native library options for the given library (see Library
).public static final NativeLibrary getProcess()
public static final NativeLibrary getProcess(java.util.Map<java.lang.String,?> options)
public static final void addSearchPath(java.lang.String libraryName, java.lang.String path)
jna.library.path
, but
only extends the search path for a single library.libraryName
- The name of the library to use the path forpath
- The path to use when trying to load the librarypublic Function getFunction(java.lang.String functionName)
Function
that is linked with a native
function that follows the NativeLibrary's calling convention.
The allocated instance represents a pointer to the named native function from the library.
functionName
- Name of the native function to be linked withjava.lang.UnsatisfiedLinkError
- if the function is not foundFunction getFunction(java.lang.String name, java.lang.reflect.Method method)
Function
that is linked with a native
function that follows the NativeLibrary's calling convention.
The allocated instance represents a pointer to the named native function from the library.
name
- Name of the native function to be linked with. Uses a
function mapper option if one was provided to
transform the name.method
- Method to which the native function is to be mappedjava.lang.UnsatisfiedLinkError
- if the function is not foundpublic Function getFunction(java.lang.String functionName, int callFlags)
Function
that is linked with a native
function that follows a given calling flags.functionName
- Name of the native function to be linked withcallFlags
- Flags affecting the function invocationjava.lang.UnsatisfiedLinkError
- if the function is not foundpublic Function getFunction(java.lang.String functionName, int callFlags, java.lang.String encoding)
Function
that is linked with a native
function that follows a given calling flags.functionName
- Name of the native function to be linked withcallFlags
- Flags affecting the function invocationencoding
- Encoding to use to convert between Java and native
strings.java.lang.UnsatisfiedLinkError
- if the function is not foundpublic java.util.Map<java.lang.String,?> getOptions()
public Pointer getGlobalVariableAddress(java.lang.String symbolName)
symbolName
- java.lang.UnsatisfiedLinkError
- if the symbol is not foundlong getSymbolAddress(java.lang.String name)
java.lang.UnsatisfiedLinkError
- if the symbol can't be foundpublic java.lang.String toString()
toString
in class java.lang.Object
public java.lang.String getName()
public java.io.File getFile()
protected void finalize()
finalize
in class java.lang.Object
static void disposeAll()
public void dispose()
static java.lang.String mapSharedLibraryName(java.lang.String libName)
System.mapLibraryName(java.lang.String)
, except that it maps to
standard shared library formats rather than specifically JNI formats.libName
- base (undecorated) name of librarystatic java.lang.String matchLibrary(java.lang.String libName, java.util.Collection<java.lang.String> searchPath)
static double parseVersion(java.lang.String ver)