Introduction
The xFunction library allows you to call external functions, implemented in any language and residing in DLLs or shared libraries, from your Java program. With xFunction, you do not need to implement native methods operating through Java Native Interface (JNI). Instead, you extend and instantiate xFunction classes to create conventional Java objects representing external functions, data structures, pointers, and callbacks. All necessary data conversions and external function calls are done seamlessly by the xFunction library:
import com.excelsior.xFunction;
...
/* call to Beep(1770,100) from KERNEL32.DLL */
xFunction f=new xFunction("kernel32", "int Beep(int,int)");
f.invoke(new Argument(1770),new Argument(100));
xFunction provides you with the following capabilities:
- calls of external functions from Java code
- calls of Java methods from external functions (callbacks)
- simulation of C-compatible structures
- simulation of pointers
- passing of input and output parameters of different types (primitive types, strings, structures, arrays, callbacks)
Note: The xFunction library is NOT intended for implementation of address arithmetic in Java.
New in version 2.17
- Added xFunction constructor which taked function address as int;
- Added Poniter.isNull() function.
The following bugs were fixed:
- Using null as an argument of type CSTRING* caused TypesDifferentException;
- Returning of big structures did not work.
New in version 2.16
- xFunction for Mac OS X is introduced;
- Windows-specific calling convention "cdecl" is supported.
The following bugs were fixed:
- Pointer.createArray() consumed a lot of memory and worked very slow on large arrays;
- From several instances of callbacks of the same class, only the first instance was invoked.
New in version 2.15
This is a maintenance release fixing the following problem:
- Creating a pointer to a pointer caused NullPointerException.
New in version 2.14
This is a maintenance release fixing the following problems:
- Conversion of non-ASCII characters from C char and char* (CSTRING) types to Java char and String did not work;
- Pointer.createArray() worked incorrectly if the base type was char or short;
- xFunction.invoke() returned null instead of an instance of the respective integer type wrapper if the external function was defined as returning an integer type and the returned value was zero. (This bug was introduced in v2.13.)
New in version 2.13
This is a maintenance release that addresses several customer issues.
New in version 2.12
- The Windows-specific string type BSTR is supported (see Class Argument.) According to Microsoft Platform SDK Documentation, “a BSTR, known as basic string or binary string, is a pointer to a wide character string used by OLE Automation data manipulation functions.”
- Bug fixed that was introduced in version 2.1 and made structure and callback names qualified with package names unrecognizable in signatures.
New in version 2.1
- Optional #pack() clauses in strings returned from implementations of Structure.defineLayout() allow you to specify alignment for native structure fields.
New in version 2.0
- The limit on the number of simultaneously existing callbacks removed;
- The method Callback.free() introduced for deallocation of the associated operating system resources.
Portability issues
If your Java program is truly portable, i.e. it does not contain native methods, you do need neither xFunction nor JNI or other native interface. Otherwise, it does not really matter whether you use xFunction or a native interface — you still need to port the native code part of your program.