A Foreign Function Interface call.
Libffi' assumes that you have a pointer to the function you wish to
call and that you know the number and types of arguments to pass it, as
well as the return type of the function.
The first thing you must do is create an ffi_cif object that matches
the signature of the function you wish to call. This is a separate step
because it is common to make multiple calls using a single ffi_cif. The
cif in ffi_cif stands for Call InterFace. To prepare a call interface
object, use the function ffi_prep_cif.
Build a FAST_ARRAY of STRINGs from a_pointer which must be of a
NULL-terminated array of C strings, that is a "char**" String
contents and array itself are copied.
Initializes Current call according to the given parameters.
Functions with variable number of arguments (also known as varargs) are not supported.
a_return_type must be a pointer to an ffi_type structure that describes the return type of the function. See FFI_TYPES.
some_argument_types contains the types of arguments. May be Void
FFI allows to use several different ABI conventions, but they are highly
platform-dependent. TODO: support different ABIs.
status is updated and will be either is_ok if everything worked
properly; is_bad__abi if the ABI is invalid (see above); its value may
be "FFI_BAD_TYPEDEF" if one of the arguments is incorrect; TODO: this
value should belong to FFI_STATUSENUM but currently it is not found in
the code.
require
a_function.is_not_null
a_return_type.is_not_null
some_argument_types /= Void implies not some_argument_types.is_empty
TODO: reactivate the following preconditions when they will not make the compiler produce wrong code anymore. Paolo 2010-03-19
is_valid_type(a_return_type)
some_argument_types=Void or else
some_argument_types.for_all(agent is_valid_type)
Note: someone may want to turn this into invariant Actually they
are right, it is an invariant. But since we do not offer a feature
to change function value we only need to check that this creation
feature correctly set it.
Calls function according to the description of Current.
a_result shall point to a chunk of memory that will hold the
result of the function call. This must be large enough to hold the
result and must be suitably aligned; it is the caller's
responsibility to ensure this. If Current declares that the function
returns void (using ffi_type_void), then a_result is ignored. If
a_result is NULL then the return value is discarded.
some_values shall point to a vector of "void *" pointers that
point to the memory locations holding the argument values for a
call. If Current declares that the function has no arguments (i.e.,
nargs was 0), then avalues is ignored.
TODO: reactivate the following preconditions when they will not make the compiler produce wrong code anymore. Paolo 2010-03-19
require
This exception occurs when Void is passed as the expression
to inspect ("inspect on STRING only).
This exception also occurs when the inspected value selects no branch (when the keyword "else"
not used, one "when" branch _must_ be selected). Some value which is not one of the inspect
constants, if there is no Else_part
f
Build a FAST_ARRAY of STRINGs from a_pointer which must be of a
NULL-terminated array of C strings, that is a "char**" String
contents and array itself are copied.