Function (JNA API)

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) String`	`encoding`
`(package private) static Integer`	`INTEGER_FALSE`
`(package private) static Integer`	`INTEGER_TRUE`
`static int`	`MAX_NARGS` Maximum number of arguments supported by a JNA function call.
`(package private) static String`	`OPTION_INVOKING_METHOD` For internal JNA use.
`(package private) Map<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, SIZE

Constructor Summary

Constructors
Constructor and 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

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and 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.
`(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.
`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)`
`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, 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
  - USE_VARARGS
```
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 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 Detail
  - 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 Detail
  - 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 Functions 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.

Class Function

Nested Class Summary

Field Summary

Fields inherited from class com.sun.jna.Pointer

Constructor Summary

Method Summary

Methods inherited from class com.sun.jna.Pointer

Methods inherited from class java.lang.Object

Field Detail

MAX_NARGS

C_CONVENTION

ALT_CONVENTION

THROW_LAST_ERROR

USE_VARARGS

INTEGER_TRUE

INTEGER_FALSE

encoding

callFlags

options

OPTION_INVOKING_METHOD

Constructor Detail

Function

Function

Method Detail

getFunction

getFunction

getFunction

getFunction

getFunction

getFunction

getName

getCallingConvention

invoke

invoke

invoke

invoke

invoke

invoke

toString

invokeObject

invokePointer

invokeString

invokeInt

invokeLong

invokeFloat

invokeDouble

invokeVoid

equals

hashCode

concatenateVarArgs

isVarArgs

fixedArgs

valueOf