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
`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
`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 (1-3) 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
`(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 (1-3) 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.