com.sun.jna

Class NativeLibrary

java.lang.Object

com.sun.jna.NativeLibrary

public class NativeLibrary
extends java.lang.Object

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

Method Summary

Methods

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()
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 instacne.
Function	getFunction(java.lang.String functionName) Create a new Function that is linked with a native function that follows the standard "C" calling convention.
Function	getFunction(java.lang.String functionName, int callingConvention) Create a new @{link Function} that is linked with a native function that follows a given 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.
java.lang.String	getName() Returns the simple name of this library.
(package private) long	getSymbolAddress(java.lang.String name) Used by the Function class to locate a symbol
(package private) static java.lang.String	matchLibrary(java.lang.String libName, java.util.List searchPath) matchLibrary() is very Linux specific.
(package private) static double	parseVersion(java.lang.String ver)
java.lang.String	toString()

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Method Detail

getInstance

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

addSearchPath

public static final void addSearchPath(java.lang.String libraryName,
                 java.lang.String path)

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

Parameters:

libraryName - The name of the library to use the path for

path - The path to use when trying to load the library

getFunction

public Function getFunction(java.lang.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 - Name of the native function to be linked with

Throws:

java.lang.UnsatisfiedLinkError - if the function is not found

getFunction

public Function getFunction(java.lang.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 - Name of the native function to be linked with

callingConvention - Calling convention used by the native function

Throws:

java.lang.UnsatisfiedLinkError - if the function is not found

getGlobalVariableAddress

public Pointer getGlobalVariableAddress(java.lang.String symbolName)

Look up the given global variable within this library.

Parameters:

symbolName -

Returns:

Pointer representing the global variable address

Throws:

java.lang.UnsatisfiedLinkError - if the symbol is not found

getSymbolAddress

long getSymbolAddress(java.lang.String name)

Used by the Function class to locate a symbol

Throws:

java.lang.UnsatisfiedLinkError - if the symbol can't be found

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

getName

public java.lang.String getName()

Returns the simple name of this library.

getFile

public java.io.File getFile()

Returns the file on disk corresponding to this NativeLibrary instacne.

finalize

protected void finalize()

Close the library when it is no longer referenced.

Overrides:

finalize in class java.lang.Object

dispose

public void dispose()

matchLibrary

static java.lang.String matchLibrary(java.lang.String libName,
                            java.util.List searchPath)

matchLibrary() is very Linux specific. It is here to deal with the case where /usr/lib/libc.so does not exist, or it is not a valid symlink to a versioned file (e.g. /lib/libc.so.6).

parseVersion

static double parseVersion(java.lang.String ver)