Top Description Fields Constructors Methods
com.sun.jna

public Class NativeLibrary

extends Object
Class Inheritance
Imports
java.io.File, .FilenameFilter, java.lang.ref.WeakReference, java.util.ArrayList, .Arrays, .Collections, .HashMap, .Iterator, .LinkedList, .List, .Map, java.util.regex.Pattern
Provides management of native library resources. One instance of this class corresponds to a single loaded native library.

Library Search Paths A search for a given library will scan the following locations:

  1. jna.library.path User-customizable path
  2. jna.platform.library.path Platform-specific paths
Author
Wayne Meissner, split library loading from Function.java

Field Summary

Modifier and TypeField and Description
private final Map<K, V>
functions

private long
handle

private static final Map<K, V>
libraries

private String
libraryName

private String
libraryPath

private static final List<E>
librarySearchPath

private static final Map<K, V>
searchPaths

Constructor Summary

AccessConstructor and Description
private
NativeLibrary(String libraryName, String libraryPath, long handle)

Method Summary

Modifier and TypeMethod and Description
public static final void
addSearchPath(String
The name of the library to use the path for
libraryName, String
The path to use when trying to load the library
path)

Add a path to search for the specified library, ahead of any system paths

private static native void
close(long handle)

protected void
finalize()

Overrides java.lang.Object.finalize.

Close the library when it is no longer referenced.
private static String
findLibraryPath(String libName, List<E> searchPath)

Use standard library search paths to find the library.

private static native long
findSymbol(long handle, String name)

public File
getFile()

Returns the file on disk corresponding to this NativeLibrary instacne.

public Function
getFunction(String
Name of the native function to be linked with
functionName)

Create a new Function that is linked with a native function that follows the standard "C" calling convention.

public Function
getFunction(String
Name of the native function to be linked with
functionName, int
Calling convention used by the native function
callingConvention)

Create a new @{link Function} that is linked with a native function that follows a given calling convention.

public Pointer

Returns:

Pointer representing the global variable address
getGlobalVariableAddress(String symbolName)

Look up the given global variable within this library.

public static final NativeLibrary
getInstance(String
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").
libraryName)

Returns an instance of NativeLibrary for the specified name.

private String
getLibraryName(String libraryName)

public String
getName()

Returns the simple name of this library.

pack-priv long
getSymbolAddress(String name)

Used by the Function class to locate a symbol

private static List<E>
initPaths(String key)

private static NativeLibrary
loadLibrary(String libraryName)

private static String
mapLibraryName(String libName)

private static String
matchLibrary(final String libName, List<E> searchPath)

matchLibrary is very Linux specific.

private static native long
open(String name)

public String
toString()

Overrides java.lang.Object.toString.

Returns a string representation of the object.
Inherited from java.lang.Object:
cloneequalsgetClasshashCodenotifynotifyAllwaitwaitwait

Field Detail

functionsback to summary
private final Map<K, V> functions
handleback to summary
private long handle
librariesback to summary
private static final Map<K, V> libraries
libraryNameback to summary
private String libraryName
libraryPathback to summary
private String libraryPath
librarySearchPathback to summary
private static final List<E> librarySearchPath
searchPathsback to summary
private static final Map<K, V> searchPaths

Constructor Detail

NativeLibraryback to summary
private NativeLibrary(String libraryName, String libraryPath, long handle)

Method Detail

addSearchPathback to summary
public static final void addSearchPath(String libraryName, String path)

Add a path to search for the specified library, ahead of any system paths

Parameters
libraryName:String

The name of the library to use the path for

path:String

The path to use when trying to load the library

closeback to summary
private static native void close(long handle)
finalizeback to summary
protected void finalize()

Overrides java.lang.Object.finalize.

Close the library when it is no longer referenced.

findLibraryPathback to summary
private static String findLibraryPath(String libName, List<E> searchPath)

Use standard library search paths to find the library.

findSymbolback to summary
private static native long findSymbol(long handle, String name)
getFileback to summary
public File getFile()

Returns the file on disk corresponding to this NativeLibrary instacne.

getFunctionback to summary
public Function getFunction(String functionName)

Create a new Function that is linked with a native function that follows the standard "C" calling convention.

The allocated instance represents a pointer to the named native function from the library, called with the standard "C" calling convention.

Parameters
functionName:String

Name of the native function to be linked with

Exceptions
UnsatisfiedLinkError:
if the function is not found
getFunctionback to summary
public Function getFunction(String functionName, int callingConvention)

Create a new @{link Function} that is linked with a native function that follows a given calling convention.

The allocated instance represents a pointer to the named native function from the library, called with the named calling convention.

Parameters
functionName:String

Name of the native function to be linked with

callingConvention:int

Calling convention used by the native function

Exceptions
UnsatisfiedLinkError:
if the function is not found
getGlobalVariableAddressback to summary
public Pointer getGlobalVariableAddress(String symbolName)

Look up the given global variable within this library.

Returns:Pointer

Pointer representing the global variable address

Exceptions
UnsatisfiedLinkError:
if the symbol is not found
getInstanceback to summary
public static final NativeLibrary getInstance(String libraryName)

Returns an instance of NativeLibrary for the specified name. The library is loaded if not already loaded. If already loaded, the existing instance is returned.

More than one name may map to the same NativeLibrary instance; only a single instance will be provided for any given unique file path.

Parameters
libraryName:String

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").

getLibraryNameback to summary
private String getLibraryName(String libraryName)
getNameback to summary
public String getName()

Returns the simple name of this library.

getSymbolAddressback to summary
pack-priv long getSymbolAddress(String name)

Used by the Function class to locate a symbol

Exceptions
UnsatisfiedLinkError:
if the symbol can't be found
initPathsback to summary
private static List<E> initPaths(String key)
loadLibraryback to summary
private static NativeLibrary loadLibrary(String libraryName)
mapLibraryNameback to summary
private static String mapLibraryName(String libName)
matchLibraryback to summary
private static String matchLibrary(final String libName, List<E> searchPath)

matchLibrary is very Linux specific. It is here to deal with the case where there is no /usr/lib/libc.so, or it is not a valid symlink to /lib/libc.so.6.

openback to summary
private static native long open(String name)
toStringback to summary
public String toString()

Overrides java.lang.Object.toString.

Doc from java.lang.Object.toString.

Returns a string representation of the object.

Returns:String

a string representation of the object.