com.sun.jna

Class NativeLibrary

public class NativeLibrary extends Object

Provides management of native library resources. One instance of this class corresponds to a single loaded native library. May also be used to map to the current process (see getProcess).

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
intcallFlags
Mapoptions
Method Summary
static voidaddSearchPath(String libraryName, String path)
Add a path to search for the specified library, ahead of any system paths.
voiddispose()
protected voidfinalize()
Close the library when it is no longer referenced.
FilegetFile()
Returns the file on disk corresponding to this NativeLibrary instance.
FunctiongetFunction(String functionName)
Create a new Function that is linked with a native function that follows the NativeLibrary's calling convention.
FunctiongetFunction(String name, Method method)
Create a new Function that is linked with a native function that follows the NativeLibrary's calling convention.
FunctiongetFunction(String functionName, int callFlags)
Create a new @{link Function} that is linked with a native function that follows a given calling flags.
PointergetGlobalVariableAddress(String symbolName)
Look up the given global variable within this library.
static NativeLibrarygetInstance(String libraryName)
Returns an instance of NativeLibrary for the specified name.
static NativeLibrarygetInstance(String libraryName, Map options)
Returns an instance of NativeLibrary for the specified name.
StringgetName()
Returns the simple name of this library.
MapgetOptions()
Returns this native library instance's options.
static NativeLibrarygetProcess()
Returns an instance of NativeLibrary which refers to the current process.
static NativeLibrarygetProcess(Map options)
Returns an instance of NativeLibrary which refers to the current process.
longgetSymbolAddress(String name)
Used by the Function class to locate a symbol
static StringmatchLibrary(String libName, List searchPath)
matchLibrary() is very Linux specific.
static doubleparseVersion(String ver)
StringtoString()

Field Detail

callFlags

final int callFlags

options

final Map options

Method Detail

addSearchPath

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 The name of the library to use the path for path The path to use when trying to load the library

dispose

public void dispose()

finalize

protected void finalize()
Close the library when it is no longer referenced.

getFile

public File getFile()
Returns the file on disk corresponding to this NativeLibrary instance. If this NativeLibrary represents the current process, this function will return null.

getFunction

public Function getFunction(String functionName)
Create a new 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.

Parameters: functionName Name of the native function to be linked with

Throws: UnsatisfiedLinkError if the function is not found

getFunction

Function getFunction(String name, Method method)
Create a new 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.

Parameters: name Name of the native function to be linked with method Method to which the native function is to be mapped

Throws: UnsatisfiedLinkError if the function is not found

getFunction

public Function getFunction(String functionName, int callFlags)
Create a new @{link Function} that is linked with a native function that follows a given calling flags.

Parameters: functionName Name of the native function to be linked with callFlags Flags affecting the function invocation

Throws: UnsatisfiedLinkError if the function is not found

getGlobalVariableAddress

public Pointer getGlobalVariableAddress(String symbolName)
Look up the given global variable within this library.

Parameters: symbolName

Returns: Pointer representing the global variable address

Throws: UnsatisfiedLinkError if the symbol is not found

getInstance

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

getInstance

public static final NativeLibrary getInstance(String libraryName, Map options)
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"). options native library options for the given library (see Library).

getName

public String getName()
Returns the simple name of this library.

getOptions

public Map getOptions()
Returns this native library instance's options.

getProcess

public static final NativeLibrary getProcess()
Returns an instance of NativeLibrary which refers to the current process. This is useful for accessing functions which were already mapped by some other mechanism, without having to reference or even know the exact name of the native library.

getProcess

public static final NativeLibrary getProcess(Map options)
Returns an instance of NativeLibrary which refers to the current process. This is useful for accessing functions which were already mapped by some other mechanism, without having to reference or even know the exact name of the native library.

getSymbolAddress

long getSymbolAddress(String name)
Used by the Function class to locate a symbol

Throws: UnsatisfiedLinkError if the symbol can't be found

matchLibrary

static String matchLibrary(String libName, 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(String ver)

toString

public String toString()
Copyright © 2007-2009 Timothy Wall. All Rights Reserved.