com.sun.jna

## Class Function

- java.lang.Object
- - com.sun.jna.Pointer
  - - com.sun.jna.Function

-     public class Function
      extends Pointer

  An abstraction for a native function pointer. An instance of `Function` represents a pointer to some native function. `invoke(Class,Object[],Map)` is the primary means to call the function.

  Function call behavior may be modified by passing one of the following call flags:
  - `C_CONVENTION` Use C calling convention (default)
  - `ALT_CONVENTION` Use alternate calling convention (e.g. stdcall)
  - `THROW_LAST_ERROR` Throw a `LastErrorException` if the native function sets the system error to a non-zero value (errno or GetLastError). Setting this flag will cause the system error to be cleared prior to native function invocation.
  Author:
    Sheng Liang, originator, Todd Fast, suitability modifications, Timothy Wall
  See Also:
    `Pointer`

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static interface` | `Function.PostCallRead` Any argument which implements this interface will have the `Function.PostCallRead.read()` method called immediately after function invocation.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `ALT_CONVENTION` First alternate convention (currently used only for w32 stdcall).
    `static int` | `C_CONVENTION` Standard C calling convention.
    `(package private) int` | `callFlags`
    `(package private) java.lang.String` | `encoding`
    `(package private) static java.lang.Integer` | `INTEGER_FALSE`
    `(package private) static java.lang.Integer` | `INTEGER_TRUE`
    `static int` | `MAX_NARGS` Maximum number of arguments supported by a JNA function call.
    `(package private) static java.lang.String` | `OPTION_INVOKING_METHOD` For internal JNA use.
    `(package private) java.util.Map` | `options`
    `static int` | `THROW_LAST_ERROR` Whether to throw an exception if last error is non-zero after call.

    - ### Fields inherited from class com.sun.jna.Pointer

      `NULL, peer, SIZE`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Function(NativeLibrary library, java.lang.String functionName, int callFlags, java.lang.String encoding)` Create a new `Function` that is linked with a native function that follows the given calling convention.
    `Function(Pointer functionAddress, int callFlags, java.lang.String encoding)` Create a new `Function` that is linked with a native function that follows the given calling convention.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `(package private) static java.lang.Object[]` | `concatenateVarArgs(java.lang.Object[] inArgs)` Concatenate varargs with normal args to obtain a simple argument array.
    `boolean` | `equals(java.lang.Object o)` Two function pointers are equal if they share the same peer address and calling convention.
    `int` | `getCallingConvention()`
    `static Function` | `getFunction(Pointer p)` Obtain a `Function` representing a native function pointer.
    `static Function` | `getFunction(Pointer p, int callFlags)` Obtain a `Function` representing a native function pointer.
    `static Function` | `getFunction(java.lang.String libraryName, java.lang.String functionName)` Obtain a `Function` representing a native function that follows the standard "C" calling convention.
    `static Function` | `getFunction(java.lang.String libraryName, java.lang.String functionName, int callFlags)` Obtain a `Function` representing a native function.
    `static Function` | `getFunction(java.lang.String libraryName, java.lang.String functionName, int callFlags, java.lang.String encoding)` Obtain a `Function` representing a native function.
    `java.lang.String` | `getName()`
    `int` | `hashCode()` Provide a unique hash code for `Function`s which are equivalent.
    `java.lang.Object` | `invoke(java.lang.Class returnType, java.lang.Object[] inArgs)` Invoke the native function with the given arguments, returning the native result as an Object.
    `java.lang.Object` | `invoke(java.lang.Class returnType, java.lang.Object[] inArgs, java.util.Map options)` Invoke the native function with the given arguments, returning the native result as an Object.
    `void` | `invoke(java.lang.Object[] args)` Call the native function being represented by this object
    `(package private) java.lang.Object` | `invoke(java.lang.Object[] args, java.lang.Class returnType, boolean allowObjects)`
    `double` | `invokeDouble(java.lang.Object[] args)` Convenience method for `invoke(Double.class, args)`.
    `float` | `invokeFloat(java.lang.Object[] args)` Convenience method for `invoke(Float.class, args)`.
    `int` | `invokeInt(java.lang.Object[] args)` Convenience method for `invoke(Integer.class, args)`.
    `long` | `invokeLong(java.lang.Object[] args)` Convenience method for `invoke(Long.class, args)`.
    `java.lang.Object` | `invokeObject(java.lang.Object[] args)` Convenience method for `invokeObject(Object.class, args)`.
    `Pointer` | `invokePointer(java.lang.Object[] args)` Convenience method for `invoke(Pointer.class, args)`.
    `java.lang.String` | `invokeString(java.lang.Object[] args, boolean wide)` Convenience method for `invoke(String.class, args)` or `invoke(WString.class, args)`
    `void` | `invokeVoid(java.lang.Object[] args)` Convenience method for `invoke(Void.class, args)`.
    `(package private) static boolean` | `isVarArgs(java.lang.reflect.Method m)` Varargs are only supported on 1.5+.
    `java.lang.String` | `toString()` Provide a human-readable representation of this object.
    `(package private) static java.lang.Boolean` | `valueOf(boolean b)` Implementation of Boolean.valueOf for older VMs.

    - ### Methods inherited from class com.sun.jna.Pointer

      `clear, createConstant, createConstant, dump, getByte, getByteArray, getByteBuffer, getChar, getCharArray, getDouble, getDoubleArray, getFloat, getFloatArray, getInt, getIntArray, getLong, getLongArray, getNativeLong, getPointer, getPointerArray, getPointerArray, getShort, getShortArray, getString, getString, getString, getStringArray, getStringArray, getStringArray, getStringArray, getStringArray, getStringArray, getValue, getWideString, getWideStringArray, getWideStringArray, indexOf, nativeValue, nativeValue, read, read, read, read, read, read, read, read, setByte, setChar, setDouble, setFloat, setInt, setLong, setMemory, setNativeLong, setPointer, setShort, setString, setString, setString, setString, setValue, setWideString, share, share, write, write, write, write, write, write, write, write`

    - ### Methods inherited from class java.lang.Object

      `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### MAX_NARGS

          public static final int MAX_NARGS

      Maximum number of arguments supported by a JNA function call.
      See Also:
        Constant Field Values

    - #### C_CONVENTION

          public static final int C_CONVENTION

      Standard C calling convention.
      See Also:
        Constant Field Values

    - #### ALT_CONVENTION

          public static final int ALT_CONVENTION

      First alternate convention (currently used only for w32 stdcall).
      See Also:
        Constant Field Values

    - #### THROW_LAST_ERROR

          public static final int THROW_LAST_ERROR

      Whether to throw an exception if last error is non-zero after call.
      See Also:
        Constant Field Values

    - #### INTEGER_TRUE

          static final java.lang.Integer INTEGER_TRUE

    - #### INTEGER_FALSE

          static final java.lang.Integer INTEGER_FALSE

    - #### encoding

          final java.lang.String encoding

    - #### callFlags

          final int callFlags

    - #### options

          final java.util.Map options

    - #### OPTION_INVOKING_METHOD

          static final java.lang.String OPTION_INVOKING_METHOD

      For internal JNA use.
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### Function

          Function(NativeLibrary library,
                  java.lang.String functionName,
                  int callFlags,
                  java.lang.String encoding)

      Create a new `Function` that is linked with a native function that follows the given calling convention.

      The allocated instance represents a pointer to the named native function from the supplied library, called with the given calling convention.

      Parameters:
        `library` - `NativeLibrary` in which to find the function
        `functionName` - Name of the native function to be linked with
        `callFlags` - Function call flags
        `encoding` - Encoding for conversion between Java and native strings.
      Throws:
        `{@link` - UnsatisfiedLinkError} if the given function name is not found within the library.

    - #### Function

          Function(Pointer functionAddress,
                  int callFlags,
                  java.lang.String encoding)

      Create a new `Function` that is linked with a native function that follows the given calling convention.

      The allocated instance represents a pointer to the given function address, called with the given calling convention.

      Parameters:
        `functionAddress` - Address of the native function
        `callFlags` - Function call flags
        `encoding` - Encoding for conversion between Java and native strings.

  - ### Method Detail

    - #### getFunction

          public static Function getFunction(java.lang.String libraryName,
                             java.lang.String functionName)

      Obtain a `Function` representing a native function that follows the standard "C" calling convention.

      The allocated instance represents a pointer to the named native function from the named library, called with the standard "C" calling convention.

      Parameters:
        `libraryName` - Library in which to find the native function
        `functionName` - Name of the native function to be linked with
      Throws:
        `{@link` - UnsatisfiedLinkError} if the library is not found or the given function name is not found within the library.

    - #### getFunction

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

      Obtain a `Function` representing a native function.

      The allocated instance represents a pointer to the named native function from the named library.

      Parameters:
        `libraryName` - Library in which to find the function
        `functionName` - Name of the native function to be linked with
        `callFlags` - Function call flags
      Throws:
        `{@link` - UnsatisfiedLinkError} if the library is not found or the given function name is not found within the library.

    - #### getFunction

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

      Obtain a `Function` representing a native function.

      The allocated instance represents a pointer to the named native function from the named library.

      Parameters:
        `libraryName` - Library in which to find the function
        `functionName` - Name of the native function to be linked with
        `callFlags` - Function call flags
        `encoding` - Encoding to use for conversion between Java and native strings.
      Throws:
        `{@link` - UnsatisfiedLinkError} if the library is not found or the given function name is not found within the library.

    - #### getFunction

          public static Function getFunction(Pointer p)

      Obtain a `Function` representing a native function pointer. In general, this function should be used by dynamic languages; Java code should allow JNA to bind to a specific Callback interface instead by defining a return type or Structure field type.

      The allocated instance represents a pointer to the native function pointer.

      Parameters:
        `p` - Native function pointer

    - #### getFunction

          public static Function getFunction(Pointer p,
                             int callFlags)

      Obtain a `Function` representing a native function pointer. In general, this function should be used by dynamic languages; Java code should allow JNA to bind to a specific Callback interface instead by defining a return type or Structure field type.

      The allocated instance represents a pointer to the native function pointer.

      Parameters:
        `p` - Native function pointer
        `callFlags` - Function call flags

    - #### getName

          public java.lang.String getName()

    - #### getCallingConvention

          public int getCallingConvention()

    - #### invoke

          public java.lang.Object invoke(java.lang.Class returnType,
                                java.lang.Object[] inArgs)

      Invoke the native function with the given arguments, returning the native result as an Object.

    - #### invoke

          public java.lang.Object invoke(java.lang.Class returnType,
                                java.lang.Object[] inArgs,
                                java.util.Map options)

      Invoke the native function with the given arguments, returning the native result as an Object.

    - #### invoke

          java.lang.Object invoke(java.lang.Object[] args,
                                java.lang.Class returnType,
                                boolean allowObjects)

      See Also:
        `implementation`

    - #### invoke

          public void invoke(java.lang.Object[] args)

      Call the native function being represented by this object
      Parameters:
        `args` - Arguments to pass to the native function

    - #### toString

          public java.lang.String toString()

      Provide a human-readable representation of this object.
      Overrides:
        `toString` in class `Pointer`

    - #### invokeObject

          public java.lang.Object invokeObject(java.lang.Object[] args)

      Convenience method for `invokeObject(Object.class, args)`.

    - #### invokePointer

          public Pointer invokePointer(java.lang.Object[] args)

      Convenience method for `invoke(Pointer.class, args)`.

    - #### invokeString

          public java.lang.String invokeString(java.lang.Object[] args,
                                      boolean wide)

      Convenience method for `invoke(String.class, args)` or `invoke(WString.class, args)`
      Parameters:
        `args` - Arguments passed to native function
        `wide` - Whether the return value is of type `wchar_t*`; if false, the return value is of type `char*`.

    - #### invokeInt

          public int invokeInt(java.lang.Object[] args)

      Convenience method for `invoke(Integer.class, args)`.

    - #### invokeLong

          public long invokeLong(java.lang.Object[] args)

      Convenience method for `invoke(Long.class, args)`.

    - #### invokeFloat

          public float invokeFloat(java.lang.Object[] args)

      Convenience method for `invoke(Float.class, args)`.

    - #### invokeDouble

          public double invokeDouble(java.lang.Object[] args)

      Convenience method for `invoke(Double.class, args)`.

    - #### invokeVoid

          public void invokeVoid(java.lang.Object[] args)

      Convenience method for `invoke(Void.class, args)`.

    - #### equals

          public boolean equals(java.lang.Object o)

      Two function pointers are equal if they share the same peer address and calling convention.
      Overrides:
        `equals` in class `Pointer`
      Parameters:
        `o` - A `Pointer` instance
      Returns:
        True if the other object is a `Pointer`, and the C pointers being pointed to by these objects are also equal. Returns false otherwise.

    - #### hashCode

          public int hashCode()

      Provide a unique hash code for `Function`s which are equivalent.
      Overrides:
        `hashCode` in class `Pointer`
      Returns:
        A hash code value for the represented native pointer

    - #### concatenateVarArgs

          static java.lang.Object[] concatenateVarArgs(java.lang.Object[] inArgs)

      Concatenate varargs with normal args to obtain a simple argument array.

    - #### isVarArgs

          static boolean isVarArgs(java.lang.reflect.Method m)

      Varargs are only supported on 1.5+.

    - #### valueOf

          static java.lang.Boolean valueOf(boolean b)

      Implementation of Boolean.valueOf for older VMs.

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