Function (JNA API)
Description: declaration: package: com.sun.jna, class: Function

Package 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
  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
  Description
  `static final int`
  `ALT_CONVENTION`
  First alternate convention (currently used only for w32 stdcall).
  `static final int`
  `C_CONVENTION`
  Standard C calling convention.
  `(package private) final int`
  `callFlags`
  `(package private) final String`
  `encoding`
  `(package private) static final Integer`
  `INTEGER_FALSE`
  `(package private) static final Integer`
  `INTEGER_TRUE`
  `static final int`
  `MAX_NARGS`
  Maximum number of arguments supported by a JNA function call.
  `(package private) static final String`
  `OPTION_INVOKING_METHOD`
  For internal JNA use.
  `(package private) final Map<String,?>`
  `options`
  `static final int`
  `THROW_LAST_ERROR`
  Whether to throw an exception if last error is non-zero after call.
  `static final 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
  Description
  `Function(NativeLibrary library, String functionName, int callFlags, String encoding)`
  Create a new `Function` that is linked with a native function that follows the given calling convention.
  `Function(Pointer functionAddress, int callFlags, String encoding)`
  Create a new `Function` that is linked with a native function that follows the given calling convention.

- ## Method Summary

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

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

  - ### INTEGER_FALSE

    static final Integer INTEGER_FALSE

  - ### encoding

    final String encoding

  - ### callFlags

    final int callFlags

  - ### options

    final Map<String,?> options

  - ### OPTION_INVOKING_METHOD

    static final String OPTION_INVOKING_METHOD
    For internal JNA use.
    See Also:
      - Constant Field Values

- ## Constructor Details

  - ### Function

    Function(NativeLibrary library, String functionName, int callFlags, 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:
      `UnsatisfiedLinkError` - if the given function name is not found within the library.

  - ### Function

    Function(Pointer functionAddress, int callFlags, 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 Details

  - ### getFunction

    public static Function getFunction(String libraryName, 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:
      `UnsatisfiedLinkError` - if the library is not found or the given function name is not found within the library.

  - ### getFunction

    public static Function getFunction(String libraryName, 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:
      `UnsatisfiedLinkError` - if the library is not found or the given function name is not found within the library.

  - ### getFunction

    public static Function getFunction(String libraryName, String functionName, int callFlags, 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:
      `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, 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 String getName()

  - ### getCallingConvention

    public int getCallingConvention()

  - ### invoke

    public Object invoke(Class<?> returnType, Object[] inArgs)
    Invoke the native function with the given arguments, returning the native result as an Object.

  - ### invoke

    public Object invoke(Class<?> returnType, Object[] inArgs, Map<String,?> options)
    Invoke the native function with the given arguments, returning the native result as an Object.

  - ### invoke

    Object invoke(Method invokingMethod, Class<?>[] paramTypes, Class<?> returnType, Object[] inArgs, Map<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

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

  - ### invoke

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

  - ### invoke

    public void invoke(Object[] args)
    Call the native function being represented by this object
    Parameters:
      `args` - Arguments to pass to the native function

  - ### toString

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

  - ### invokeObject

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

  - ### invokePointer

    public Pointer invokePointer(Object[] args)
    Convenience method for `invoke(Pointer.class, args)`.

  - ### invokeString

    public String invokeString(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(Object[] args)
    Convenience method for `invoke(Integer.class, args)`.

  - ### invokeLong

    public long invokeLong(Object[] args)
    Convenience method for `invoke(Long.class, args)`.

  - ### invokeFloat

    public float invokeFloat(Object[] args)
    Convenience method for `invoke(Float.class, args)`.

  - ### invokeDouble

    public double invokeDouble(Object[] args)
    Convenience method for `invoke(Double.class, args)`.

  - ### invokeVoid

    public void invokeVoid(Object[] args)
    Convenience method for `invoke(Void.class, args)`.

  - ### equals

    public boolean equals(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 Object[] concatenateVarArgs(Object[] inArgs)
    Concatenate varargs with normal args to obtain a simple argument array.

  - ### isVarArgs

    static boolean isVarArgs(Method m)
    Varargs are only supported on 1.5+.

  - ### fixedArgs

    static int fixedArgs(Method m)
    Varargs are only supported on 1.5+.

  - ### valueOf

    static Boolean valueOf(boolean b)
    Implementation of Boolean.valueOf for older VMs.