Skip to main content

JNA API 3.2.7

com.sun.jna
Class Function

java.lang.Object
  
extended by com.sun.jna.Pointer extended by 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 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 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, 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 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.
 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(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.
 String getName()
           
 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 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)
           
 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
_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 Integer INTEGER_TRUE

INTEGER_FALSE

static final Integer INTEGER_FALSE

callFlags

int callFlags

options

final Map options

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)
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(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:
{@link - 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:
{@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 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 options)
Invoke the native function with the given arguments, returning the native result as an Object.


invoke

Object invoke(Object[] args,
              Class returnType,
              boolean allowObjects)
See Also:
implementation

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


valueOf

static Boolean valueOf(boolean b)
Implementation of Boolean.valueOf for older VMs.


JNA API 3.2.7

Copyright © 2007-2010 Timothy Wall. All Rights Reserved.
 
 
Close
loading
Please Confirm
Close