JNA API 3.5.2

com.sun.jna
Class NativeLibrary

java.lang.Object
  extended by com.sun.jna.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
  3. On OSX, ~/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).
  4. Context class loader classpath. Deployed native libraries may be installed on the classpath under ${os-prefix}/LIBRARY_FILENAME, where ${os-prefix} is the OS/Arch prefix returned by Native.getNativeLibraryResourcePrefix(). If bundled in a jar file, the resource will be extracted to jna.tmpdir for loading, and later removed.

Author:
Wayne Meissner, split library loading from Function.java, twall

Field Summary
(package private)  int callFlags
           
(package private)  Map options
           
 
Method Summary
static void addSearchPath(String libraryName, 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.
 File getFile()
          Returns the file on disk corresponding to this NativeLibrary instance.
 Function getFunction(String functionName)
          Create a new Function that is linked with a native function that follows the NativeLibrary's calling convention.
 Function getFunction(String functionName, int callFlags)
          Create a new @{link Function} that is linked with a native function that follows a given calling flags.
(package private)  Function getFunction(String name, Method method)
          Create a new Function that is linked with a native function that follows the NativeLibrary's calling convention.
 Pointer getGlobalVariableAddress(String symbolName)
          Look up the given global variable within this library.
static NativeLibrary getInstance(String libraryName)
          Returns an instance of NativeLibrary for the specified name.
static NativeLibrary getInstance(String libraryName, Map options)
          Returns an instance of NativeLibrary for the specified name.
 String getName()
          Returns the simple name of this library.
 Map getOptions()
          Returns this native library instance's options.
static NativeLibrary getProcess()
          Returns an instance of NativeLibrary which refers to the current process.
static NativeLibrary getProcess(Map options)
          Returns an instance of NativeLibrary which refers to the current process.
(package private)  long getSymbolAddress(String name)
          Used by the Function class to locate a symbol
(package private) static String matchFramework(String libraryName)
          Look for a matching framework (OSX)
(package private) static String matchLibrary(String libName, List searchPath)
          matchLibrary() is very Linux specific.
(package private) static double parseVersion(String ver)
           
 String toString()
           
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

callFlags

final int callFlags

options

final Map options
Method Detail

matchFramework

static String matchFramework(String libraryName)
Look for a matching framework (OSX)


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 "QuickTime.framework/Versions/Current/QuickTime"), or the full (absolute) path to the library (e.g. "/lib/libc.so.6").
options - native library options for the given library (see Library).

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.


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

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

getOptions

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


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

getSymbolAddress

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

Throws:
UnsatisfiedLinkError - if the symbol can't be found

toString

public String toString()
Overrides:
toString in class Object

getName

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


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.


finalize

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

Overrides:
finalize in class Object

disposeAll

static void disposeAll()
Close all open native libraries.


dispose

public void dispose()
Close the native library we're mapped to.


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)

JNA API 3.5.2

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