Function (JNA API)

Overview | Package | Class | Tree | Deprecated | Index | Help
| JNA API 3.3.0
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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 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()`
`int` | `hashCode()` Provide a unique hash code for `Function`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 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
`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, 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.

### hashCode

    public int hashCode()

  Provide a unique hash code for `Function`s which are equivalent.

  Overrides:
    `hashCode` in class `Pointer`
  Returns:
    A hash code value for the represented native pointer

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

Overview | Package | Class | Tree | Deprecated | Index | Help
| JNA API 3.3.0
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2007-2010 Timothy Wall. All Rights Reserved.