ctypes python_ctypes --- Python 的外部函数库 — Python 3.7.9 文档

函数原型¶

外部函数也可通过实例化函数原型来创建。 函数原型类似于 C 中的函数原型；它们在不定义具体实现的情况下描述了一个函数（返回类型、参数类型、调用约定）。 工厂函数必须使用函数所需要的结果类型和参数类型来调用，并可被用作装饰器工厂函数，在此情况下可以通过 @wrapper 语法应用于函数。 请参阅 回调函数 了解有关示例。

ctypes.CFUNCTYPE(restype, *argtypes, use_errno=False, use_last_error=False)¶

The returned function prototype creates functions that use the standard C

calling convention. The function will release the GIL during the call. If

use_errno is set to true, the ctypes private copy of the system

errno variable is exchanged with the real errno value before

and after the call; use_last_error does the same for the Windows error

code.

ctypes.WINFUNCTYPE(restype, *argtypes, use_errno=False, use_last_error=False)¶

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. use_errno and use_last_error have the

same meaning as above.

ctypes.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 these 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 which must be an integer.

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 non-negative

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 one, two, or three items.

The first item is an integer containing a combination of direction

flags for the parameter:

1Specifies an input parameter to the function.

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

4Input 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 MessageBoxW function so

that it supports default parameters and named arguments. The C declaration from

the windows header file is this:

WINUSERAPI int WINAPI

MessageBoxW(

HWND hWnd,

LPCWSTR lpText,

LPCWSTR lpCaption,

UINT uType);

Here is the wrapping with ctypes:

>>>from ctypes import c_int, WINFUNCTYPE, windll

>>>from ctypes.wintypes import HWND, LPCWSTR, UINT

>>>prototype = WINFUNCTYPE(c_int, HWND, LPCWSTR, LPCWSTR, UINT)

>>>paramflags = (1, "hwnd", 0), (1, "text", "Hi"), (1, "caption", "Hello from ctypes"), (1, "flags", 0)

>>>MessageBox = prototype(("MessageBoxW", 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

>>>