Function (JNA API)

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<java.lang.String,?>` | `options`
    `static int` | `THROW_LAST_ERROR` Whether to throw an exception if last error is non-zero after call.
    `static int` | `USE_VARARGS` Mask for number of fixed args (max 255) for varargs calls.

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

      `NULL, peer`

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

    All Methods Static Methods Instance Methods Concrete 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.
    `(package private) static int` | `fixedArgs(java.lang.reflect.Method m)` Varargs are only supported on 1.5+.
    `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(Pointer p, int callFlags, java.lang.String encoding)` 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<java.lang.String,?> options)` Invoke the native function with the given arguments, returning the native result as an Object.
    `(package private) java.lang.Object` | `invoke(java.lang.reflect.Method invokingMethod, java.lang.Class<?>[] paramTypes, java.lang.Class<?> returnType, java.lang.Object[] inArgs, java.util.Map<java.lang.String,?> 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)`
    `(package private) java.lang.Object` | `invoke(java.lang.Object[] args, java.lang.Class<?> returnType, boolean allowObjects, int fixedArgs)`
    `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, 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, 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

          @Native
          public static final int MAX_NARGS

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

    - #### C_CONVENTION

          @Native
          public static final int C_CONVENTION

      Standard C calling convention.
      See Also:
        Constant Field Values

    - #### ALT_CONVENTION

          @Native
          public static final int ALT_CONVENTION

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

    - #### THROW_LAST_ERROR

          @Native
          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

    - #### USE_VARARGS

          @Native
          public static final int USE_VARARGS

      Mask for number of fixed args (max 255) for varargs calls.
      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<java.lang.String,?> 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:
        `java.lang.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:
        `java.lang.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:
        `java.lang.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:
        `java.lang.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

    - #### getFunction

          public static Function getFunction(Pointer p,
                                             int callFlags,
                                             java.lang.String encoding)

      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
        `encoding` - Encoding to use for conversion between Java and native strings.

    - #### 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<java.lang.String,?> options)

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

    - #### invoke

          java.lang.Object invoke(java.lang.reflect.Method invokingMethod,
                                  java.lang.Class<?>[] paramTypes,
                                  java.lang.Class<?> returnType,
                                  java.lang.Object[] inArgs,
                                  java.util.Map<java.lang.String,?> options)

      Invoke the native function with the given arguments, returning the native result as an Object. This method can be called if invoking method and parameter types are already at hand. When calling `invoke(Class, Object[], Map)`, the method has to be in the options under key `OPTION_INVOKING_METHOD`.

    - #### invoke

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

    - #### invoke

          java.lang.Object invoke(java.lang.Object[] args,
                                  java.lang.Class<?> returnType,
                                  boolean allowObjects,
                                  int fixedArgs)

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

    - #### hashCode

          public int hashCode()

      Provide a unique hash code for `Function`s which are equivalent.
      Overrides:
        `hashCode` in class `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+.

    - #### fixedArgs

          static int fixedArgs(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-2018 Timothy Wall. All Rights Reserved.