14.14.2.3 Foreign functions
As explained in the previous section, foreign functions can be
accessed as attributes of loaded shared libraries. The function
objects created in this way by default accept any number of arguments,
accept any ctypes data instances as arguments, and return the default
result type specified by the library loader. They are instances of a
private class:
- class _FuncPtr
-
Base class for C callable foreign functions.
Instances of foreign functions are also C compatible data types; they
represent C function pointers.
This behaviour can be customized by assigning to special attributes of
the foreign function object.
- restype
-
Assign a ctypes type to specify the result type of the foreign
function. Use
None for void a function not returning
anything.
It is possible to assign a callable Python object that is not a
ctypes type, in this case the function is assumed to return a
C int , and the callable will be called with this integer,
allowing to do further processing or error checking. Using this
is deprecated, for more flexible postprocessing or error checking
use a ctypes data type as restype and assign a callable to the
errcheck attribute.
- argtypes
-
Assign a tuple of ctypes types to specify the argument types that
the function accepts. Functions using the
stdcall calling
convention can only be called with the same number of arguments as
the length of this tuple; functions using the C calling convention
accept additional, unspecified arguments as well.
When a foreign function is called, each actual argument is passed
to the from_param class method of the items in the
argtypes tuple, this method allows to adapt the actual
argument to an object that the foreign function accepts. For
example, a c_char_p item in the argtypes tuple will
convert a unicode string passed as argument into an byte string
using ctypes conversion rules.
New: It is now possible to put items in argtypes which are not
ctypes types, but each item must have a from_param method
which returns a value usable as argument (integer, string, ctypes
instance). This allows to define adapters that can adapt custom
objects as function parameters.
- errcheck
-
Assign a Python function or another callable to this attribute.
The callable will be called with three or more arguments:
callable( |
result, func, arguments) |
-
result is what the foreign function returns, as specified by the
restype attribute.
func is the foreign function object itself, this allows to
reuse the same callable object to check or postprocess the results
of several functions.
arguments is a tuple containing the parameters originally
passed to the function call, this allows to specialize the
behaviour on the arguments used.
The object that this function returns will be returned from the
foreign function call, but it can also check the result value and
raise an exception if the foreign function call failed.
- exception ArgumentError()
-
This exception is raised when a foreign function call cannot
convert one of the passed arguments.
Release 2.5.2, documentation updated on 21st February, 2008.
See About this document... for information on suggesting changes.
|