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

static interface

Function.PostCallRead Any argument which implements this interface will have the Function.PostCallRead.read() method called immediately after function invocation.

Field Summary

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) 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	options
static int	THROW_LAST_ERROR Whether to throw an exception if last error is non-zero after call.

Fields inherited from class com.sun.jna.Pointer

NULL, peer, SIZE

Constructor Summary

Function(NativeLibrary library, java.lang.String functionName, int callFlags)
Create a new Function that is linked with a native function that follows the given calling convention.

Function(Pointer functionAddress, int callFlags)
Create a new Function that is linked with a native function that follows the given calling convention.

Method Summary

(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.
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(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.
java.lang.String	getName()
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 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)
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

_setMemory, clear, createConstant, createConstant, 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, hashCode, indexOf, nativeValue, nativeValue, read, read, read, read, read, read, read, read, setByte, setChar, setDouble, setFloat, setInt, setLong, setMemory, setNativeLong, setPointer, setShort, setString, setString, setValue, 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

INTEGER_TRUE

static final java.lang.Integer INTEGER_TRUE

INTEGER_FALSE

static final java.lang.Integer INTEGER_FALSE

callFlags

int callFlags

options

final java.util.Map 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)

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

Throws:

{@link - UnsatisfiedLinkError} if the given function name is not found within the library.

Function

Function(Pointer functionAddress,
         int callFlags)

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

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:

{@link - 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:

{@link - 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

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 options)

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

invoke

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

See Also:

implementation

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

Parameters:

o - A Pointer instance

Returns:

True if the other object is a Pointer, and the C pointers being pointed to by these objects are also equal. Returns false otherwise.

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+.

valueOf

static java.lang.Boolean valueOf(boolean b)

Implementation of Boolean.valueOf for older VMs.