ffi module provides an interface to dynamically loaded libraries (DLLs) written and compiled from other languages, allowing you to extend the functionality of DOME.
You do this by first declaring the API that the functions within the DLL expect, and then calling it appropriately.
This module depends on
libffi and is considered optional, so it is only included if DOME is built using
DOME_OPT_FFI=1 when running
Accessing methods using this module is a very low level operation, and comes with certain caveats:
Types are referred to as a string of the C type, except for “pointer” and the names of user-defined structs.
It contains the following classes:
static load(shortName: String, libraryName: String): Library
libraryName which is valid and on the path in your execution environment, DOME will load that DLL for future use,
and return you a Library object representing it. It will be assigned the given
shortName, for future retrieval if necessary.
static get(shortName: String): Library
If a library was loaded with the given
shortName, return it. This is useful for retrieving previously loaded library.
static unload(shortName: String): Void
shortNameed DLL. After this, all functions within that library are inaccessible and invalidated.
bind(fnName: String, retType: String, paramTypeList: String)): Void
This defines a function named
fnName which returns a value of
retType and is called with parameters in order of
call(fnName: String, params: Any): Any
Calls the function
fnName with the parameters in the
There is minimal type checking performed here, and you are responsible for passing in the correct types.
static declare(typeName: String, fieldTypeList: String): StructType
Defines a structType which can be passed to functions in a library.
static init(typeName: String, params: Any): Struct
Initialises a struct with the given parameters, ready to be passed to a function.
getValue(index: Number): Any
Retrieves the value held in the field at the given index.
This represents a pointer to a block of contiguous memory. It can be returned by a function or reference memory reserved by
reserve(bytes: Number): Pointer
bytes of memory and return a pointer to it. This pointer can be freed by calling
Frees memory reserved by
Treats the pointer as a C-String so it will return all bytes until a null-terminator.
asBytes(size: Number): String
Treats the pointer as an array of bytes and returns as many bytes as expected.