Callback functions
~~~~~~~~~~~~~~~~~~

ctypes is able to create C callable functions from Python callables.
This is useful because sometimes library functions need a callback
function parameter; the ``qsort`` C function is such an example.

Callback functions are created by first creating a function prototype
with a call to ``CFUNCTYPE`` or ``WINFUNCTYPE``, specifying the return
type and the argument types that the callback function will receive.

Calling the prototype with a single Python callable will create and
return a C-callable function pointer or callback function.  Note that
this allows using prototypes as decorators creating callback
functions (Windows example)::

    @WINFUNCTYPE(BOOL, HWND, LPARAM)
    def enumwindowsproc(hwnd, lParam):
        ....
        return True

When a Python exception is raised in the Python callable, the return
value of the C callable function is undefined.

Important note: You must keep a reference to the callback AS LONG as
foreign code will call it!  Segfaults will result if the callback is
cleaned up by Python's garbage collector and external code then
tries to call it.

Callback objects can also be called from Python - this may be useful
for debugging.