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.