NativeLibrary (JNA API)

Overview | Package | Class | Tree | Deprecated | Index | Help
| JNA API 3.3.0
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.sun.jna
Class NativeLibrary

    java.lang.Object
      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

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

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` | `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

### 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`).

### 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)

Overview | Package | Class | Tree | Deprecated | Index | Help
| JNA API 3.3.0
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

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