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.

Author:

Sheng Liang, originator, Todd Fast, suitability modifications

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

Fields inherited from class com.sun.jna.Pointer

NULL, peer, SIZE

Constructor Summary

Constructors

Constructor and Description
Function(NativeLibrary library, java.lang.String functionName, int callingConvention) Create a new Function that is linked with a native function that follows the given calling convention.
Function(Pointer functionAddress, int callingConvention) Create a new Function that is linked with a native function that follows the given calling convention.

Method Summary

Methods

Modifier and Type	Method and Description
(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(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 callConvention) Obtain a Function representing a native function that follows a given calling convention.
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)
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).
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, getByte, getByteArray, getByteBuffer, getChar, getCharArray, getDouble, getDoubleArray, getFloat, getFloatArray, getInt, getIntArray, getLong, getLongArray, getNativeLong, getPointer, getPointerArray, getShort, getShortArray, getString, getString, hashCode, indexOf, read, read, read, read, read, read, read, read, setByte, setChar, setDouble, setFloat, setInt, setLong, setMemory, setNativeLong, setPointer, setShort, setString, setString, 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

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

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

callingConvention - Calling convention used by the native function

Throws:

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

Function

Function(Pointer functionAddress,
        int callingConvention)

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

callingConvention - Calling convention used by the native function

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

Obtain a Function representing a native function that follows a given calling convention.

The allocated instance represents a pointer to the named native function from the named library, called with the named calling convention.

Parameters:

libraryName - Library in which to find the function

functionName - Name of the native function to be linked with

callConvention - Call convention used by the native function

Throws:

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

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)

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

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.