Python调用c/c++动态库（一）
2020.6.22更新：
增加了部分案例，并在python2和python3下都进行了调试。
——————————————————————————————————————————
因为工作需求，最近要使用python在linux环境下调用c/c++的动态库，执行动态库中的函数。这种没接触过的内容，自然首先开启百度谷歌大法。经过一番搜索，尝试使用python的ctypes模块。
一、初识
首先自然是查询文档了。附文档链接：https://docs.python.org/zh-cn/2.7/library/ctypes.html
python2.7文档描述：“ctypes is a foreign function library for Python. It provides C compatible data types, and allows calling functions in DLLs or shared libraries. It can be used to wrap these libraries in pure Python.”
大意是ctypes是python的一个外部函数库，提供了c的兼容数据类型，允许调用DLL或者共享库中的函数。通过该模块能以纯python的代码对这些库进行封装（最后这句话不理解 =_=，看别人的文章，说是这样你就可以直接 import xxx 来使用这些函数库了）。
可知ctypes只提供了c的兼容，因此若是c++代码，需要使其以c的方式进行编译。
（想了解如何用c的方式编译c++代码，见链接：c方式编译c++）
二、使用
注明：本文均采用python2.7版本
新增了python3的调试，除了str编码内容，其余无需变动
看了文档，就要开始使用了。根据我遇到的使用场景，主要有3个步骤需要处理。
0_0
1.动态库的引入
这一步操作很简单，只需调用方法LoadLibrary，查看文档：
LoadLibrary(name)：Load a shared library into the process and return it. This method always returns a new instance of the library.
加载动态库到进程中并返回其实例对象，该方法每次都会返回一个新的实例。
举个栗子，编写如下代码：
# -*- coding: utf-8 -*-
from ctypes import *
#引入动态库libDemo.so
library = cdll.LoadLibrary("./libDemo.so")
2.函数的声明和调用
因为ctypes只能调用C编译成的库，因此不支持重载，需要在程序中显式定义函数的参数类型和返回类型。
不过在介绍前，需要先了解ctypes的基本数据类型
该表格列举了ctypes、c和python之间基本数据的对应关系，在定义函数的参数和返回值时，需记住几点：
- 必须使用ctypes的数据类型
- 参数类型用关键字argtypes定义，返回类型用restype定义,其中argtypes必须是一个序列，如tuple或list，否则会报错
- 若没有显式定义参数类型和返回类型，python默认为int型
举个栗子：
/******C端代码*********/
#include
#include
#include
#include "demo.h"
int hello()
{
printf("Hello world\n");
return 0;
}
编写c端代码demo.c， 用GCC指令编译成动态库libDemo.so ：gcc -fPIC -shared -o libDemo.so demo.c
编写python端代码linkTest.py进行调用：
# -*- coding: utf-8 -*-
from ctypes import *
#引入动态库libDemo.so
library = cdll.LoadLibrary("./libDemo.so")
library.hello()
执行结果：
3.C语言和python之间数据类型的转换
这部分内容是当初学习的重点，踩了不少坑。
3.1 基本数据类型
这部分已经在上面提到过了，根据对应表格进行转换使用即可。
样例代码在上述demo.c和linkTest.py中继续添加：
C端代码：
......(省略上述代码）
int basicTest(int a, float b)
{
printf("a=%d\n", a);
printf("b=%f\n", b);
return 100;
}
python端代码
def c_basic_test():
library.basicTest.argtypes = [c_int, c_float]
library.basicTest.restype = c_void_p
a = c_int(10)
b = c_float(12.34)
library.basicTest(a, b)
执行结果：
3.1-增加 字符指针及数组类型
c代码：
void arrayTest(char * pStr, unsigned char *puStr)
{
int i = 0;
printf("%s\n", pStr);
for (i = 0; i < 10; i++) {
printf("%c ", puStr[i]);
}
printf("\n");
}
python代码：
该样例有几个注意点：
<1>使用了ctypes的create_string_buffer和from_buffer_copy函数。
create_string_buffer函数会分配一段内存，产生一个c_char类型的字符串，并以NULL结尾。
同理有个类似函数create_unicode_buffer函数，返回的是c_wchar类型
from_buffer_copy函数则是创建一个ctypes实例，并将source参数内容拷贝进去
<2>python2与python3的字符差异：
python2默认都是ascii编码，python3中str类型默认是unicode类型，而ctypes参数需传入bytes-like object(提示这么说的)。因此python3中的字符串都需转换编码，如样例所示。
def c_array_test():
# 以下两方法皆可,但需显式说明c_ubyte数组的大小,个人感觉不方便，求指导
# library.arrayTest.argtypes = [c_char_p, c_ubyte*16]
library.arrayTest.argtypes = [c_char_p, POINTER(c_ubyte * 16)]
library.arrayTest.restype = c_void_p
# python2
# str_info = create_string_buffer("Fine,thank you")
# python3,str都是unicode格式，需转为其余编码，可使用encode函数或b前缀
# 以下两种方法皆可
str_info = create_string_buffer(b"Fine,thank you")
str_info = create_string_buffer("Fine,thank you".encode('utf-8'))
# 调用类型需配套
u_str_info = (c_ubyte * 16).from_buffer_copy(b'0123456789abcdef')
# library.arrayTest(str_info, u_str_info)
library.arrayTest(str_info, byref(u_str_info))
执行结果：
3.2 指针
- 一级指针
指针是c语言中的重要内容，难免要经常使用。因为我处理的主要是api接口的转换，涉及的指针处理就是定义指针类型、获取地址或值，而ctypes中都提供了相应的函数。
在上面的对应表格中，我们可以看到char * 和 void * 已经有专用类型了，直接使用即可，对于其他类型的指针，ctypes提供了两种定义方式：pointer 和POINTER。
查询文档：
ctypes.POINTER(type)
This factory function creates and returns a new ctypes pointer type. Pointer types are cached and reused internally, so calling this function repeatedly is cheap. type must be a ctypes type.
ctypes.pointer(obj)
This function creates a new pointer instance, pointing to obj. The returned object is of the type POINTER(type(obj)).
大意是POINTER必须传入ctypes类型，创建出新的ctypes 指针类型（pointer type），而pointer传入一个对象，创建出一个新的指针实例。可见POINTER创建出了pointer，我一般选择POINTER来使用（具体差别还没太多研究。。=_=).
传输地址，ctypes提供了byref函数：
ctypes.byref(obj[, offset])
Returns a light-weight pointer to obj, which must be an instance of a ctypes type. offset defaults to zero, and must be an integer that will be added to the internal pointer value.
…
The returned object can only be used as a foreign function call parameter. It behaves similar to pointer(obj), but the construction is a lot faster.
大意是返回一个指向ctypes实例对象的轻量级指针，函数中还可以通过参数（必须是int）来设置偏移地址,这个返回的对象只能用于外部函数调用的参数。
有了这几个函数，指针就能实现啦。见实例：
C端代码
void pointerTest(int * pInt, float * pFloat)
{
*pInt = 10;
*pFloat = 12.34;
}
python端代码
def c_pointer_test():
library.pointerTest.argtypes = [POINTER(c_int), POINTER(c_float)]
library.pointerTest.restype = c_void_p
int_a = c_int(0)
float_b = c_float(0)
library.pointerTest(byref(int_a), byref(float_b))
print("out_a:", int_a.value)
print("out_b:", float_b.value)
可见我们在python中预设的值都在函数中被更改了，指针有效。
- 补充样例：外部传输字符空间，在函数内部进行操作
c代码：
void mallocTest(char *pszStr)
{
strcpy(pszStr, "Happay Children's Day!");
}
python代码：
def c_malloc_test():
library.mallocTest.argtypes = [c_char_p]
library.mallocTest.restype = c_void_p
word = (c_char * 32)()
library.mallocTest(word)
print("out_word:", word.value)
执行成功！
- 二级指针
在实际应用中，我处理的二级指针是在c端接口传送一个char*指针的地址作为参数，在接口中给char * 指针分配空间和赋值。
根据指针的功能，很容易实现，见实例。
c端接口代码
/**函数定义*/
void doublePointTest(int ** ppInt, char ** ppStr)
{
printf("before int:%d\n", **ppInt);
**ppInt = 10086;
*ppStr = (char*)malloc(10 * sizeof(char));
strcpy(*ppStr, "Happy National Day!");
}
//释放函数
void freePoint(void *pt) {
if (pt != NULL) {
free(pt);
pt = NULL;
}
}
/**函数调用,运行会输出接口中复制的字符串*/
int useDoublePoint()
{
int num_e = 10;
int * pInt = &num_e;
char *pStr_b = NULL;
doublePointTest(&pInt, &pStr_b);
printf("after int:%d\n", *pInt);
printf("out str:%s\n", pStr_b);
//必须释放动态内存
freePoint(pStr_b);
}
python端代码
# 函数定义及测试
def c_double_point_and_free_test():
library.doublePointTest.argtypes = [POINTER(POINTER(c_int)), POINTER(c_char_p)]
library.doublePointTest.restype = c_void_p
library.freePoint.argtypes = [c_void_p]
library.freePoint.restype = c_void_p
int_a = c_int(10)
# 注意POINTER和pointer的区别，因为POINTER必须指向ctypes类型，此处只能用pointer
int_pt = pointer(int_a)
word_pt = c_char_p()
library.doublePointTest(byref(int_pt), byref(word_pt))
print("out_word:", word_pt.value)
# contents是指针内容
print("out_value:", int_pt.contents.value)
library.freePoint(word_pt)
执行结果：
另一个c端接口，需要传入一个char* 指针的地址，出参为这个指针指向的内容和内容长度。该接口用于处理图片的rgb值，因此内容都是0-255的值，样例代码如下
......(省略上述代码)
#define LENGTH 8
void doubleUnsignedPointerTest( char ** ppChar, int *num )
{
int i;
*num = LENGTH;
*ppChar = (char*)malloc(LENGTH*sizeof(char));
for(i=0;iC端调用代码
int num = 0, i;
doubleUnsignedPointerTest(&pChar, &num);
for(i=0;i这时python端若使用c_char_p来构造类似上述的代码，在输出时会提示超出范围异常（out of range）。
查询了文档，原因在于：
class ctypes.c_char_p
Represents the C char * datatype when it points to a zero-terminated string…
（大意是c_char_p指针必须指向’\0’结尾的字符串。因此输出时遇到了第一个’\0’就中断了）
所以根据对应表格，使用POINTER嵌套构造了双重指针，使用后无误
python端代码
......(省略上述代码)
library.doubleUnendPointerTest.argtypes = [POINTER(POINTER(c_byte)), POINTER(c_int)]
library.doubleUnendPointerTest.restype = c_void_p
num = c_int(0)
word_pt = POINTER(c_byte)() #若使用c_char类型，在下面输出时会以字符类型输出，有乱码，因此选择c_byte
library.doubleUnendPointerTest(byref(word_pt), byref(num))
print "num:", num.value
for i in range(8):
print "key:", i, " value:", word_pt[i]
执行结果:
3.3 结构体、共用体
结构体、共用体是c中常用类型，使用前需要先定义其成员类型，在python中也是同样的处理。查看文档：
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.
大意是结构体和共用体必须继承Sturcture和Unino类，定义其成员必须使用_field_属性。该属性是一个list，其成员都是2个值的tuple，分别是每个结构体/共用体成员的类型和长度，而且定义类型必须使用ctype类型或由ctype组合而成的新类型。
以此写个样例：
c端代码
//结构体
typedef struct _rect
{
int index;
char info[16];
}Rect;
<1>读取结构体
C代码：
int readRect(Rect rect)
{
printf("value=============\n");
printf("index:%d\ninfo:%s\n", rect.index, rect.info);
return 0;
}
python代码：
def c_read_rect():
library.readRect.argtypes = [Rect]
library.readRect.restype = c_void_p
rect_a = Rect(10, b"Hello")
library.readRect(rect_a)
<2>读取结构体，传参为指针
C代码：
int readRectPoint(Rect * pRect)
{
printf("point==============\n");
printf("index:%d\n", pRect->index);
printf("info:%s\n", pRect->info);
return 0;
}
python代码：
def c_read_rect_point():
library.readRectPoint.argtypes = [POINTER(Rect)]
library.readRectPoint.restype = c_void_p
rect_a = Rect(10, b"Hello")
library.readRectPoint(byref(rect_a))
<3>类似，可以传输结构体数组给动态库，实质是传输结构体数组指针，也就是首元素指针
C代码：
void readRectArray(Rect *pRectArray)
{
int i;
for(i=0;i<5;i++)
{
printf("pRectArray.index:%d\n", pRectArray[i].index);
printf("pRectArray.info:%s\n", pRectArray[i].info);
}
}
python代码：
def c_read_rect_array():
library.readRectArray.argtypes = [POINTER(Rect)]
library.readRectArray.restype = c_void_p
rect_array = (Rect * 5)()
for i in range(5):
# python2
# rect_array[i] = Rect(i, "Hello_" + str(i))
# python3
rect_array[i] = Rect(i, bytes("Hello_"+str(i), encoding='utf-8') )
# 以下两方法皆可
# library.readRectArray(rect_array)
library.readRectArray(byref(rect_array[0]))
执行结果：
<4> 从动态库中获取结构体数组内容
C代码：
/**函数定义*/
Rect * obtainRectArray(int *pArrayNum)
{
int num = 5;
*pArrayNum = num;
Rect *pArray = (Rect*)malloc(num * sizeof(Rect));
for (int i = 0; i < num; i++) {
pArray[i].index = i;
sprintf(pArray[i].info,"%s_%d", "Hello", i);
}
return pArray;
}
//必须释放内存
void freeRect(Rect *pRect)
{
free(pRect);
}
/**c中调用方式*/
void testObtainRectArray(int *num)
{
int num = 0;
Rect *pstRectArray = obtainRectArray(&num);
for (int i = 0; i < num; i++) {
printf("index:%d\n", pstRectArray[i].index);
printf("info:%s\n", pstRectArray[i].info);
}
freeRect(pstRectArray);
}
python代码：
ctypes的pointer有一个contents方法，通过该方法可以获取指针的内容。但在这个样例中，contents只能获取首元素的内容，后来才发现竟然能循环读取= =
def c_obtain_rect_array_and_free():
library.obtainRectArray.argtypes = [POINTER(c_int)]
# library.obtainRectArray.restype = Array()
library.obtainRectArray.restype = POINTER(Rect)
library.freeRect.argtypes = [POINTER(Rect)]
library.freeRect.restype = c_void_p
num = c_int(10)
rect_pt = library.obtainRectArray(byref(num))
num = num.value
print("num:", num)
# 这种赋值方法是真的没想到,找了好久= = 之前一直在rect_pt.contents上面绕
# rect_pt.contents只能输出首元素的内容，如rect_pt.contents.index
rect_array = [rect_pt[i] for i in range(num)]
for item in rect_array:
print("index:", item.index)
print("info:", item.info)
library.freeRect(rect_pt)
执行结果：
三、结语
通过文档，python调用C动态库还是比较容易实现的，只是第一次使用没有经验，摸索了一段时间。其实文档还有很多内容，待后续再慢慢学习吧。
附源码:https://pan.baidu.com/s/10dUqfrVQYYDDFTgNAa0Pmw
提取码: yctx
四、补充
1，动态库so中的函数，如fun_add，可能使用了c++的函数模块，直接增加extern "C"无法编译，可以再封装一层函数，如fun_c_add，该函数直接调用fun_add函数，则fun_c_add可以增加extern "C"编译通过，python也可调用；
2，特殊的函数指针，如unsigned char *，转化为python，函数的定义参数格式是POINTER(c_ubyte)，较为复杂，可以用c_void_p类型代替。