Package com.sun.jna

Class 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
    • 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
      • 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
    • Constructor Detail

      • Function

        Function​(NativeLibrary library,
                 String functionName,
                 int callFlags,
                 String encoding)
        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
        encoding - 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 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
        encoding - Encoding for conversion between Java and native strings.
    • 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:
        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:
        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 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
        encoding - 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 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
      • getFunction

        public static Function getFunction​(Pointer p,
                                           int callFlags,
                                           String encoding)
        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
        encoding - 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 calling invoke(Class, Object[], Map), the method has to be in the options under key OPTION_INVOKING_METHOD.
      • invoke

        Object invoke​(Object[] args,
                      Class<?> returnType,
                      boolean allowObjects)
      • invoke

        Object invoke​(Object[] args,
                      Class<?> returnType,
                      boolean allowObjects,
                      int fixedArgs)
      • 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
      • 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
      • hashCode

        public int hashCode()
        Provide a unique hash code for Functions which are equivalent.
        Overrides:
        hashCode in class 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+.
      • 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.