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:Functionrepresents a pointer to some native function.invoke(Class,Object[],Map)is the primary means to call the function.C_CONVENTIONUse C calling convention (default)ALT_CONVENTIONUse alternate calling convention (e.g. stdcall)THROW_LAST_ERRORThrow aLastErrorExceptionif 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 interfaceFunction.PostCallReadAny 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 intALT_CONVENTIONFirst alternate convention (currently used only for w32 stdcall).static intC_CONVENTIONStandard C calling convention.(package private) intcallFlags(package private) java.lang.Stringencoding(package private) static java.lang.IntegerINTEGER_FALSE(package private) static java.lang.IntegerINTEGER_TRUEstatic intMAX_NARGSMaximum number of arguments supported by a JNA function call.(package private) static java.lang.StringOPTION_INVOKING_METHODFor internal JNA use.(package private) java.util.Map<java.lang.String,?>optionsstatic intTHROW_LAST_ERRORWhether to throw an exception if last error is non-zero after call.static intUSE_VARARGSMask for number of fixed args (1-3) for varargs calls.
-
Constructor Summary
Constructors Constructor Description Function(NativeLibrary library, java.lang.String functionName, int callFlags, java.lang.String encoding)Create a newFunctionthat is linked with a native function that follows the given calling convention.Function(Pointer functionAddress, int callFlags, java.lang.String encoding)Create a newFunctionthat 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 java.lang.Object[]concatenateVarArgs(java.lang.Object[] inArgs)Concatenate varargs with normal args to obtain a simple argument array.booleanequals(java.lang.Object o)Two function pointers are equal if they share the same peer address and calling convention.(package private) static intfixedArgs(java.lang.reflect.Method m)Varargs are only supported on 1.5+.intgetCallingConvention()static FunctiongetFunction(Pointer p)Obtain aFunctionrepresenting a native function pointer.static FunctiongetFunction(Pointer p, int callFlags)Obtain aFunctionrepresenting a native function pointer.static FunctiongetFunction(Pointer p, int callFlags, java.lang.String encoding)Obtain aFunctionrepresenting a native function pointer.static FunctiongetFunction(java.lang.String libraryName, java.lang.String functionName)Obtain aFunctionrepresenting a native function that follows the standard "C" calling convention.static FunctiongetFunction(java.lang.String libraryName, java.lang.String functionName, int callFlags)Obtain aFunctionrepresenting a native function.static FunctiongetFunction(java.lang.String libraryName, java.lang.String functionName, int callFlags, java.lang.String encoding)Obtain aFunctionrepresenting a native function.java.lang.StringgetName()inthashCode()Provide a unique hash code forFunctions which are equivalent.java.lang.Objectinvoke(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.Objectinvoke(java.lang.Class<?> returnType, java.lang.Object[] inArgs, java.util.Map<java.lang.String,?> options)Invoke the native function with the given arguments, returning the native result as an Object.voidinvoke(java.lang.Object[] args)Call the native function being represented by this object(package private) java.lang.Objectinvoke(java.lang.Object[] args, java.lang.Class<?> returnType, boolean allowObjects)(package private) java.lang.Objectinvoke(java.lang.Object[] args, java.lang.Class<?> returnType, boolean allowObjects, int fixedArgs)(package private) java.lang.Objectinvoke(java.lang.reflect.Method invokingMethod, java.lang.Class<?>[] paramTypes, java.lang.Class<?> returnType, java.lang.Object[] inArgs, java.util.Map<java.lang.String,?> options)Invoke the native function with the given arguments, returning the native result as an Object.doubleinvokeDouble(java.lang.Object[] args)Convenience method forinvoke(Double.class, args).floatinvokeFloat(java.lang.Object[] args)Convenience method forinvoke(Float.class, args).intinvokeInt(java.lang.Object[] args)Convenience method forinvoke(Integer.class, args).longinvokeLong(java.lang.Object[] args)Convenience method forinvoke(Long.class, args).java.lang.ObjectinvokeObject(java.lang.Object[] args)Convenience method forinvokeObject(Object.class, args).PointerinvokePointer(java.lang.Object[] args)Convenience method forinvoke(Pointer.class, args).java.lang.StringinvokeString(java.lang.Object[] args, boolean wide)Convenience method forinvoke(String.class, args)orinvoke(WString.class, args)voidinvokeVoid(java.lang.Object[] args)Convenience method forinvoke(Void.class, args).(package private) static booleanisVarArgs(java.lang.reflect.Method m)Varargs are only supported on 1.5+.java.lang.StringtoString()Provide a human-readable representation of this object.(package private) static java.lang.BooleanvalueOf(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 java.lang.Integer INTEGER_TRUE
-
INTEGER_FALSE
static final java.lang.Integer INTEGER_FALSE
-
encoding
final java.lang.String encoding
-
callFlags
final int callFlags
-
options
final java.util.Map<java.lang.String,?> 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, java.lang.String encoding)
Create a newFunctionthat 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-NativeLibraryin 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:
java.lang.UnsatisfiedLinkError- if the given function name is not found within the library.
-
Function
Function(Pointer functionAddress, int callFlags, java.lang.String encoding)
Create a newFunctionthat 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(java.lang.String libraryName, java.lang.String functionName)
Obtain aFunctionrepresenting 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:
java.lang.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 aFunctionrepresenting 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:
java.lang.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, java.lang.String encoding)
Obtain aFunctionrepresenting 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:
java.lang.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 aFunctionrepresenting 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 aFunctionrepresenting 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, java.lang.String encoding)
Obtain aFunctionrepresenting 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 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<java.lang.String,?> options)Invoke the native function with the given arguments, returning the native result as an Object.
-
invoke
java.lang.Object invoke(java.lang.reflect.Method invokingMethod, java.lang.Class<?>[] paramTypes, java.lang.Class<?> returnType, java.lang.Object[] inArgs, java.util.Map<java.lang.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
java.lang.Object invoke(java.lang.Object[] args, java.lang.Class<?> returnType, boolean allowObjects)
-
invoke
java.lang.Object invoke(java.lang.Object[] args, java.lang.Class<?> returnType, boolean allowObjects, int fixedArgs)
-
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.
-
invokeObject
public java.lang.Object invokeObject(java.lang.Object[] args)
Convenience method forinvokeObject(Object.class, args).
-
invokePointer
public Pointer invokePointer(java.lang.Object[] args)
Convenience method forinvoke(Pointer.class, args).
-
invokeString
public java.lang.String invokeString(java.lang.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(java.lang.Object[] args)
Convenience method forinvoke(Integer.class, args).
-
invokeLong
public long invokeLong(java.lang.Object[] args)
Convenience method forinvoke(Long.class, args).
-
invokeFloat
public float invokeFloat(java.lang.Object[] args)
Convenience method forinvoke(Float.class, args).
-
invokeDouble
public double invokeDouble(java.lang.Object[] args)
Convenience method forinvoke(Double.class, args).
-
invokeVoid
public void invokeVoid(java.lang.Object[] args)
Convenience method forinvoke(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.
-
hashCode
public int hashCode()
Provide a unique hash code forFunctions which are equivalent.
-
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+.
-
fixedArgs
static int fixedArgs(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.
-
-