NativeLibrary (JNA API)

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. 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 `Platform.getNativeLibraryResourcePrefix()`. If bundled in a jar file, the resource will be extracted to `jna.tmpdir` for loading, and later removed (but only if `jna.nounpack` is false or not set).
  You may set the system property `jna.debug_load=true` to make JNA print the steps of its library search to the console.
  Author:
    Wayne Meissner, split library loading from Function.java, twall

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `(package private) int` | `callFlags`
    `(package private) java.util.Map<java.lang.String,?>` | `options`

  - ### 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()` 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.
    `java.io.File` | `getFile()` Returns the file on disk corresponding to this NativeLibrary instance.
    `Function` | `getFunction(java.lang.String functionName)` Create a new `Function` that is linked with a native function that follows the NativeLibrary's calling convention.
    `Function` | `getFunction(java.lang.String functionName, int callFlags)` Create a new `Function` that is linked with a native function that follows a given calling flags.
    `Function` | `getFunction(java.lang.String functionName, int callFlags, java.lang.String encoding)` Create a new `Function` that is linked with a native function that follows a given calling flags.
    `(package private) Function` | `getFunction(java.lang.String name, java.lang.reflect.Method method)` Create a new `Function` that is linked with a native function that follows the NativeLibrary's 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.
    `static NativeLibrary` | `getInstance(java.lang.String libraryName, java.lang.ClassLoader classLoader)` Returns an instance of NativeLibrary for the specified name.
    `static NativeLibrary` | `getInstance(java.lang.String libraryName, java.util.Map<java.lang.String,?> libraryOptions)` Returns an instance of NativeLibrary for the specified name.
    `java.lang.String` | `getName()` Returns the simple name of this library.
    `java.util.Map<java.lang.String,?>` | `getOptions()`
    `static NativeLibrary` | `getProcess()` Returns an instance of NativeLibrary which refers to the current process.
    `static NativeLibrary` | `getProcess(java.util.Map<java.lang.String,?> options)` Returns an instance of NativeLibrary which refers to the current process.
    `(package private) long` | `getSymbolAddress(java.lang.String name)` Used by the Function class to locate a symbol
    `(package private) static java.lang.String` | `mapSharedLibraryName(java.lang.String libName)` Similar to `System.mapLibraryName(java.lang.String)`, except that it maps to standard shared library formats rather than specifically JNI formats.
    `(package private) static java.lang.String` | `matchFramework(java.lang.String libraryName)` Look for a matching framework (OSX)
    `(package private) static java.lang.String` | `matchLibrary(java.lang.String libName, java.util.List<java.lang.String> 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`

- - ### Field Detail

    - #### callFlags

          final int callFlags

    - #### options

          final java.util.Map<java.lang.String,?> options

  - ### Method Detail

    - #### matchFramework

          static java.lang.String matchFramework(java.lang.String libraryName)

      Look for a matching framework (OSX)

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

    - #### getInstance

          public static final NativeLibrary getInstance(java.lang.String libraryName,
                                  java.lang.ClassLoader classLoader)

      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").
        `classLoader` - The class loader to use to load the native library. This only affects library loading when the native library is included somewhere in the classpath, either bundled in a jar file or as a plain file within the classpath.

    - #### getInstance

          public static final NativeLibrary getInstance(java.lang.String libraryName,
                                  java.util.Map<java.lang.String,?> libraryOptions)

      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").
        `libraryOptions` - 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(java.util.Map<java.lang.String,?> 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(java.lang.String libraryName,
                           java.lang.String path)

      Add a path to search for the specified library, ahead of any system paths. This is similar to setting `jna.library.path`, but only extends the search path for a single library.
      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 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:
        `java.lang.UnsatisfiedLinkError` - if the function is not found

    - #### getFunction

          Function getFunction(java.lang.String name,
                             java.lang.reflect.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. Uses a function mapper option if one was provided to transform the name.
        `method` - Method to which the native function is to be mapped
      Throws:
        `java.lang.UnsatisfiedLinkError` - if the function is not found

    - #### getFunction

          public Function getFunction(java.lang.String functionName,
                             int callFlags)

      Create a new `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:
        `java.lang.UnsatisfiedLinkError` - if the function is not found

    - #### getFunction

          public Function getFunction(java.lang.String functionName,
                             int callFlags,
                             java.lang.String encoding)

      Create a new `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
        `encoding` - Encoding to use to convert between Java and native strings.
      Throws:
        `java.lang.UnsatisfiedLinkError` - if the function is not found

    - #### getOptions

          public java.util.Map<java.lang.String,?> getOptions()

      Returns:
        this native library instance's options.

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

    - #### disposeAll

          static void disposeAll()

      Close all open native libraries.

    - #### dispose

          public void dispose()

      Close the native library we're mapped to.

    - #### mapSharedLibraryName

          static java.lang.String mapSharedLibraryName(java.lang.String libName)

      Similar to `System.mapLibraryName(java.lang.String)`, except that it maps to standard shared library formats rather than specifically JNI formats.
      Parameters:
        `libName` - base (undecorated) name of library

    - #### matchLibrary

          static java.lang.String matchLibrary(java.lang.String libName,
                                      java.util.List<java.lang.String> 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)

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