14.14.2.4 Function prototypes

###
14.14.2.4 Function prototypes

Foreign functions can also be created by instantiating function prototypes. Function prototypes are similar to function prototypes in C; they describe a function (return type, argument types, calling convention) without defining an implementation. The factory functions must be called with the desired result type and the argument types of the function.

`CFUNCTYPE`( | restype, *argtypes)

  The returned function prototype creates functions that use the standard C calling convention. The function will release the GIL during the call.

`WINFUNCTYPE`( | restype, *argtypes)

  Windows only: The returned function prototype creates functions that use the `stdcall` calling convention, except on Windows CE where `WINFUNCTYPE` is the same as `CFUNCTYPE`. The function will release the GIL during the call.

`PYFUNCTYPE`( | restype, *argtypes)

  The returned function prototype creates functions that use the Python calling convention. The function will not release the GIL during the call.

Function prototypes created by the factory functions can be instantiated in different ways, depending on the type and number of the parameters in the call.

`prototype`( | address)

  Returns a foreign function at the specified address.

`prototype`( | callable)

  Create a C callable function (a callback function) from a Python `callable`.

`prototype`( | func_spec[, paramflags])

  Returns a foreign function exported by a shared library. `func_spec` must be a 2-tuple `(name_or_ordinal, library)`. The first item is the name of the exported function as string, or the ordinal of the exported function as small integer. The second item is the shared library instance.

`prototype`( | vtbl_index, name[, paramflags[, iid]])

  Returns a foreign function that will call a COM method. `vtbl_index` is the index into the virtual function table, a small nonnegative integer. name is name of the COM method. iid is an optional pointer to the interface identifier which is used in extended error reporting.

  COM methods use a special calling convention: They require a pointer to the COM interface as first argument, in addition to those parameters that are specified in the `argtypes` tuple.

The optional paramflags parameter creates foreign function wrappers with much more functionality than the features described above.

paramflags must be a tuple of the same length as `argtypes`.

Each item in this tuple contains further information about a parameter, it must be a tuple containing 1, 2, or 3 items.

The first item is an integer containing flags for the parameter:

`1`
  Specifies an input parameter to the function.

`2`
  Output parameter. The foreign function fills in a value.

`4`
  Input parameter which defaults to the integer zero.

The optional second item is the parameter name as string. If this is specified, the foreign function can be called with named parameters.

The optional third item is the default value for this parameter.

This example demonstrates how to wrap the Windows `MessageBoxA` function so that it supports default parameters and named arguments. The C declaration from the windows header file is this:

    WINUSERAPI int WINAPI
    MessageBoxA(
        HWND hWnd ,
        LPCSTR lpText,
        LPCSTR lpCaption,
        UINT uType);

Here is the wrapping with `ctypes`:

    >>> from ctypes import c_int, WINFUNCTYPE, windll
    >>> from ctypes.wintypes import HWND, LPCSTR, UINT
    >>> prototype = WINFUNCTYPE(c_int, HWND, LPCSTR, LPCSTR, UINT)
    >>> paramflags = (1, "hwnd", 0), (1, "text", "Hi"), (1, "caption", None), (1, "flags", 0)
    >>> MessageBox = prototype(("MessageBoxA", windll.user32), paramflags)
    >>>

The MessageBox foreign function can now be called in these ways:

    >>> MessageBox()
    >>> MessageBox(text="Spam, spam, spam")
    >>> MessageBox(flags=2, text="foo bar")
    >>>

A second example demonstrates output parameters. The win32 `GetWindowRect` function retrieves the dimensions of a specified window by copying them into `RECT` structure that the caller has to supply. Here is the C declaration:

    WINUSERAPI BOOL WINAPI
    GetWindowRect(
         HWND hWnd,
         LPRECT lpRect);

Here is the wrapping with `ctypes`:

    >>> from ctypes import POINTER, WINFUNCTYPE, windll, WinError
    >>> from ctypes.wintypes import BOOL, HWND, RECT
    >>> prototype = WINFUNCTYPE(BOOL, HWND, POINTER(RECT))
    >>> paramflags = (1, "hwnd"), (2, "lprect")
    >>> GetWindowRect = prototype(("GetWindowRect", windll.user32), paramflags)
    >>>

Functions with output parameters will automatically return the output parameter value if there is a single one, or a tuple containing the output parameter values when there are more than one, so the GetWindowRect function now returns a RECT instance, when called.

Output parameters can be combined with the `errcheck` protocol to do further output processing and error checking. The win32 `GetWindowRect` api function returns a `BOOL` to signal success or failure, so this function could do the error checking, and raises an exception when the api call failed:

    >>> def errcheck(result, func, args):
    ...     if not result:
    ...         raise WinError()
    ...     return args
    >>> GetWindowRect.errcheck = errcheck
    >>>

If the `errcheck` function returns the argument tuple it receives unchanged, `ctypes` continues the normal processing it does on the output parameters. If you want to return a tuple of window coordinates instead of a `RECT` instance, you can retrieve the fields in the function and return them instead, the normal processing will no longer take place:

    >>> def errcheck(result, func, args):
    ...     if not result:
    ...         raise WinError()
    ...     rc = args[1]
    ...     return rc.left, rc.top, rc.bottom, rc.right
    >>>
    >>> GetWindowRect.errcheck = errcheck
    >>>