com.sun.jna

## Interface Library

- All Known Subinterfaces:
    Advapi32, BaseTSD, Carbon, CoreDLL, Crypt32, DBT, DsGetDC, GDI32, Kernel32, LMAccess, LMCons, LMErr, LMJoin, MacFileUtils.FileManager, Msi, Netapi32, NtDll, NTSecApi, Ole32, OleAuto, Secur32, SetupApi, Shell32, ShellAPI, Sspi, StdCallLibrary, Tlhelp32, User32, VerRsrc, Version, W32APIOptions, Wdm, WinBase, WinCrypt, WinDef, WinGDI, Winioctl, WinNT, WinReg, Winspool, Winsvc, WinUser, Wtsapi32, X11, X11.Xevie, X11.Xext, X11.Xrender, X11.XTest
  All Known Implementing Classes:
    Kernel32Util

      public interface Library

  Derive from this interface for all native library definitions. Define an instance of your library like this: `

       MyNativeLibrary INSTANCE = (MyNativeLibrary)
           Native.loadLibrary("mylib", MyNativeLibrary.class);

  `

  By convention, method names are identical to the native names, although you can map java names to different native names by providing a `FunctionMapper` as a value for key `OPTION_FUNCTION_MAPPER` in the options map passed to the `Native.loadLibrary(String, Class, Map)` call.

  Although the names for structures and structure fields may be chosen arbitrarily, they should correspond as closely as possible to the native definitions. The same is true for parameter names.

  This interface supports multiple, concurrent invocations of any library methods on the Java side. Check your library documentation for its multi-threading requirements on the native side. If a library is not safe for simultaneous multi-threaded access, consider using `Native.synchronizedLibrary(com.sun.jna.Library)` to prevent simultaneous multi-threaded access to the native code.

  Optional fields
  Interface options will be automatically propagated to structures defined within the library provided a call to `Native.loadLibrary(String,Class,Map)` is made prior to instantiating any of those structures. One common way of ensuring this is to declare an INSTANCE field in the interface which holds the `loadLibrary` result.

  OPTIONS (an instance of `Map`), TYPE_MAPPER (an instance of `TypeMapper`), STRUCTURE_ALIGNMENT (one of the alignment types defined in `Structure`), and STRING_ENCODING (a `String`) may also be defined. If no instance of the interface has been instantiated, these fields will be used to determine customization settings for structures and methods defined within the interface.

  Author:
    Todd Fast, todd.fast@sun.com, Timothy Wall, twalljava@dev.java.net

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Interface and Description
    --- | ---
    `static class` | `Library.Handler`

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.lang.String` | `OPTION_ALLOW_OBJECTS` Option key for a boolean flag to allow any Java class instance as a parameter.
    `static java.lang.String` | `OPTION_CALLING_CONVENTION` Calling convention for the entire library.
    `static java.lang.String` | `OPTION_CLASSLOADER` Class loader to use when searching for native libraries on the resource path (classpath).
    `static java.lang.String` | `OPTION_FUNCTION_MAPPER` Option key for a `FunctionMapper` for the library.
    `static java.lang.String` | `OPTION_INVOCATION_MAPPER` Option key for an `InvocationMapper` for the library.
    `static java.lang.String` | `OPTION_OPEN_FLAGS` Flags to use when opening the native library (see `Native.open(String,int)`)
    `static java.lang.String` | `OPTION_STRING_ENCODING` Option key for per-library String encoding.
    `static java.lang.String` | `OPTION_STRUCTURE_ALIGNMENT` Option key for structure alignment type (`Integer`), which should be one of the predefined alignment types in `Structure`.
    `static java.lang.String` | `OPTION_TYPE_MAPPER` Option key for a `TypeMapper` for the library.

- - ### Field Detail

    - #### OPTION_TYPE_MAPPER

          static final java.lang.String OPTION_TYPE_MAPPER

      Option key for a `TypeMapper` for the library.
      See Also:
        Constant Field Values

    - #### OPTION_FUNCTION_MAPPER

          static final java.lang.String OPTION_FUNCTION_MAPPER

      Option key for a `FunctionMapper` for the library.
      See Also:
        Constant Field Values

    - #### OPTION_INVOCATION_MAPPER

          static final java.lang.String OPTION_INVOCATION_MAPPER

      Option key for an `InvocationMapper` for the library.
      See Also:
        Constant Field Values

    - #### OPTION_STRUCTURE_ALIGNMENT

          static final java.lang.String OPTION_STRUCTURE_ALIGNMENT

      Option key for structure alignment type (`Integer`), which should be one of the predefined alignment types in `Structure`.
      See Also:
        Constant Field Values

    - #### OPTION_STRING_ENCODING

          static final java.lang.String OPTION_STRING_ENCODING

      Option key for per-library String encoding. This affects conversions between Java unicode and native (`const char*`) strings (as arguments or Structure fields).

      Defaults to `Native.getDefaultStringEncoding()`.
      See Also:
        Constant Field Values

    - #### OPTION_ALLOW_OBJECTS

          static final java.lang.String OPTION_ALLOW_OBJECTS

      Option key for a boolean flag to allow any Java class instance as a parameter. If no type mapper is found, the object is passed as a pointer. NOTE: This is for use with raw JNI interactions via the JNIEnv data structure.
      See Also:
        Constant Field Values

    - #### OPTION_CALLING_CONVENTION

          static final java.lang.String OPTION_CALLING_CONVENTION

      Calling convention for the entire library.
      See Also:
        Constant Field Values

    - #### OPTION_OPEN_FLAGS

          static final java.lang.String OPTION_OPEN_FLAGS

      Flags to use when opening the native library (see `Native.open(String,int)`)
      See Also:
        Constant Field Values

    - #### OPTION_CLASSLOADER

          static final java.lang.String OPTION_CLASSLOADER

      Class loader to use when searching for native libraries on the resource path (classpath). If not provided the current thread's context class loader is used.

      If extracted from the resource path (i.e. bundled in a jar file), the loaded library's lifespan will mirror that of the class loader, which means you can use the same library in isolated contexts without conflict.
      See Also:
        Constant Field Values

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