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 call behavior may be modified by passing one of the following call flags:Function
represents a pointer to some native function.invoke(Class,Object[],Map)
is the primary means to call the function.C_CONVENTION
Use C calling convention (default)ALT_CONVENTION
Use alternate calling convention (e.g. stdcall)THROW_LAST_ERROR
Throw aLastErrorException
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 theFunction.PostCallRead.read()
method called immediately after function invocation.
-
Field Summary
Fields Modifier and Type Field 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.
-
Constructor Summary
Constructors Constructor Description Function(NativeLibrary library, String functionName, int callFlags, String encoding)
Create a newFunction
that is linked with a native function that follows the given calling convention.Function(Pointer functionAddress, int callFlags, String encoding)
Create a newFunction
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 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 aFunction
representing a native function pointer.static Function
getFunction(Pointer p, int callFlags)
Obtain aFunction
representing a native function pointer.static Function
getFunction(Pointer p, int callFlags, String encoding)
Obtain aFunction
representing a native function pointer.static Function
getFunction(String libraryName, String functionName)
Obtain aFunction
representing a native function that follows the standard "C" calling convention.static Function
getFunction(String libraryName, String functionName, int callFlags)
Obtain aFunction
representing a native function.static Function
getFunction(String libraryName, String functionName, int callFlags, String encoding)
Obtain aFunction
representing a native function.String
getName()
int
hashCode()
Provide a unique hash code forFunction
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 forinvoke(Double.class, args)
.float
invokeFloat(Object[] args)
Convenience method forinvoke(Float.class, args)
.int
invokeInt(Object[] args)
Convenience method forinvoke(Integer.class, args)
.long
invokeLong(Object[] args)
Convenience method forinvoke(Long.class, args)
.Object
invokeObject(Object[] args)
Convenience method forinvokeObject(Object.class, args)
.Pointer
invokePointer(Object[] args)
Convenience method forinvoke(Pointer.class, args)
.String
invokeString(Object[] args, boolean wide)
Convenience method forinvoke(String.class, args)
orinvoke(WString.class, args)
void
invokeVoid(Object[] args)
Convenience method forinvoke(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
-
-
-
-
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 Integer INTEGER_TRUE
-
INTEGER_FALSE
static final Integer INTEGER_FALSE
-
encoding
final String encoding
-
callFlags
final int callFlags
-
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 newFunction
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 functionfunctionName
- Name of the native function to be linked withcallFlags
- Function call flagsencoding
- 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 newFunction
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 functioncallFlags
- Function call flagsencoding
- Encoding for conversion between Java and native strings.
-
-
Method Detail
-
getFunction
public static Function getFunction(String libraryName, String functionName)
Obtain aFunction
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 functionfunctionName
- 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 aFunction
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 functionfunctionName
- Name of the native function to be linked withcallFlags
- 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 aFunction
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 functionfunctionName
- Name of the native function to be linked withcallFlags
- Function call flagsencoding
- 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 aFunction
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 aFunction
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 pointercallFlags
- Function call flags
-
getFunction
public static Function getFunction(Pointer p, int callFlags, String encoding)
Obtain aFunction
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 pointercallFlags
- Function call flagsencoding
- 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 callinginvoke(Class, Object[], Map)
, the method has to be in the options under keyOPTION_INVOKING_METHOD
.
-
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.
-
invokeObject
public Object invokeObject(Object[] args)
Convenience method forinvokeObject(Object.class, args)
.
-
invokePointer
public Pointer invokePointer(Object[] args)
Convenience method forinvoke(Pointer.class, args)
.
-
invokeString
public String invokeString(Object[] args, boolean wide)
Convenience method forinvoke(String.class, args)
orinvoke(WString.class, args)
- Parameters:
args
- Arguments passed to native functionwide
- Whether the return value is of typewchar_t*
; if false, the return value is of typechar*
.
-
invokeInt
public int invokeInt(Object[] args)
Convenience method forinvoke(Integer.class, args)
.
-
invokeLong
public long invokeLong(Object[] args)
Convenience method forinvoke(Long.class, args)
.
-
invokeFloat
public float invokeFloat(Object[] args)
Convenience method forinvoke(Float.class, args)
.
-
invokeDouble
public double invokeDouble(Object[] args)
Convenience method forinvoke(Double.class, args)
.
-
invokeVoid
public void invokeVoid(Object[] args)
Convenience method forinvoke(Void.class, args)
.
-
equals
public boolean equals(Object o)
Two function pointers are equal if they share the same peer address and calling convention.
-
hashCode
public int hashCode()
Provide a unique hash code forFunction
s which are equivalent.
-
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.
-
-