ctypes
- Python 的外部函数库¶
源代码: Lib/ctypes
ctypes
是 Python 的外部函数库。它提供了与 C 兼容的数据类型,并允许调用 DLL 或共享库中的函数。它可以用来用纯 Python 包装这些库。
ctypes 教程¶
注意:本教程中的代码示例使用 doctest
来确保它们确实有效。由于某些代码示例在 Linux、Windows 或 macOS 下的行为不同,因此它们在注释中包含 doctest 指令。
注意:一些代码示例引用了 ctypes c_int
类型。在 sizeof(long) == sizeof(int)
的平台上,它是 c_long
的别名。因此,如果您期望看到 c_int
但却打印出 c_long
,请不要感到困惑 - 它们实际上是同一类型。
加载动态链接库¶
ctypes
导出 cdll 对象,在 Windows 上还导出 windll 和 oledll 对象,用于加载动态链接库。
您可以通过将库作为这些对象的属性访问来加载它们。cdll 加载使用标准 cdecl
调用约定导出函数的库,而 windll 加载使用 stdcall
调用约定调用函数的库。oledll 也使用 stdcall
调用约定,并假定函数返回 Windows HRESULT
错误代码。错误代码用于在函数调用失败时自动引发 OSError
异常。
在 3.3 版更改: Windows 错误过去引发 WindowsError
,现在它是 OSError
的别名。
以下是一些 Windows 示例。请注意,msvcrt
是包含大多数标准 C 函数的 MS 标准 C 库,它使用 cdecl 调用约定
>>> from ctypes import *
>>> print(windll.kernel32)
<WinDLL 'kernel32', handle ... at ...>
>>> print(cdll.msvcrt)
<CDLL 'msvcrt', handle ... at ...>
>>> libc = cdll.msvcrt
>>>
Windows 会自动追加通常的 .dll
文件后缀。
注意
通过 cdll.msvcrt
访问标准 C 库将使用该库的过时版本,该版本可能与 Python 使用的版本不兼容。如果可能,请使用原生 Python 功能,或者导入并使用 msvcrt
模块。
在 Linux 上,需要指定*包含*扩展名的文件名才能加载库,因此不能使用属性访问来加载库。应该使用 dll 加载器的 LoadLibrary()
方法,或者应该通过调用构造函数创建 CDLL 的实例来加载库
>>> cdll.LoadLibrary("libc.so.6")
<CDLL 'libc.so.6', handle ... at ...>
>>> libc = CDLL("libc.so.6")
>>> libc
<CDLL 'libc.so.6', handle ... at ...>
>>>
访问已加载 dll 中的函数¶
函数作为 dll 对象的属性访问
>>> libc.printf
<_FuncPtr object at 0x...>
>>> print(windll.kernel32.GetModuleHandleA)
<_FuncPtr object at 0x...>
>>> print(windll.kernel32.MyOwnFunction)
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
File "ctypes.py", line 239, in __getattr__
func = _StdcallFuncPtr(name, self)
AttributeError: function 'MyOwnFunction' not found
>>>
请注意,像 kernel32
和 user32
这样的 win32 系统 dll 通常会导出函数的 ANSI 和 UNICODE 版本。UNICODE 版本的名称后面会附加一个 W
,而 ANSI 版本的名称后面会附加一个 A
。win32 GetModuleHandle
函数返回给定模块名称的*模块句柄*,它具有以下 C 原型,并使用宏根据是否定义了 UNICODE 来将其中一个公开为 GetModuleHandle
/* ANSI version */
HMODULE GetModuleHandleA(LPCSTR lpModuleName);
/* UNICODE version */
HMODULE GetModuleHandleW(LPCWSTR lpModuleName);
windll 不会尝试神奇地选择其中一个,您必须通过显式指定 GetModuleHandleA
或 GetModuleHandleW
来访问您需要的版本,然后分别使用字节或字符串对象调用它。
有时,dll 导出的函数名称不是有效的 Python 标识符,例如 "??2@YAPAXI@Z"
。在这种情况下,您必须使用 getattr()
来检索函数
>>> getattr(cdll.msvcrt, "??2@YAPAXI@Z")
<_FuncPtr object at 0x...>
>>>
在 Windows 上,某些 dll 不是按名称而是按序号导出函数。可以通过使用序号索引 dll 对象来访问这些函数
>>> cdll.kernel32[1]
<_FuncPtr object at 0x...>
>>> cdll.kernel32[0]
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
File "ctypes.py", line 310, in __getitem__
func = _StdcallFuncPtr(name, self)
AttributeError: function ordinal 0 not found
>>>
调用函数¶
您可以像调用任何其他 Python 可调用对象一样调用这些函数。此示例使用 rand()
函数,该函数不带参数并返回一个伪随机整数
>>> print(libc.rand())
1804289383
在 Windows 上,您可以调用 GetModuleHandleA()
函数,该函数返回一个 win32 模块句柄(传递 None
作为单个参数以使用 NULL
指针调用它)
>>> print(hex(windll.kernel32.GetModuleHandleA(None)))
0x1d000000
>>>
当您使用 cdecl
调用约定调用 stdcall
函数时,或者反之亦然,会引发 ValueError
>>> cdll.kernel32.GetModuleHandleA(None)
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
ValueError: Procedure probably called with not enough arguments (4 bytes missing)
>>>
>>> windll.msvcrt.printf(b"spam")
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
ValueError: Procedure probably called with too many arguments (4 bytes in excess)
>>>
要找出正确的调用约定,您必须查看要调用的函数的 C 头文件或文档。
在 Windows 上,ctypes
使用 win32 结构化异常处理来防止在使用无效参数值调用函数时出现一般保护错误导致崩溃
>>> windll.kernel32.GetModuleHandleA(32)
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
OSError: exception: access violation reading 0x00000020
>>>
但是,使用 ctypes
仍然有很多方法可以让 Python 崩溃,因此您无论如何都应该小心。faulthandler
模块可以帮助调试崩溃(例如,由错误的 C 库调用产生的段错误)。
None
、整数、字节对象和(unicode)字符串是唯一可以直接用作这些函数调用中的参数的原生 Python 对象。None
作为 C NULL
指针传递,字节对象和字符串作为指向包含其数据的内存块的指针传递(char* 或 wchar_t*)。Python 整数作为平台默认的 C int 类型传递,它们的值会被屏蔽以适应 C 类型。
在我们继续调用具有其他参数类型的函数之前,我们必须了解更多关于 ctypes
数据类型的知识。
基本数据类型¶
ctypes
定义了许多与 C 兼容的原始数据类型
ctypes 类型 |
C 类型 |
Python 类型 |
---|---|---|
_Bool |
bool (1) |
|
char |
1 个字符的字节对象 |
|
|
1 个字符的字符串 |
|
char |
int |
|
unsigned char |
int |
|
short |
int |
|
unsigned short |
int |
|
int |
int |
|
unsigned int |
int |
|
long |
int |
|
unsigned long |
int |
|
__int64 或 long long |
int |
|
unsigned __int64 或 unsigned long long |
int |
|
|
int |
|
|
int |
|
|
int |
|
float |
float |
|
double |
float |
|
long double |
float |
|
char*(以 NUL 结尾) |
字节对象或 |
|
wchar_t*(以 NUL 结尾) |
字符串或 |
|
void* |
int 或 |
构造函数接受任何具有真值的 Python 对象。
所有这些类型都可以通过使用正确类型和值的可选初始化器调用它们来创建
>>> c_int()
c_long(0)
>>> c_wchar_p("Hello, World")
c_wchar_p(140018365411392)
>>> c_ushort(-3)
c_ushort(65533)
>>>
由于这些类型是可变的,因此它们的值也可以在之后更改
>>> i = c_int(42)
>>> print(i)
c_long(42)
>>> print(i.value)
42
>>> i.value = -99
>>> print(i.value)
-99
>>>
将新值赋给指针类型 c_char_p
、c_wchar_p
和 c_void_p
的实例会更改它们指向的*内存位置*,而*不会更改*内存块的*内容*(当然不会,因为 Python 字节对象是不可变的)
>>> s = "Hello, World"
>>> c_s = c_wchar_p(s)
>>> print(c_s)
c_wchar_p(139966785747344)
>>> print(c_s.value)
Hello World
>>> c_s.value = "Hi, there"
>>> print(c_s) # the memory location has changed
c_wchar_p(139966783348904)
>>> print(c_s.value)
Hi, there
>>> print(s) # first object is unchanged
Hello, World
>>>
但是,您应该小心,不要将它们传递给期望指向可变内存的指针的函数。如果您需要可变内存块,ctypes 有一个 create_string_buffer()
函数,它可以通过各种方式创建这些内存块。可以使用 raw
属性访问(或更改)当前内存块内容;如果要将其作为以 NUL 结尾的字符串访问,请使用 value
属性
>>> from ctypes import *
>>> p = create_string_buffer(3) # create a 3 byte buffer, initialized to NUL bytes
>>> print(sizeof(p), repr(p.raw))
3 b'\x00\x00\x00'
>>> p = create_string_buffer(b"Hello") # create a buffer containing a NUL terminated string
>>> print(sizeof(p), repr(p.raw))
6 b'Hello\x00'
>>> print(repr(p.value))
b'Hello'
>>> p = create_string_buffer(b"Hello", 10) # create a 10 byte buffer
>>> print(sizeof(p), repr(p.raw))
10 b'Hello\x00\x00\x00\x00\x00'
>>> p.value = b"Hi"
>>> print(sizeof(p), repr(p.raw))
10 b'Hi\x00lo\x00\x00\x00\x00\x00'
>>>
create_string_buffer()
函数取代了旧的 c_buffer()
函数(该函数仍然可用作别名)。要创建一个包含 C 类型 wchar_t
的 unicode 字符的可变内存块,请使用 create_unicode_buffer()
函数。
调用函数(续)¶
请注意,printf 打印到真实的标准输出通道,而*不是* sys.stdout
,因此这些示例只能在控制台提示符下工作,而不能在 *IDLE* 或 *PythonWin* 中工作
>>> printf = libc.printf
>>> printf(b"Hello, %s\n", b"World!")
Hello, World!
14
>>> printf(b"Hello, %S\n", "World!")
Hello, World!
14
>>> printf(b"%d bottles of beer\n", 42)
42 bottles of beer
19
>>> printf(b"%f bottles of beer\n", 42.5)
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
ArgumentError: argument 2: TypeError: Don't know how to convert parameter 2
>>>
如前所述,除整数、字符串和字节对象之外的所有 Python 类型都必须包装在相应的 ctypes
类型中,以便可以将它们转换为所需的 C 数据类型
>>> printf(b"An int %d, a double %f\n", 1234, c_double(3.14))
An int 1234, a double 3.140000
31
>>>
调用可变参数函数¶
在许多平台上,通过 ctypes 调用可变参数函数与调用具有固定数量参数的函数完全相同。在某些平台上,特别是 Apple 平台的 ARM64,可变参数函数的调用约定与常规函数的调用约定不同。
在这些平台上,需要为常规的、非可变参数的函数参数指定 argtypes
属性
libc.printf.argtypes = [ctypes.c_char_p]
因为指定该属性不会抑制可移植性,所以建议始终为所有可变参数函数指定 argtypes
。
使用您自己的自定义数据类型调用函数¶
您还可以自定义 ctypes
参数转换,以允许您自己的类的实例用作函数参数。 ctypes
会查找 _as_parameter_
属性,并将其用作函数参数。 该属性必须是整数、字符串、字节串、ctypes
实例或具有 _as_parameter_
属性的对象。
>>> class Bottles:
... def __init__(self, number):
... self._as_parameter_ = number
...
>>> bottles = Bottles(42)
>>> printf(b"%d bottles of beer\n", bottles)
42 bottles of beer
19
>>>
如果您不想将实例的数据存储在 _as_parameter_
实例变量中,则可以定义一个 property
,以便在需要时提供该属性。
指定所需的参数类型(函数原型)¶
可以通过设置 argtypes
属性来指定从 DLL 导出的函数所需的的参数类型。
argtypes
必须是 C 数据类型的序列(printf()
函数可能不是一个很好的例子,因为它根据格式字符串接受可变数量和不同类型的参数,但另一方面,这对于试验此功能非常方便)。
>>> printf.argtypes = [c_char_p, c_char_p, c_int, c_double]
>>> printf(b"String '%s', Int %d, Double %f\n", b"Hi", 10, 2.2)
String 'Hi', Int 10, Double 2.200000
37
>>>
指定格式可以防止不兼容的参数类型(就像 C 函数的原型一样),并尝试将参数转换为有效的类型。
>>> printf(b"%d %d %d", 1, 2, 3)
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
ArgumentError: argument 2: TypeError: wrong type
>>> printf(b"%s %d %f\n", b"X", 2, 3)
X 2 3.000000
13
>>>
如果您定义了自己的类并将其传递给函数调用,则必须为它们实现 from_param()
类方法,以便能够在 argtypes
序列中使用它们。 from_param()
类方法接收传递给函数调用的 Python 对象,它应该进行类型检查或任何必要的检查以确保此对象是可接受的,然后返回对象本身、其 _as_parameter_
属性,或者您想在这种情况下作为 C 函数参数传递的任何内容。 同样,结果应该是一个整数、字符串、字节串、ctypes
实例或具有 _as_parameter_
属性的对象。
返回类型¶
默认情况下,假定函数返回 C int 类型。可以通过设置函数对象的 restype
属性来指定其他返回类型。
time()
的 C 原型是 time_t time(time_t *)
。因为 time_t
的类型可能与默认返回类型 int 不同,所以您应该指定 restype
属性。
>>> libc.time.restype = c_time_t
可以使用 argtypes
指定参数类型。
>>> libc.time.argtypes = (POINTER(c_time_t),)
要使用 NULL
指针作为第一个参数调用函数,请使用 None
。
>>> print(libc.time(None))
1150640792
下面是一个更高级的示例,它使用了 strchr()
函数,该函数需要一个字符串指针和一个字符,并返回一个指向字符串的指针。
>>> strchr = libc.strchr
>>> strchr(b"abcdef", ord("d"))
8059983
>>> strchr.restype = c_char_p # c_char_p is a pointer to a string
>>> strchr(b"abcdef", ord("d"))
b'def'
>>> print(strchr(b"abcdef", ord("x")))
None
>>>
如果您想避免上面的 ord("x")
调用,可以设置 argtypes
属性,第二个参数将从单个字符的 Python 字节串对象转换为 C 字符。
>>> strchr.restype = c_char_p
>>> strchr.argtypes = [c_char_p, c_char]
>>> strchr(b"abcdef", b"d")
b'def'
>>> strchr(b"abcdef", b"def")
Traceback (most recent call last):
ctypes.ArgumentError: argument 2: TypeError: one character bytes, bytearray or integer expected
>>> print(strchr(b"abcdef", b"x"))
None
>>> strchr(b"abcdef", b"d")
b'def'
>>>
如果外部函数返回一个整数,您还可以使用可调用的 Python 对象(例如函数或类)作为 restype
属性。将使用 C 函数返回的 *整数* 调用可调用对象,并且此调用的结果将用作函数调用的结果。这对于检查错误返回值和自动引发异常非常有用。
>>> GetModuleHandle = windll.kernel32.GetModuleHandleA
>>> def ValidHandle(value):
... if value == 0:
... raise WinError()
... return value
...
>>>
>>> GetModuleHandle.restype = ValidHandle
>>> GetModuleHandle(None)
486539264
>>> GetModuleHandle("something silly")
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
File "<stdin>", line 3, in ValidHandle
OSError: [Errno 126] The specified module could not be found.
>>>
WinError
是一个函数,它将调用 Windows FormatMessage()
API 来获取错误代码的字符串表示形式,并 *返回* 一个异常。 如果没有使用错误代码参数,WinError
会调用 GetLastError()
来检索它。
请注意,可以通过 errcheck
属性获得更强大的错误检查机制;有关详细信息,请参阅参考手册。
传递指针(或:通过引用传递参数)¶
有时,C API 函数需要一个指向数据类型的 *指针* 作为参数,可能是为了写入相应的位置,或者如果数据太大而无法按值传递。这也称为 *通过引用传递参数*。
ctypes
导出 byref()
函数,该函数用于通过引用传递参数。可以使用 pointer()
函数实现相同的效果,尽管 pointer()
会做更多工作,因为它构造了一个真正的指针对象,所以如果您不需要在 Python 本身中使用指针对象,则使用 byref()
会更快。
>>> i = c_int()
>>> f = c_float()
>>> s = create_string_buffer(b'\000' * 32)
>>> print(i.value, f.value, repr(s.value))
0 0.0 b''
>>> libc.sscanf(b"1 3.14 Hello", b"%d %f %s",
... byref(i), byref(f), s)
3
>>> print(i.value, f.value, repr(s.value))
1 3.1400001049 b'Hello'
>>>
结构体和联合体¶
结构体和联合体必须从 Structure
和 Union
基类派生,这些基类在 ctypes
模块中定义。每个子类都必须定义一个 _fields_
属性。 _fields_
必须是一个 *2 元组* 的列表,包含 *字段名称* 和 *字段类型*。
字段类型必须是 ctypes
类型,例如 c_int
,或任何其他派生的 ctypes
类型:结构体、联合体、数组、指针。
下面是一个 POINT 结构体的简单示例,它包含两个名为 *x* 和 *y* 的整数,还展示了如何在构造函数中初始化结构体。
>>> from ctypes import *
>>> class POINT(Structure):
... _fields_ = [("x", c_int),
... ("y", c_int)]
...
>>> point = POINT(10, 20)
>>> print(point.x, point.y)
10 20
>>> point = POINT(y=5)
>>> print(point.x, point.y)
0 5
>>> POINT(1, 2, 3)
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
TypeError: too many initializers
>>>
但是,您可以构建更复杂的结构体。结构体本身可以通过使用结构体作为字段类型来包含其他结构体。
下面是一个 RECT 结构体,它包含两个名为 *upperleft* 和 *lowerright* 的 POINT。
>>> class RECT(Structure):
... _fields_ = [("upperleft", POINT),
... ("lowerright", POINT)]
...
>>> rc = RECT(point)
>>> print(rc.upperleft.x, rc.upperleft.y)
0 5
>>> print(rc.lowerright.x, rc.lowerright.y)
0 0
>>>
嵌套结构体也可以在构造函数中以多种方式初始化。
>>> r = RECT(POINT(1, 2), POINT(3, 4))
>>> r = RECT((1, 2), (3, 4))
可以从类中检索字段描述符,它们对于调试非常有用,因为它们可以提供有用的信息。
>>> print(POINT.x)
<Field type=c_long, ofs=0, size=4>
>>> print(POINT.y)
<Field type=c_long, ofs=4, size=4>
>>>
警告
ctypes
不支持按值将联合或带有位域的结构传递给函数。虽然这在 32 位 x86 上可能有效,但库不能保证在一般情况下有效。联合和带有位域的结构应始终通过指针传递给函数。
结构/联合对齐和字节顺序¶
默认情况下,结构和联合字段的对其方式与 C 编译器相同。可以通过在子类定义中指定 _pack_
类属性来覆盖此行为。这必须设置为正整数,并指定字段的最大对齐方式。这也是 #pragma pack(n)
在 MSVC 中的作用。
ctypes
对结构和联合使用本地字节顺序。要构建具有非本地字节顺序的结构,可以使用 BigEndianStructure
、LittleEndianStructure
、BigEndianUnion
和 LittleEndianUnion
基类之一。这些类不能包含指针字段。
结构和联合中的位域¶
可以创建包含位域的结构和联合。位域仅适用于整数字段,位宽在 _fields_
元组中指定为第三项。
>>> class Int(Structure):
... _fields_ = [("first_16", c_int, 16),
... ("second_16", c_int, 16)]
...
>>> print(Int.first_16)
<Field type=c_long, ofs=0:0, bits=16>
>>> print(Int.second_16)
<Field type=c_long, ofs=0:16, bits=16>
>>>
数组¶
数组是序列,包含固定数量的相同类型的实例。
创建数组类型的推荐方法是将数据类型乘以一个正整数。
TenPointsArrayType = POINT * 10
下面是一个有点人为的数据类型的例子,一个结构包含 4 个 POINT 和其他东西。
>>> from ctypes import *
>>> class POINT(Structure):
... _fields_ = ("x", c_int), ("y", c_int)
...
>>> class MyStruct(Structure):
... _fields_ = [("a", c_int),
... ("b", c_float),
... ("point_array", POINT * 4)]
>>>
>>> print(len(MyStruct().point_array))
4
>>>
实例的创建方式与通常一样,通过调用类。
arr = TenPointsArrayType()
for pt in arr:
print(pt.x, pt.y)
上面的代码打印了一系列 0 0
行,因为数组内容被初始化为零。
也可以指定正确类型的初始化器。
>>> from ctypes import *
>>> TenIntegers = c_int * 10
>>> ii = TenIntegers(1, 2, 3, 4, 5, 6, 7, 8, 9, 10)
>>> print(ii)
<c_long_Array_10 object at 0x...>
>>> for i in ii: print(i, end=" ")
...
1 2 3 4 5 6 7 8 9 10
>>>
指针¶
指针实例是通过在 ctypes
类型上调用 pointer()
函数创建的。
>>> from ctypes import *
>>> i = c_int(42)
>>> pi = pointer(i)
>>>
指针实例有一个 contents
属性,它返回指针指向的对象,即上面的 i
对象。
>>> pi.contents
c_long(42)
>>>
请注意,ctypes
没有 OOR(原始对象返回),它每次检索属性时都会构造一个新的、等效的对象。
>>> pi.contents is i
False
>>> pi.contents is pi.contents
False
>>>
将另一个 c_int
实例分配给指针的 contents 属性将导致指针指向存储此实例的内存位置。
>>> i = c_int(99)
>>> pi.contents = i
>>> pi.contents
c_long(99)
>>>
指针实例也可以使用整数索引。
>>> pi[0]
99
>>>
分配给整数索引会更改指向的值。
>>> print(i)
c_long(99)
>>> pi[0] = 22
>>> print(i)
c_long(22)
>>>
也可以使用不同于 0 的索引,但您必须知道自己在做什么,就像在 C 中一样:您可以访问或更改任意内存位置。通常,只有当您从 C 函数接收到一个指针,并且您*知道*该指针实际上指向一个数组而不是单个项目时,才会使用此功能。
在幕后,pointer()
函数不仅仅是创建指针实例,它首先必须创建指针*类型*。这是通过 POINTER()
函数完成的,该函数接受任何 ctypes
类型,并返回一个新类型。
>>> PI = POINTER(c_int)
>>> PI
<class 'ctypes.LP_c_long'>
>>> PI(42)
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
TypeError: expected c_long instead of int
>>> PI(c_int(42))
<ctypes.LP_c_long object at 0x...>
>>>
调用不带参数的指针类型会创建一个 NULL
指针。NULL
指针的布尔值为 False
。
>>> null_ptr = POINTER(c_int)()
>>> print(bool(null_ptr))
False
>>>
ctypes
在解引用指针时会检查 NULL
(但解引用无效的非 NULL
指针会导致 Python 崩溃)。
>>> null_ptr[0]
Traceback (most recent call last):
....
ValueError: NULL pointer access
>>>
>>> null_ptr[0] = 1234
Traceback (most recent call last):
....
ValueError: NULL pointer access
>>>
类型转换¶
通常,ctypes 会进行严格的类型检查。这意味着,如果您在函数的 argtypes
列表中或结构定义中成员字段的类型为 POINTER(c_int)
,则只接受完全相同类型的实例。此规则有一些例外情况,ctypes 接受其他对象。例如,您可以传递兼容的数组实例而不是指针类型。因此,对于 POINTER(c_int)
,ctypes 接受一个 c_int 数组。
>>> class Bar(Structure):
... _fields_ = [("count", c_int), ("values", POINTER(c_int))]
...
>>> bar = Bar()
>>> bar.values = (c_int * 3)(1, 2, 3)
>>> bar.count = 3
>>> for i in range(bar.count):
... print(bar.values[i])
...
1
2
3
>>>
此外,如果在 argtypes
中将函数参数显式声明为指针类型(例如 POINTER(c_int)
),则可以将指向类型的对象(在本例中为 c_int
)传递给函数。在这种情况下,ctypes 将自动应用所需的 byref()
转换。
要将 POINTER 类型字段设置为 NULL
,可以分配 None
。
>>> bar.values = None
>>>
有时您会遇到不兼容类型的实例。在 C 中,您可以将一种类型转换为另一种类型。ctypes
提供了一个 cast()
函数,可以以相同的方式使用。上面定义的 Bar
结构接受 POINTER(c_int)
指针或 c_int
数组作为其 values
字段,但不接受其他类型的实例。
>>> bar.values = (c_byte * 4)()
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
TypeError: incompatible types, c_byte_Array_4 instance instead of LP_c_long instance
>>>
对于这些情况,cast()
函数非常方便。
cast()
函数可用于将 ctypes 实例转换为指向不同 ctypes 数据类型的指针。cast()
接受两个参数,一个是可以转换为某种指针的 ctypes 对象,以及一个 ctypes 指针类型。它返回第二个参数的实例,该实例引用与第一个参数相同的内存块。
>>> a = (c_byte * 4)()
>>> cast(a, POINTER(c_int))
<ctypes.LP_c_long object at ...>
>>>
因此,cast()
可用于为 Bar
结构的 values
字段赋值。
>>> bar = Bar()
>>> bar.values = cast((c_byte * 4)(), POINTER(c_int))
>>> print(bar.values[0])
0
>>>
不完整类型¶
不完整类型是指其成员尚未指定的结构体、联合体或数组。在 C 语言中,它们由前向声明指定,并在稍后定义。
struct cell; /* forward declaration */
struct cell {
char *name;
struct cell *next;
};
直接翻译成 ctypes 代码是这样的,但它不起作用。
>>> class cell(Structure):
... _fields_ = [("name", c_char_p),
... ("next", POINTER(cell))]
...
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
File "<stdin>", line 2, in cell
NameError: name 'cell' is not defined
>>>
因为新的 class cell
在类声明本身中不可用。在 ctypes
中,我们可以定义 cell
类并在类声明之后设置 _fields_
属性。
>>> from ctypes import *
>>> class cell(Structure):
... pass
...
>>> cell._fields_ = [("name", c_char_p),
... ("next", POINTER(cell))]
>>>
让我们试试看。我们创建两个 cell
的实例,让它们互相指向,最后沿着指针链走几步。
>>> c1 = cell()
>>> c1.name = b"foo"
>>> c2 = cell()
>>> c2.name = b"bar"
>>> c1.next = pointer(c2)
>>> c2.next = pointer(c1)
>>> p = c1
>>> for i in range(8):
... print(p.name, end=" ")
... p = p.next[0]
...
foo bar foo bar foo bar foo bar
>>>
回调函数¶
ctypes
允许从 Python 可调用对象创建 C 可调用函数指针。这些有时被称为*回调函数*。
首先,您必须为回调函数创建一个类。该类知道调用约定、返回类型以及此函数将接收的参数的数量和类型。
CFUNCTYPE()
工厂函数使用 cdecl
调用约定为回调函数创建类型。在 Windows 上,WINFUNCTYPE()
工厂函数使用 stdcall
调用约定为回调函数创建类型。
这两个工厂函数的调用方式都是将结果类型作为第一个参数,将回调函数预期的参数类型作为其余参数。
我将在这里展示一个使用标准 C 库的 qsort()
函数的示例,该函数用于借助回调函数对项目进行排序。qsort()
将用于对整数数组进行排序。
>>> IntArray5 = c_int * 5
>>> ia = IntArray5(5, 1, 7, 33, 99)
>>> qsort = libc.qsort
>>> qsort.restype = None
>>>
qsort()
必须使用指向要排序的数据的指针、数据数组中的项目数、一个项目的大小以及指向比较函数(回调)的指针来调用。然后将使用指向项目的两个指针调用回调,如果第一个项目小于第二个项目,则它必须返回一个负整数;如果它们相等,则返回零;否则返回一个正整数。
因此,我们的回调函数接收指向整数的指针,并且必须返回一个整数。首先,我们为回调函数创建 type
。
>>> CMPFUNC = CFUNCTYPE(c_int, POINTER(c_int), POINTER(c_int))
>>>
首先,这是一个简单的回调,它显示了传递给它的值。
>>> def py_cmp_func(a, b):
... print("py_cmp_func", a[0], b[0])
... return 0
...
>>> cmp_func = CMPFUNC(py_cmp_func)
>>>
结果
>>> qsort(ia, len(ia), sizeof(c_int), cmp_func)
py_cmp_func 5 1
py_cmp_func 33 99
py_cmp_func 7 33
py_cmp_func 5 7
py_cmp_func 1 7
>>>
现在我们可以实际比较这两个项目并返回一个有用的结果。
>>> def py_cmp_func(a, b):
... print("py_cmp_func", a[0], b[0])
... return a[0] - b[0]
...
>>>
>>> qsort(ia, len(ia), sizeof(c_int), CMPFUNC(py_cmp_func))
py_cmp_func 5 1
py_cmp_func 33 99
py_cmp_func 7 33
py_cmp_func 1 7
py_cmp_func 5 7
>>>
我们可以很容易地检查,我们的数组现在已经排序了。
>>> for i in ia: print(i, end=" ")
...
1 5 7 33 99
>>>
函数工厂可以用作装饰器工厂,因此我们也可以这样写。
>>> @CFUNCTYPE(c_int, POINTER(c_int), POINTER(c_int))
... def py_cmp_func(a, b):
... print("py_cmp_func", a[0], b[0])
... return a[0] - b[0]
...
>>> qsort(ia, len(ia), sizeof(c_int), py_cmp_func)
py_cmp_func 5 1
py_cmp_func 33 99
py_cmp_func 7 33
py_cmp_func 1 7
py_cmp_func 5 7
>>>
注意
确保只要从 C 代码中使用 CFUNCTYPE()
对象,就保留对它们的引用。ctypes
不会这样做,如果您不这样做,它们可能会被垃圾回收,从而在进行回调时导致程序崩溃。
此外,请注意,如果在 Python 控制之外创建的线程中调用回调函数(例如,通过调用回调的外部代码),则 ctypes 会在每次调用时创建一个新的虚拟 Python 线程。这种行为在大多数情况下都是正确的,但这意味着使用 threading.local
存储的值在不同的回调之间将*不会*保留,即使这些调用是从同一个 C 线程进行的。
访问从 DLL 导出的值¶
一些共享库不仅导出函数,还导出变量。Python 库本身中的一个例子是 Py_Version
,它是编码在单个常量整数中的 Python 运行时版本号。
ctypes
可以使用该类型的 in_dll()
类方法访问此类值。*pythonapi* 是一个预定义的符号,用于访问 Python C api。
>>> version = ctypes.c_int.in_dll(ctypes.pythonapi, "Py_Version")
>>> print(hex(version.value))
0x30c00a0
一个扩展示例还演示了指针的使用,它访问了 Python 导出的 PyImport_FrozenModules
指针。
引用该值的文档
此指针初始化为指向一个
_frozen
记录数组,该数组以一个所有成员均为NULL
或零的记录结尾。当导入冻结模块时,将在此表中搜索它。第三方代码可以利用这一点来提供动态创建的冻结模块集合。
因此,操作此指针甚至可能被证明是有用的。为了限制示例的大小,我们仅展示如何使用 ctypes
读取此表。
>>> from ctypes import *
>>>
>>> class struct_frozen(Structure):
... _fields_ = [("name", c_char_p),
... ("code", POINTER(c_ubyte)),
... ("size", c_int),
... ("get_code", POINTER(c_ubyte)), # Function pointer
... ]
...
>>>
我们已经定义了 _frozen
数据类型,因此我们可以获取指向该表的指针。
>>> FrozenTable = POINTER(struct_frozen)
>>> table = FrozenTable.in_dll(pythonapi, "_PyImport_FrozenBootstrap")
>>>
由于 table
是指向 struct_frozen
记录数组的 pointer
,因此我们可以对其进行迭代,但我们必须确保循环终止,因为指针没有大小。迟早它可能会因访问冲突或其他原因而崩溃,因此最好在我们遇到 NULL
条目时跳出循环。
>>> for item in table:
... if item.name is None:
... break
... print(item.name.decode("ascii"), item.size)
...
_frozen_importlib 31764
_frozen_importlib_external 41499
zipimport 12345
>>>
标准 Python 具有冻结模块和冻结包(由负 size
成员指示)这一事实并不广为人知,它仅用于测试。例如,尝试使用 import __hello__
。
意外情况¶
在 ctypes
中,您可能会遇到一些边缘情况,在这些情况下,您预期的结果与实际发生的情况不同。
请考虑以下示例。
>>> from ctypes import *
>>> class POINT(Structure):
... _fields_ = ("x", c_int), ("y", c_int)
...
>>> class RECT(Structure):
... _fields_ = ("a", POINT), ("b", POINT)
...
>>> p1 = POINT(1, 2)
>>> p2 = POINT(3, 4)
>>> rc = RECT(p1, p2)
>>> print(rc.a.x, rc.a.y, rc.b.x, rc.b.y)
1 2 3 4
>>> # now swap the two points
>>> rc.a, rc.b = rc.b, rc.a
>>> print(rc.a.x, rc.a.y, rc.b.x, rc.b.y)
3 4 3 4
>>>
嗯。我们当然希望最后一条语句打印 3 4 1 2
。发生了什么事?以下是上面 rc.a, rc.b = rc.b, rc.a
行的步骤。
>>> temp0, temp1 = rc.b, rc.a
>>> rc.a = temp0
>>> rc.b = temp1
>>>
请注意,temp0
和 temp1
是仍然使用上面 rc
对象的内部缓冲区的对象。因此,执行 rc.a = temp0
会将 temp0
的缓冲区内容复制到 rc
的缓冲区中。反过来,这也会更改 temp1
的内容。因此,最后的赋值 rc.b = temp1
不会产生预期的效果。
请记住,从结构体、联合体和数组中检索子对象不会*复制*子对象,而是检索一个访问根对象底层缓冲区的包装器对象。
另一个可能与预期行为不同的示例如下。
>>> s = c_char_p()
>>> s.value = b"abc def ghi"
>>> s.value
b'abc def ghi'
>>> s.value is s.value
False
>>>
注意
从 c_char_p
实例化的对象只能将其值设置为字节或整数。
为什么它打印 False
?ctypes 实例是包含内存块和一些访问内存内容的 描述符 的对象。在内存块中存储 Python 对象不会存储对象本身,而是存储对象的 内容
。每次访问内容时都会构造一个新的 Python 对象!
可变大小的数据类型¶
ctypes
为可变大小的数组和结构体提供了一些支持。
resize()
函数可用于调整现有 ctypes 对象的内存缓冲区大小。该函数将对象作为第一个参数,将请求的大小(以字节为单位)作为第二个参数。内存块的大小不能小于对象类型指定的自然内存块大小,如果尝试这样做,则会引发 ValueError
>>> short_array = (c_short * 4)()
>>> print(sizeof(short_array))
8
>>> resize(short_array, 4)
Traceback (most recent call last):
...
ValueError: minimum size is 8
>>> resize(short_array, 32)
>>> sizeof(short_array)
32
>>> sizeof(type(short_array))
8
>>>
这很好,但是如何访问此数组中包含的其他元素呢?由于该类型仍然只知道 4 个元素,因此我们在访问其他元素时会出错
>>> short_array[:]
[0, 0, 0, 0]
>>> short_array[7]
Traceback (most recent call last):
...
IndexError: invalid index
>>>
在 ctypes
中使用可变大小数据类型的另一种方法是利用 Python 的动态特性,并在已知所需大小后根据具体情况(重新)定义数据类型。
ctypes 参考¶
外部函数¶
如上一节所述,可以将外部函数作为已加载共享库的属性进行访问。默认情况下,以这种方式创建的函数对象接受任意数量的参数,接受任何 ctypes 数据实例作为参数,并返回库加载器指定的默认结果类型。它们是私有类的实例
- class ctypes._FuncPtr¶
C 可调用外部函数的基类。
外部函数的实例也是 C 兼容的数据类型;它们表示 C 函数指针。
可以通过将值赋给外部函数对象的特殊属性来自定义此行为。
- restype¶
分配一个 ctypes 类型以指定外部函数的结果类型。对于 void(不返回任何内容的函数),请使用
None
。可以分配一个不是 ctypes 类型的可调用 Python 对象,在这种情况下,该函数假定返回 C int,并且将使用此整数调用该可调用对象,从而允许进行进一步的处理或错误检查。不建议使用此方法,为了进行更灵活的后处理或错误检查,请使用 ctypes 数据类型作为
restype
并将可调用对象分配给errcheck
属性。
- argtypes¶
分配一个 ctypes 类型元组以指定函数接受的参数类型。使用
stdcall
调用约定的函数只能使用与此元组长度相同的参数数量进行调用;使用 C 调用约定的函数也接受其他未指定的参数。调用外部函数时,每个实际参数都会传递给
argtypes
元组中各项的from_param()
类方法,此方法允许将实际参数调整为外部函数接受的对象。例如,argtypes
元组中的c_char_p
项将使用 ctypes 转换规则将作为参数传递的字符串转换为字节对象。新增:现在可以在 argtypes 中放入不是 ctypes 类型的项,但每个项都必须有一个
from_param()
方法,该方法返回一个可用作参数的值(整数、字符串、ctypes 实例)。这允许定义适配器,这些适配器可以将自定义对象作为函数参数进行适配。
- errcheck¶
将 Python 函数或其他可调用对象分配给此属性。将使用三个或更多参数调用该可调用对象
- callable(result, func, arguments)
result 是外部函数返回的内容,由
restype
属性指定。func 是外部函数对象本身,这允许重用同一个可调用对象来检查或后处理多个函数的结果。
arguments 是一个元组,其中包含最初传递给函数调用的参数,这允许根据使用的参数专门化行为。
此函数返回的对象将从外部函数调用中返回,但它也可以检查结果值并在外部函数调用失败时引发异常。
- exception ctypes.ArgumentError¶
当外部函数调用无法转换传递的参数之一时,将引发此异常。
在 Windows 上,当外部函数调用引发系统异常(例如,由于访问冲突)时,它将被捕获并替换为合适的 Python 异常。此外,还会引发带有参数 code
的审计事件 ctypes.set_exception
,从而允许审计钩子用其自身的异常替换该异常。
某些调用外部函数的方法可能会引发带有参数 function pointer
和 arguments
的审计事件 ctypes.call_function
。
函数原型¶
也可以通过实例化函数原型来创建外部函数。 函数原型类似于 C 中的函数原型; 它们描述一个函数(返回类型、参数类型、调用约定)而不定义实现。 工厂函数必须使用所需的返回类型和函数的参数类型来调用,并且可以用作装饰器工厂,因此,可以通过 @wrapper
语法应用于函数。 有关示例,请参阅 回调函数。
- ctypes.CFUNCTYPE(restype, *argtypes, use_errno=False, use_last_error=False)¶
返回的函数原型创建使用标准 C 调用约定的函数。 该函数将在调用期间释放 GIL。 如果将 use_errno 设置为 true,则在调用前后将系统
errno
变量的 ctypes 私有副本与实际的errno
值交换; use_last_error 对 Windows 错误代码执行相同的操作。
- ctypes.WINFUNCTYPE(restype, *argtypes, use_errno=False, use_last_error=False)¶
仅限 Windows:返回的函数原型创建使用
stdcall
调用约定的函数。 该函数将在调用期间释放 GIL。 use_errno 和 use_last_error 具有与上述相同的含义。
- ctypes.PYFUNCTYPE(restype, *argtypes)¶
返回的函数原型创建使用 Python 调用约定的函数。 该函数在调用期间*不会*释放 GIL。
由这些工厂函数创建的函数原型可以用不同的方式实例化,具体取决于调用中参数的类型和数量
- prototype(address)
返回指定地址处的外部函数,该地址必须是整数。
- prototype(callable)
从 Python callable 创建一个 C 可调用函数(回调函数)。
- prototype(func_spec[, paramflags])
返回由共享库导出的外部函数。 func_spec 必须是一个 2 元组
(name_or_ordinal, library)
。 第一个元素是作为字符串的导出函数的名称,或者作为小整数的导出函数的序号。 第二个元素是共享库实例。
- prototype(vtbl_index, name[, paramflags[, iid]])
返回一个外部函数,该函数将调用 COM 方法。 vtbl_index 是虚拟函数表中的索引,一个小的非负整数。 name 是 COM 方法的名称。 iid 是指向接口标识符的可选指针,用于扩展错误报告。
COM 方法使用一种特殊的调用约定:除了
argtypes
元组中指定的参数外,它们还需要一个指向 COM 接口的指针作为第一个参数。
可选的 paramflags 参数创建的外部函数包装器比上述功能具有更多功能。
paramflags 必须是与 argtypes
长度相同的元组。
此元组中的每个元素都包含有关参数的更多信息,它必须是一个包含一个、两个或三个元素的元组。
第一个元素是一个整数,其中包含参数的方向标志的组合
- 1
指定函数的输入参数。
- 2
输出参数。 外部函数填充一个值。
- 4
输入参数,默认为整数零。
可选的第二个元素是作为字符串的参数名称。 如果指定了此项,则可以使用命名参数调用外部函数。
可选的第三个元素是此参数的默认值。
以下示例演示如何包装 Windows MessageBoxW
函数,使其支持默认参数和命名参数。 windows 头文件中的 C 声明如下
WINUSERAPI int WINAPI
MessageBoxW(
HWND hWnd,
LPCWSTR lpText,
LPCWSTR lpCaption,
UINT uType);
以下是使用 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)
现在可以通过以下方式调用 MessageBox
外部函数
>>> MessageBox()
>>> MessageBox(text="Spam, spam, spam")
>>> MessageBox(flags=2, text="foo bar")
第二个示例演示了输出参数。 win32 GetWindowRect
函数通过将指定窗口的尺寸复制到调用者必须提供的 RECT
结构中来检索它们。 以下是 C 声明
WINUSERAPI BOOL WINAPI
GetWindowRect(
HWND hWnd,
LPRECT lpRect);
以下是使用 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)
>>>
具有输出参数的函数将在只有一个输出参数时自动返回输出参数值,或者在有多个输出参数时返回包含输出参数值的元组,因此 GetWindowRect 函数现在在被调用时返回一个 RECT 实例。
输出参数可以与 errcheck
协议结合使用,以进行进一步的输出处理和错误检查。 win32 GetWindowRect
api 函数返回一个 BOOL
来表示成功或失败,因此此函数可以执行错误检查,并在 api 调用失败时引发异常
>>> def errcheck(result, func, args):
... if not result:
... raise WinError()
... return args
...
>>> GetWindowRect.errcheck = errcheck
>>>
如果 errcheck
函数返回其接收到的参数元组不变,则 ctypes
将继续对输出参数执行正常处理。 如果要返回窗口坐标元组而不是 RECT
实例,则可以在函数中检索字段并返回它们,正常处理将不再进行
>>> 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
>>>
实用函数¶
- ctypes.alignment(obj_or_type)¶
返回 ctypes 类型的对齐要求。obj_or_type 必须是 ctypes 类型或实例。
- ctypes.byref(obj[, offset])¶
返回指向 obj 的轻量级指针,该指针必须是 ctypes 类型的实例。offset 默认为零,并且必须是将添加到内部指针值的整数。
byref(obj, offset)
对应于以下 C 代码(((char *)&obj) + offset)
返回的对象只能用作外部函数调用参数。它的行为类似于
pointer(obj)
,但构造速度要快得多。
- ctypes.cast(obj, type)¶
此函数类似于 C 中的强制转换运算符。它返回 type 的新实例,该实例指向与 obj 相同的内存块。type 必须是指针类型,obj 必须是可以解释为指针的对象。
- ctypes.create_string_buffer(init_or_size, size=None)¶
此函数创建一个可变字符缓冲区。返回的对象是一个
c_char
的 ctypes 数组。init_or_size 必须是一个整数,用于指定数组的大小,或者是一个字节对象,用于初始化数组项。
如果将字节对象指定为第一个参数,则缓冲区的大小将比其长度大一个元素,以便数组中的最后一个元素是 NUL 终止字符。可以将整数作为第二个参数传递,以便在不应使用字节长度的情况下指定数组的大小。
使用参数
init
、size
引发 审计事件ctypes.create_string_buffer
。
- ctypes.create_unicode_buffer(init_or_size, size=None)¶
此函数创建一个可变的 Unicode 字符缓冲区。返回的对象是一个
c_wchar
的 ctypes 数组。init_or_size 必须是一个整数,用于指定数组的大小,或者是一个字符串,用于初始化数组项。
如果将字符串指定为第一个参数,则缓冲区的大小将比字符串的长度大一个元素,以便数组中的最后一个元素是 NUL 终止字符。可以将整数作为第二个参数传递,以便在不应使用字符串长度的情况下指定数组的大小。
使用参数
init
、size
引发 审计事件ctypes.create_unicode_buffer
。
- ctypes.DllCanUnloadNow()¶
仅限 Windows:此函数是一个钩子,允许使用 ctypes 实现进程内 COM 服务器。它从 _ctypes 扩展 DLL 导出的 DllCanUnloadNow 函数调用。
- ctypes.DllGetClassObject()¶
仅限 Windows:此函数是一个钩子,允许使用 ctypes 实现进程内 COM 服务器。它从
_ctypes
扩展 DLL 导出的 DllGetClassObject 函数调用。
- ctypes.util.find_library(name)¶
尝试查找库并返回路径名。name 是不带任何前缀(如
lib
)、后缀(如.so
、.dylib
)或版本号的库名(这是用于 posix 链接器选项-l
的形式)。如果找不到库,则返回None
。确切的功能取决于系统。
- ctypes.util.find_msvcrt()¶
仅限 Windows:返回 Python 和扩展模块使用的 VC 运行时库的文件名。如果无法确定库的名称,则返回
None
。如果需要释放内存(例如,由扩展模块通过调用
free(void *)
分配的内存),则必须使用分配内存的同一个库中的函数。
- ctypes.FormatError([code])¶
仅限 Windows:返回错误代码 code 的文本描述。如果没有指定错误代码,则通过调用 Windows api 函数 GetLastError 使用最后一个错误代码。
- ctypes.GetLastError()¶
仅限 Windows:返回 Windows 在调用线程中设置的最后一个错误代码。此函数直接调用 Windows
GetLastError()
函数,它不返回错误代码的 ctypes 私有副本。
- ctypes.get_last_error()¶
仅限 Windows:返回调用线程中系统
LastError
变量的 ctypes 私有副本的当前值。引发一个不带参数的 审计事件
ctypes.get_last_error
。
- ctypes.memmove(dst, src, count)¶
与标准 C memmove 库函数相同:将 src 中的 count 个字节复制到 dst。dst 和 src 必须是整数或可以转换为指针的 ctypes 实例。
- ctypes.memset(dst, c, count)¶
与标准 C memset 库函数相同:用 count 个字节的值 c 填充地址 dst 处的内存块。dst 必须是指定地址的整数或 ctypes 实例。
- ctypes.POINTER(type, /)¶
创建并返回一个新的 ctypes 指针类型。指针类型在内部缓存和重用,因此重复调用此函数的开销很低。type 必须是 ctypes 类型。
- ctypes.pointer(obj, /)¶
创建一个指向 obj 的新指针实例。返回的对象的类型为
POINTER(type(obj))
。注意:如果您只想将指向对象的指针传递给外部函数调用,则应使用
byref(obj)
,它的速度要快得多。
- ctypes.resize(obj, size)¶
此函数调整 obj 的内部内存缓冲区的大小,obj 必须是 ctypes 类型的实例。无法使缓冲区小于对象类型的本机大小(由
sizeof(type(obj))
给出),但可以扩大缓冲区。
- ctypes.set_errno(value)¶
将调用线程中系统
errno
变量的 ctypes 私有副本的当前值设置为 value 并返回先前的值。引发一个带有参数
errno
的 审计事件ctypes.set_errno
。
- ctypes.set_last_error(value)¶
仅限 Windows:将调用线程中系统
LastError
变量的 ctypes 私有副本的当前值设置为 value 并返回先前的值。引发一个带有参数
error
的 审计事件ctypes.set_last_error
。
- ctypes.sizeof(obj_or_type)¶
返回 ctypes 类型或实例内存缓冲区的大小(以字节为单位)。与 C
sizeof
运算符的功能相同。
- ctypes.string_at(ptr, size=-1)¶
返回 void *ptr 处的字节字符串。如果指定了 size,则将其用作大小,否则假定字符串以零结尾。
引发一个带有参数
ptr
、size
的 审计事件ctypes.string_at
。
- ctypes.WinError(code=None, descr=None)¶
仅限 Windows:此函数可能是 ctypes 中命名最糟糕的东西。它创建了一个
OSError
的实例。如果未指定 code,则调用GetLastError
来确定错误代码。如果未指定 descr,则调用FormatError()
来获取错误的文本描述。在 3.3 版更改: 过去创建的是
WindowsError
的实例,现在它是OSError
的别名。
数据类型¶
- class ctypes._CData¶
这个非公共类是所有 ctypes 数据类型的公共基类。除此之外,所有 ctypes 类型实例都包含一个保存 C 兼容数据的内存块;内存块的地址由
addressof()
辅助函数返回。另一个实例变量公开为_objects
;它包含其他 Python 对象,如果内存块包含指针,则需要保持这些对象的活动状态。ctypes 数据类型的常用方法,这些都是类方法(确切地说,它们是 元类 的方法)
- from_buffer(source[, offset])¶
此方法返回一个 ctypes 实例,该实例共享 source 对象的缓冲区。source 对象必须支持可写缓冲区接口。可选的 offset 参数指定源缓冲区中以字节为单位的偏移量;默认为零。如果源缓冲区不够大,则会引发
ValueError
。使用参数
pointer
、size
、offset
引发 审计事件ctypes.cdata/buffer
。
- from_buffer_copy(source[, offset])¶
此方法创建一个 ctypes 实例,从 source 对象缓冲区复制缓冲区,该缓冲区必须是可读的。可选的 offset 参数指定源缓冲区中以字节为单位的偏移量;默认为零。如果源缓冲区不够大,则会引发
ValueError
。使用参数
pointer
、size
、offset
引发 审计事件ctypes.cdata/buffer
。
- from_address(address)¶
此方法使用 address 指定的内存返回一个 ctypes 类型实例,该地址必须是一个整数。
此方法以及其他间接调用此方法的方法,使用参数
address
引发 审计事件ctypes.cdata
。
- from_param(obj)¶
此方法将 obj 调整为 ctypes 类型。当类型出现在外部函数的
argtypes
元组中时,它将使用外部函数调用中使用的实际对象调用;它必须返回一个可以用作函数调用参数的对象。所有 ctypes 数据类型都有此类方法的默认实现,如果该对象是该类型的实例,则通常返回 obj。某些类型也接受其他对象。
- in_dll(library, name)¶
此方法返回由共享库导出的 ctypes 类型实例。name 是导出数据的符号的名称,library 是已加载的共享库。
ctypes 数据类型的常见实例变量
- _b_needsfree_¶
当 ctypes 数据实例自身分配内存块时,此只读变量为 true,否则为 false。
- _objects¶
此成员是
None
或包含 Python 对象的字典,需要保留这些对象以保持内存块内容有效。此对象仅用于调试;切勿修改此字典的内容。
基本数据类型¶
- class ctypes._SimpleCData¶
这个非公共类是所有基本 ctypes 数据类型的基类。这里提到它是因为它包含了基本 ctypes 数据类型的共同属性。
_SimpleCData
是_CData
的子类,因此它继承了它们的方法和属性。不包含指针的 ctypes 数据类型现在可以被序列化。实例有一个属性
基本数据类型,当作为外部函数调用结果返回时,或者例如,通过检索结构字段成员或数组项,会透明地转换为原生 Python 类型。换句话说,如果外部函数的 restype
为 c_char_p
,您将始终收到一个 Python 字节对象,*而不是* 一个 c_char_p
实例。
基本数据类型的子类*不* 继承此行为。因此,如果外部函数的 restype
是 c_void_p
的子类,您将从函数调用中收到此子类的实例。当然,您可以通过访问 value
属性来获取指针的值。
以下是基本 ctypes 数据类型
- class ctypes.c_byte¶
表示 C signed char 数据类型,并将该值解释为小整数。构造函数接受一个可选的整数初始化器;不进行溢出检查。
- class ctypes.c_char¶
表示 C char 数据类型,并将该值解释为单个字符。构造函数接受一个可选的字符串初始化器,字符串的长度必须恰好为一个字符。
- class ctypes.c_char_p¶
当 C char* 数据类型指向以零结尾的字符串时,表示该数据类型。对于也可能指向二进制数据的通用字符指针,必须使用
POINTER(c_char)
。构造函数接受一个整数地址或一个字节对象。
- class ctypes.c_double¶
表示 C double 数据类型。构造函数接受一个可选的浮点数初始值。
- class ctypes.c_longdouble¶
表示 C long double 数据类型。构造函数接受一个可选的浮点数初始值。在
sizeof(long double) == sizeof(double)
的平台上,它是c_double
的别名。
- class ctypes.c_float¶
表示 C float 数据类型。构造函数接受一个可选的浮点数初始值。
- class ctypes.c_int¶
表示 C signed int 数据类型。构造函数接受一个可选的整数初始值;不进行溢出检查。在
sizeof(int) == sizeof(long)
的平台上,它是c_long
的别名。
- class ctypes.c_int64¶
表示 C 64 位 signed int 数据类型。通常是
c_longlong
的别名。
- class ctypes.c_long¶
表示 C signed long 数据类型。构造函数接受一个可选的整数初始值;不进行溢出检查。
- class ctypes.c_longlong¶
表示 C signed long long 数据类型。构造函数接受一个可选的整数初始值;不进行溢出检查。
- class ctypes.c_short¶
表示 C signed short 数据类型。构造函数接受一个可选的整数初始值;不进行溢出检查。
- class ctypes.c_size_t¶
表示 C
size_t
数据类型。
- class ctypes.c_ssize_t¶
表示 C
ssize_t
数据类型。3.2 版新增。
- class ctypes.c_time_t¶
表示 C
time_t
数据类型。3.12 版新增。
- class ctypes.c_ubyte¶
表示 C unsigned char 数据类型,它将值解释为小整数。构造函数接受一个可选的整数初始值;不进行溢出检查。
- class ctypes.c_uint¶
表示 C unsigned int 数据类型。构造函数接受一个可选的整数初始值;不进行溢出检查。在
sizeof(int) == sizeof(long)
的平台上,它是c_ulong
的别名。
- class ctypes.c_uint64¶
表示 C 64 位 unsigned int 数据类型。通常是
c_ulonglong
的别名。
- class ctypes.c_ulong¶
表示 C unsigned long 数据类型。构造函数接受一个可选的整数初始化器;不进行溢出检查。
- class ctypes.c_ulonglong¶
表示 C unsigned long long 数据类型。构造函数接受一个可选的整数初始化器;不进行溢出检查。
- class ctypes.c_ushort¶
表示 C unsigned short 数据类型。构造函数接受一个可选的整数初始化器;不进行溢出检查。
- class ctypes.c_void_p¶
表示 C void* 类型。该值表示为整数。构造函数接受一个可选的整数初始化器。
- class ctypes.c_wchar¶
表示 C
wchar_t
数据类型,并将该值解释为单个字符的 Unicode 字符串。构造函数接受一个可选的字符串初始化器,字符串的长度必须恰好为一个字符。
- class ctypes.c_wchar_p¶
表示 C wchar_t* 数据类型,它必须是指向以零结尾的宽字符串的指针。构造函数接受一个整数地址或一个字符串。
- class ctypes.c_bool¶
表示 C bool 数据类型(更准确地说,是 C99 中的 _Bool)。它的值可以是
True
或False
,并且构造函数接受任何具有真值的 Python 对象。
- class ctypes.HRESULT¶
仅限 Windows:表示
HRESULT
值,其中包含函数或方法调用的成功或错误信息。
ctypes.wintypes
模块提供了许多其他 Windows 特定的数据类型,例如 HWND
、WPARAM
或 DWORD
。还定义了一些有用的结构,如 MSG
或 RECT
。
结构化数据类型¶
- class ctypes.Union(*args, **kw)¶
按本机字节顺序排列的联合体的抽象基类。
- class ctypes.BigEndianUnion(*args, **kw)¶
按*大端*字节顺序排列的联合体的抽象基类。
3.11 版新增。
- class ctypes.LittleEndianUnion(*args, **kw)¶
按*小端*字节顺序排列的联合体的抽象基类。
3.11 版新增。
- class ctypes.BigEndianStructure(*args, **kw)¶
按*大端*字节顺序排列的结构体的抽象基类。
- class ctypes.LittleEndianStructure(*args, **kw)¶
按*小端*字节顺序排列的结构体的抽象基类。
非本机字节顺序的结构体和联合体不能包含指针类型字段,也不能包含任何其他包含指针类型字段的数据类型。
- class ctypes.Structure(*args, **kw)¶
以本地字节顺序表示结构体的抽象基类。
具体的结构体和联合类型必须通过继承这些类型之一来创建,并且至少要定义一个
_fields_
类变量。ctypes
将创建 描述符,允许通过直接属性访问来读取和写入字段。它们是:- _fields_¶
定义结构体字段的序列。每个元素必须是 2 元组或 3 元组。第一个元素是字段的名称,第二个元素指定字段的类型;它可以是任何 ctypes 数据类型。
对于像
c_int
这样的整数类型字段,可以给出第三个可选元素。它必须是一个定义字段位宽的小正整数。字段名称在一个结构体或联合中必须是唯一的。这不进行检查,当名称重复时,只能访问一个字段。
可以在定义 Structure 子类的类语句之后定义
_fields_
类变量,这允许创建直接或间接引用自身的的数据类型。class List(Structure): pass List._fields_ = [("pnext", POINTER(List)), ... ]
但是,
_fields_
类变量必须在首次使用该类型之前定义(创建一个实例,对其调用sizeof()
,等等)。之后对_fields_
类变量的赋值将引发 AttributeError。可以定义结构体类型的子子类,它们继承基类的字段以及子子类中定义的
_fields_
(如果有)。
- _anonymous_¶
一个可选的序列,列出未命名(匿名)字段的名称。
_anonymous_
必须在分配_fields_
时已经定义,否则它将不起作用。此变量中列出的字段必须是结构体或联合类型字段。
ctypes
将在结构体类型中创建描述符,允许直接访问嵌套字段,而无需创建结构体或联合字段。以下是一个示例类型(Windows):
class _U(Union): _fields_ = [("lptdesc", POINTER(TYPEDESC)), ("lpadesc", POINTER(ARRAYDESC)), ("hreftype", HREFTYPE)] class TYPEDESC(Structure): _anonymous_ = ("u",) _fields_ = [("u", _U), ("vt", VARTYPE)]
TYPEDESC
结构体描述了一个 COM 数据类型,vt
字段指定哪个联合字段有效。由于u
字段被定义为匿名字段,因此现在可以直接从 TYPEDESC 实例访问其成员。td.lptdesc
和td.u.lptdesc
是等效的,但前者更快,因为它不需要创建临时的联合实例。td = TYPEDESC() td.vt = VT_PTR td.lptdesc = POINTER(some_type) td.u.lptdesc = POINTER(some_type)
可以定义结构体的子子类,它们继承基类的字段。如果子类定义有单独的
_fields_
变量,则其中指定的字段将追加到基类的字段中。结构体和联合构造函数接受位置参数和关键字参数。位置参数用于按照
_fields_
中出现的顺序初始化成员字段。构造函数中的关键字参数被解释为属性赋值,因此它们将初始化与之同名的_fields_
,或者为_fields_
中不存在的名称创建新属性。