Python C/C++ 拓展使用接口库(build-in) ctypes 使用手册

ctypes 是一个Python 标准库中的一个库.为了实现调用 DLL,或者共享库等C数据类型而设计.它可以把这些C库包装后在纯Python环境下调用.

注意:代码中 c_int 类型其实只是 c_long 的别名,在32位系统中他们被定义为相同的数据类型.

1.1 加载动态链接库

ctypes 可以导出 cdll,在windows上则为 windll和oledll

究竟什么是 cdll,windll和oledll? 他们是DLL生成时的调用约定(不同语言生成的dll也会有细微差别). 这样来说用cdll方法导出DLL中的方法是使用cdecl方式的,windll方法则是stdcall方式的,oledll下面再具体解释.也可以查阅官方说法

CDLL:代码方式 cdecl 。

WINDLL:代码方式win32 stdcall 。

oledll使用win32调用代码方式 且返回值是windows里返回的hresult值,双字节的值说明函数执行结果,其最高bit位为0则执行成功,1则为执行失败。详细见http://www.blogjava.net/JAVA-HE/archive/2010/01/04/308134.html。

cdecl和stdcall异同,参数入栈顺序均是从右向左,不同的是栈的清除工作,cdecl是由调用者负责清除,stdcall由被调用者清除。

在python3.3中改变:WIndows的错误类型 WindowsError,现在只是OSError的别名.

下面是一个Windows中的例子.其中 msvcrt 是MS(微软)标准C库,它包含了大多数的标准C库函数,并使用 cdecl 代码方式来调用:

>>> from ctypes import *                   # 导入 ctypes模块

>>> print(windll.kernel32)                 # 使用windll约定方式导出 kernel32.dll 中的功能和信息

<WinDLL 'kernel32', handle ... at ...>

>>> print(cdll.msvcrt)                     # 使用cdll约定方式导出 msvcrt.dll 中的功能和信息

<CDLL 'msvcrt', handle ... at ...>

>>> libc = cdll.msvcrt

>>>

在windows中,通常 .dll 后缀会自动加上

而在Linux系统中,必须具体指定文件名(包含后缀)才能加载,所以基于"属性"的调用就不可能了,例如 windll.kernel32.dll 中最后一个"."到底是 kernal32 的属性还是后缀名的一部分?不得而知. 所以我们必须使用 LoadLibrary() 方法来加载 dll,或者通过实例化CDLL来加载dll.

>>> cdll.LoadLibrary("libc.so.6")

<CDLL 'libc.so.6', handle ... at ...>

>>> libc = CDLL("libc.so.6")

>>> libc

<CDLL 'libc.so.6', handle ... at ...>

>>>

在 Linux系统中(Ubuntu等) 动态链接库的编译与windows不同,后缀也不同,通常为 .so 文件,放在 usr/lib 文件夹下,而windows的dll大多放在Windows\System32文件夹下.其实原理差不多.我们这里统一称为dll代表 Dynamic Link Library,而非单指windows下的动态链接库文件.

1.2 从dll中获取函数

函数是从dll对象中的属性来获取得到的

接着上面的代码

>>> libc.printf

<_FuncPtr object at 0x...>                   # 可以看到 libc.printf 函数的信息

>>> print(windll.kernel32.GetModuleHandleA)

<_FuncPtr object at 0x...>                   # 与上述相同

>>> print(windll.kernel32.MyOwnFunction)     # 返回错误信息没有该函数属性

Traceback (most recent call last):

  File "<stdin>", line 1, in ?

  File "ctypes.py", line 239, in __getattr__

    func = _StdcallFuncPtr(name, self)

AttributeError: function 'MyOwnFunction' not found

>>>

注意win32系统dll像 kernel32 和 user32 通常既会返回ANSI也会返回UNICODE的函数版本. UNICODE版本通常会有"W"作为名字后缀,ANSI则是A.

比如 win32 中的 GetModuleHandle函数会根据 module的名字返回一个 module handle, 库内部根据宏定义选择以下两个版本之一作为函数原型:

/* ANSI version */

HMODULE GetModuleHandleA(LPCSTR lpModuleName);

/* UNICODE version */

HMODULE GetModuleHandleW(LPCWSTR lpModuleName);

windll 不会神奇的选择其中的一项,你必须显示的指定调用,然后使用指定的类型参数(宽字符)

有些时候 dll 导出的函数不是Python中的有效值,比如 "??2@YAPAXI@Z". 在这种情况下你必须使用函数 getattr() 来获取函数:

>>> getattr(cdll.msvcrt, "??2@YAPAXI@Z")   # 因为 cdll.msvcrt.??2@YAPAXI@Z 不合法,变量名(属性)不可以这样定义

<_FuncPtr object at 0x...>

>>>

在windows中,一些dll的导出函数并不是按名字来的,而是下标数字. 这些函数可以用下标序号来获取,比如:

>>> cdll.kernel32[1]               # 通过下标获取函数信息

<_FuncPtr object at 0x...>

>>> cdll.kernel32[0]               # 可见并不是按顺序排列的...

Traceback (most recent call last):

	File "<stdin>", line 1, in ?

	File "ctypes.py", line 310, in __getitem__

		func = _StdcallFuncPtr(name, self)

AttributeError: function ordinal 0 not found

>>>

1.3 调用函数

你可以像调用Python一样调用这些函数.在这个例子中我们使用 time() 函数,该函数返回自Unix时间戳(1970年1月1日00:00:00 UTC)到现在的累计总秒数.(会不会int32值不够用?int32可以代表68年间的总秒数uint32则136年,uint64则是584942417354年)

下面的例子中函数都以 NULL 指针来调用( None在python中代表 NULL)

>>> print(libc.time(None))

1150640792

>>> print(hex(windll.kernel32.GetModuleHandleA(None)))

0x1d000000

>>>

ctypes试图阻止你用错误的参数和代码风格,但这种徒劳只在Windows下有效.

>>> windll.kernel32.GetModuleHandleA()

Traceback (most recent call last):

  File "<stdin>", line 1, in ?

ValueError: Procedure probably called with not enough arguments (4 bytes missing)

>>> windll.kernel32.GetModuleHandleA(0, 0)

Traceback (most recent call last):

  File "<stdin>", line 1, in ?

ValueError: Procedure probably called with too many arguments (4 bytes in excess)

>>>

下面一个例子会报错,原因是错误的使用 cdecl 风格来调用 stdcall 风格的函数,反过来也是错的

>>> cdll.kernel32.GetModuleHandleA(None)

Traceback (most recent call last):

  File "<stdin>", line 1, in ?

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 ?

ValueError: Procedure probably called with too many arguments (4 bytes in excess)

>>>

为了正确地使用调用函数风格你必须到C头文件中去查看,或者查阅有关文档.

在Windows中,ctypes使用win32结构的异常处理机制来防止程序 crash掉,当你传入无效参数的时候.

>>> windll.kernel32.GetModuleHandleA(32)  # 试图获得一个并不存在的模块

Traceback (most recent call last):

	File "<stdin>", line 1, in ?

OSError: exception: access violation reading 0x00000020  # 捕获到的异常

>>>

但令 ctypes crash掉有诸多方法(甚至没有异常捕获到),所以你必须很小心. faulthandler 模块(python内置)可以帮助你debug crash的具体原因.

None,integers,bytes,(unicode)strings 是仅有的可以被直接作为函数调用参数的Python原生结构.其中 None 对应C语言中 Null, bytes和 strings 作为内存块的指针 (char *,wchar_t *). Python中的 integers 对应C中的 int 类型,他们的值可被直接转换成C类型.

在我们使用其他类型的参数来调用C函数前,先来看一下 ctypes 中的数据类型

1.4 基本数据类型

ctypes 定义了一些基础C兼容的类型

ctypes type	C type	Python type
c_bool	_Bool	bool(1)
c_char	char	1-character bytes object
c_wchar	wchar_t	1-charactor string
c_byte	char	int
c_ubyte	unsigned char	int
c_short	short	int
c_ushort	unsigned short	int
c_int	int	int
c_uint	unsigned int	int
c_long	long	int
c_ulong	unsigned long	int
c_longlong	__int64 or long long	int
c_ulonglong	unsigned __int64 or unsigned long long	int
c_size_t	size_t	int
c_ssize_t	ssize_t or Py_ssize_t	int
c_float	float	float
c_double	double	float
c_longdouble	long double	float
c_char_p	char * (NUL terminated)	bytes object or None
c_wchar_p	wchar_t * (NUL terminated)	string or None
c_void_p	void *	int or None

构造函数接受任意对象(只要是值为真)

所有这些类型都可以用相应的类型和值来调用构造函数.

>>> c_int()     # 在文章前已经提及 ctypes 中 c_int只是 c_long的别名而已

c_long(0)

>>> c_wchar_p("Hello, World")

c_wchar_p('Hello, World')

>>> c_ushort(-3)

c_ushort(65533)

>>>

因为这些类型都是可变的(mutable),他们的值同样可以在定义之后被修改

>>> i = c_int(42)

>>> print(i)

c_long(42)

>>> print(i.value)

42

>>> i.value = -99  # 注意别忘了Python的特性,ctypes所有类型都是一个对象包装

>>> print(i.value) # 如果你使用i=-99,则 i会直接被Python原生int替换...

-99

>>>

给指针类型赋新值等于改变他们指向内存的位置,而不是修改他们所指内存中的值,指针类型有c_char_p, c_wchar_p和 c_void_p.(这非常好理解,因为Python中的 bytes 对象是不可修改的常量):

>>> s = "Hello, World"

>>> c_s = c_wchar_p(s)

>>> print(c_s)

c_wchar_p('Hello, World')

>>> c_s.value = "Hi, there"

>>> print(c_s)

c_wchar_p('Hi, there')

>>> print(s)                 # first object is unchanged

Hello, World

>>>

你应该小心,不要把这些指针传给试图改变内存的函数. 如果你确实需要改变内存数据而非替换指针地址, ctypes提供了create_string_buffer()函数.

内存块可以使用 raw 属性来访问和修改; 如果你希望访问一个以 NUL 为结尾 string, 则使用 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"                       # 这里注意 p.value = b'HI'并不是把value替换成常量b'HI'的指针,而是直接修改了buffer

>>> print(sizeof(p), repr(p.raw))

10 b'Hi\x00lo\x00\x00\x00\x00\x00'        # 从这里看得到，确实是 buffer 被修改了,上一次的值Hello 中的lo还在内存之中.

>>>

create_string_buffer() 函数代替了以前的 c_buffer() 函数(现在依旧可用,作为别名). 为了创建可修改的unicode wchar_t类型内存块, 请使用 create_unicode_buffer() 函数.

1.5 再谈调用函数

注意 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 ?

ArgumentError: argument 2: exceptions.TypeError: Don't know how to convert parameter 2

>>>

就像之前提到的那样, 只有四种类型 integers:42, (unicode)strings:"World!", bytes objects:b"World!", NULL:None. 其他所有相应类型类型都需要用 ctypes进行相应的包装才能被使用:

>>> printf(b"An int %d, a double %f\n", 1234, c_double(3.14))

An int 1234, a double 3.140000

31

>>>

1.6 使用自定义数据类型调用函数

你可以自定义 ctypes 的参数变换来使用自定义数据类型作为函数参数. ctypes 查看 as_parameter 这个属性,并使用它作为函数参数. 当然,它必须是Python支持的四种类型之一:

>>> 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_paramter 之中,那你也可以动态地给任意一个对象增加这个属性值.

1.7 指定参数类型(函数原型定义)

通过设置 argtypes 属性,我们可以指定函数的参数类型.

argtypes 必须是C数据类型的一个数列(printf 可能并不是个很好的例子,但是可以用来实验这个特性):

>>> printf.argtypes = [c_char_p, c_char_p, c_int, c_double]  # 指定4个参数,按顺序

>>> 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)               # 与 argtypes 中定义的参数数列不匹配并报错

Traceback (most recent call last):

  File "<stdin>", line 1, in ?

ArgumentError: argument 2: exceptions.TypeError: wrong type

>>> printf(b"%s %d %f\n", b"X", 2, 3)          # 可以看到最后一个参数被 c_double(3)转化成了有效值

X 2 3.000000

13

>>>

如果你定义了一个自己的类,并试图将它作为参数传入函数时,你必须实现它的 from_param() 类方法,为了能在 argtypes 数列中使用他们. from_param() 类方法会获得函数调用时对应参数位置传入的Python对象并且由您自己判断并实现您觉得必要的一些类型检查工作,最后返回该传入的对象或者该对象的 as_parameter 属性,又或者是你想返回的任何东西(返回内容完全看你的心情). 当然返回结果也必须是四种原生数据类型中的一种,或者依旧是一个带有 _as_parameter_属性的对象.(注:所有这些只有在你想使用 argtypes 来做函数的参数类型限定时才是必须的)

1.8 返回值类型

ctypes默认函数的返回值应该是 C int类型的. 其他类型的返回值则要使用函数对象的 restpye 属性来设置.

下面是一个更高级的例子,它使用 strchr 函数(接受一个 string 指针和一个 char,查找字符串中首次出现字符char的位置并返回指针)

>>> strchr = libc.strchr

>>> strchr(b"abcdef", ord("d"))

8059983            # 这里ctypes并不知道返回的是什么,所以默认直接就把指针地址打印了出来(int型)

>>> strchr.restype = c_char_p   # c_char_p is a pointer to a string

>>> strchr(b"abcdef", ord("d"))

b'def'			   # 这里设置过了,ctypes知道返回的是c_char_p类型,所以打印该指针指向的字符串数据

>>> print(strchr(b"abcdef", ord("x")))

None

>>>

如果你想避免使用 ord()函数(用来返回char字符的数字编码), 你可以设置 argtypes ,那么第二个参数就会从Python的单字节对象转换成 C char类型数据:

>>> strchr.restype = c_char_p

>>> strchr.argtypes = [c_char_p, c_char]

>>> strchr(b"abcdef", b"d")

'def'

>>> strchr(b"abcdef", b"def")

Traceback (most recent call last):

  File "<stdin>", line 1, in ?

ArgumentError: argument 2: exceptions.TypeError: one character string expected

>>> print(strchr(b"abcdef", b"x"))

None

>>> strchr(b"abcdef", b"d")

'def'

>>>

--------------------余下部分还未翻译--------------------

strchr.restype = c_char_p

strchr.argtypes = [c_char_p, c_char]

strchr("abcdef", "d")

'def'

strchr("abcdef", "def")

Traceback (most recent call last):

File "", line 1, in ?

ArgumentError: argument 2: exceptions.TypeError: one character string expected

print strchr("abcdef", "x")

None

strchr("abcdef", "d")

'def'

You can also use a callable Python object (a function or a class for example) as the restype attribute, if the foreign function returns an integer. The callable will be called with the integer the C function returns, and the result of this call will be used as the result of your function call. This is useful to check for error return values and automatically raise an exception:

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 "", line 1, in ?

File "", line 3, in ValidHandle

WindowsError: [Errno 126] The specified module could not be found.

WinError is a function which will call Windows FormatMessage() api to get the string representation of an error code, and returns an exception. WinError takes an optional error code parameter, if no one is used, it calls GetLastError() to retrieve it.

Please note that a much more powerful error checking mechanism is available through the errcheck attribute; see the reference manual for details.

15.17.1.9. Passing pointers (or: passing parameters by reference)

Sometimes a C api function expects a pointer to a data type as parameter, probably to write into the corresponding location, or if the data is too large to be passed by value. This is also known as passing parameters by reference.

ctypes exports the byref() function which is used to pass parameters by reference. The same effect can be achieved with the pointer() function, although pointer() does a lot more work since it constructs a real pointer object, so it is faster to use byref() if you don’t need the pointer object in Python itself:

i = c_int()

f = c_float()

s = create_string_buffer('\000' * 32)

print i.value, f.value, repr(s.value)

0 0.0 ''

libc.sscanf("1 3.14 Hello", "%d %f %s",

... byref(i), byref(f), s)

3

print i.value, f.value, repr(s.value)

1 3.1400001049 'Hello'

15.17.1.10. Structures and unions

Structures and unions must derive from the Structure and Union base classes which are defined in the ctypes module. Each subclass must define a fields attribute. fields must be a list of 2-tuples, containing a field name and a field type.

The field type must be a ctypes type like c_int, or any other derived ctypes type: structure, union, array, pointer.

Here is a simple example of a POINT structure, which contains two integers named x and y, and also shows how to initialize a structure in the constructor:

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 "", line 1, in ?

ValueError: too many initializers

You can, however, build much more complicated structures. A structure can itself contain other structures by using a structure as a field type.

Here is a RECT structure which contains two POINTs named upperleft and lowerright:

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

Nested structures can also be initialized in the constructor in several ways:

r = RECT(POINT(1, 2), POINT(3, 4))

r = RECT((1, 2), (3, 4))

Field descriptors can be retrieved from the class, they are useful for debugging because they can provide useful information:

print POINT.x

print POINT.y

Warning:

ctypes does not support passing unions or structures with bit-fields to functions by value. While this may work on 32-bit x86, it’s not guaranteed by the library to work in the general case. Unions and structures with bit-fields should always be passed to functions by pointer.

15.17.1.11. Structure/union alignment and byte order

By default, Structure and Union fields are aligned in the same way the C compiler does it. It is possible to override this behavior be specifying a pack class attribute in the subclass definition. This must be set to a positive integer and specifies the maximum alignment for the fields. This is what #pragma pack(n) also does in MSVC.

ctypes uses the native byte order for Structures and Unions. To build structures with non-native byte order, you can use one of the BigEndianStructure, LittleEndianStructure, BigEndianUnion, and LittleEndianUnion base classes. These classes cannot contain pointer fields.

15.17.1.12. Bit fields in structures and unions

It is possible to create structures and unions containing bit fields. Bit fields are only possible for integer fields, the bit width is specified as the third item in the fields tuples:

class Int(Structure):

... fields = [("first_16", c_int, 16),

... ("second_16", c_int, 16)]

...

print Int.first_16

print Int.second_16

15.17.1.13. Arrays

Arrays are sequences, containing a fixed number of instances of the same type.

The recommended way to create array types is by multiplying a data type with a positive integer:

TenPointsArrayType = POINT * 10

Here is an example of an somewhat artificial data type, a structure containing 4 POINTs among other stuff:

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

Instances are created in the usual way, by calling the class:

arr = TenPointsArrayType()

for pt in arr:

print pt.x, pt.y

The above code print a series of 0 0 lines, because the array contents is initialized to zeros.

Initializers of the correct type can also be specified:

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,

...

1 2 3 4 5 6 7 8 9 10

15.17.1.14. Pointers

Pointer instances are created by calling the pointer() function on a ctypes type:

from ctypes import *

i = c_int(42)

pi = pointer(i)

Pointer instances have a contents attribute which returns the object to which the pointer points, the i object above:

pi.contents

c_long(42)

Note that ctypes does not have OOR (original object return), it constructs a new, equivalent object each time you retrieve an attribute:

pi.contents is i

False

pi.contents is pi.contents

False

Assigning another c_int instance to the pointer’s contents attribute would cause the pointer to point to the memory location where this is stored:

i = c_int(99)

pi.contents = i

pi.contents

c_long(99)

Pointer instances can also be indexed with integers:

pi[0]

99

Assigning to an integer index changes the pointed to value:

print i

c_long(99)

pi[0] = 22

print i

c_long(22)

It is also possible to use indexes different from 0, but you must know what you’re doing, just as in C: You can access or change arbitrary memory locations. Generally you only use this feature if you receive a pointer from a C function, and you know that the pointer actually points to an array instead of a single item.

Behind the scenes, the pointer() function does more than simply create pointer instances, it has to create pointer types first. This is done with the POINTER() function, which accepts any ctypes type, and returns a new type:

PI = POINTER(c_int)

PI

<class 'ctypes.LP_c_long'>

PI(42)

Traceback (most recent call last):

File "", line 1, in ?

TypeError: expected c_long instead of int

PI(c_int(42))

<ctypes.LP_c_long object at 0x...>

Calling the pointer type without an argument creates a NULL pointer. NULL pointers have a False boolean value:

null_ptr = POINTER(c_int)()

print bool(null_ptr)

False

ctypes checks for NULL when dereferencing pointers (but dereferencing invalid non-NULL pointers would crash 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

15.17.1.15. Type conversions

Usually, ctypes does strict type checking. This means, if you have POINTER(c_int) in the argtypes list of a function or as the type of a member field in a structure definition, only instances of exactly the same type are accepted. There are some exceptions to this rule, where ctypes accepts other objects. For example, you can pass compatible array instances instead of pointer types. So, for POINTER(c_int), ctypes accepts an array of 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

In addition, if a function argument is explicitly declared to be a pointer type (such as POINTER(c_int)) in argtypes, an object of the pointed type (c_int in this case) can be passed to the function. ctypes will apply the required byref() conversion in this case automatically.

To set a POINTER type field to NULL, you can assign None:

bar.values = None

Sometimes you have instances of incompatible types. In C, you can cast one type into another type. ctypes provides a cast() function which can be used in the same way. The Bar structure defined above accepts POINTER(c_int) pointers or c_int arrays for its values field, but not instances of other types:

bar.values = (c_byte * 4)()

Traceback (most recent call last):

File "", line 1, in ?

TypeError: incompatible types, c_byte_Array_4 instance instead of LP_c_long instance

For these cases, the cast() function is handy.

The cast() function can be used to cast a ctypes instance into a pointer to a different ctypes data type. cast() takes two parameters, a ctypes object that is or can be converted to a pointer of some kind, and a ctypes pointer type. It returns an instance of the second argument, which references the same memory block as the first argument:

a = (c_byte * 4)()

cast(a, POINTER(c_int))

<ctypes.LP_c_long object at ...>

So, cast() can be used to assign to the values field of Bar the structure:

bar = Bar()

bar.values = cast((c_byte * 4)(), POINTER(c_int))

print bar.values[0]

0

15.17.1.16. Incomplete Types

Incomplete Types are structures, unions or arrays whose members are not yet specified. In C, they are specified by forward declarations, which are defined later:

struct cell; /* forward declaration */

struct cell {

char *name;

struct cell *next;

};

The straightforward translation into ctypes code would be this, but it does not work:

class cell(Structure):

... fields = [("name", c_char_p),

... ("next", POINTER(cell))]

...

Traceback (most recent call last):

File "", line 1, in ?

File "", line 2, in cell

NameError: name 'cell' is not defined

because the new class cell is not available in the class statement itself. In ctypes, we can define the cell class and set the fields attribute later, after the class statement:

from ctypes import *

class cell(Structure):

... pass

...

cell.fields = [("name", c_char_p),

... ("next", POINTER(cell))]

Lets try it. We create two instances of cell, and let them point to each other, and finally follow the pointer chain a few times:

c1 = cell()

c1.name = "foo"

c2 = cell()

c2.name = "bar"

c1.next = pointer(c2)

c2.next = pointer(c1)

p = c1

for i in range(8):

... print p.name,

... p = p.next[0]

...

foo bar foo bar foo bar foo bar

15.17.1.17. Callback functions

ctypes allows creating C callable function pointers from Python callables. These are sometimes called callback functions.

First, you must create a class for the callback function, the class knows the calling convention, the return type, and the number and types of arguments this function will receive.

The CFUNCTYPE factory function creates types for callback functions using the normal cdecl calling convention, and, on Windows, the WINFUNCTYPE factory function creates types for callback functions using the stdcall calling convention.

Both of these factory functions are called with the result type as first argument, and the callback functions expected argument types as the remaining arguments.

I will present an example here which uses the standard C library’s qsort() function, this is used to sort items with the help of a callback function. qsort() will be used to sort an array of integers:

IntArray5 = c_int * 5

ia = IntArray5(5, 1, 7, 33, 99)

qsort = libc.qsort

qsort.restype = None

qsort() must be called with a pointer to the data to sort, the number of items in the data array, the size of one item, and a pointer to the comparison function, the callback. The callback will then be called with two pointers to items, and it must return a negative integer if the first item is smaller than the second, a zero if they are equal, and a positive integer else.

So our callback function receives pointers to integers, and must return an integer. First we create the type for the callback function:

CMPFUNC = CFUNCTYPE(c_int, POINTER(c_int), POINTER(c_int))

For the first implementation of the callback function, we simply print the arguments we get, and return 0 (incremental development