Node-ffi (Foreign Function Interface)是一个Node.js的轻量级模块,可以让Node.js轻松地调用动态链接库中的函数。该模块为Node.js与外部C/C++库交互提供了简便、快捷的方式,提供了一种翻译C语言API到JavaScript的机制。下面从多个方面对Node-ffi进行详细介绍。
一、安装Node-ffi
Node-ffi是一个npm模块,安装非常简单,只需在终端中输入以下命令即可:
npm install ffi
安装完毕后,只需在项目中引入即可:
const ffi = require("ffi");
二、使用Node-ffi
1. Node-ffi的简单示例
下面是一个简单的示例,用于展示如何使用Node-ffi调用C库函数:
const ffi = require("ffi");
let libm = ffi.Library("libm.so.6", {
"ceil": ["double", ["double"]] //ceil为C库中的函数名,["double", ["double"]]为C语言函数的返回值类型和参数列表
});
libm.ceil(1.5); // Node.js可以调用 C 库函数
由于ceil是math.h工具库中的一个函数,因此我们需要在调用前将其添加到libm对象中。Library函数的第一个参数是所需C库文件的名称或完整路径。由于math.h是标准C库的一部分,因此该库被链接到所有C程序中,包括我们所编写的JavaScript文件。该示例使用了libm.so.6文件。
2. 将C结构映射到Node.js结构体
在C应用程序中,结构体是一种用于组合数据类型的机制。使用Node-ffi时,我们必须将C结构映射到Node.js结构体。 这是一个由C结构体定义的示例:
struct Network {
double bias;
double weights[10];
};
要将其映射到Node.js结构体,我们可以使用ref模块来声明类型:
let ref = require("ref");
let StructType = require("ref-struct");
let Network = StructType({
bias: "double", // 结构体中的字段名称和类型
weights: ref.refType("double"), //指针类型的字段
});
注意,weights字段被定义为指针类型, 因此我们需要通过ref模块的refType方法来声明。 创建一个C语言结构体的示例:
let net = new Network();
net.bias = 0.1;
net.weights[0] = 0.2;
net.weights[1] = 0.3;
3. 将C函数返回的指针转换为JavaScript Buffer
有时,C函数可能会返回指针类型的数据。如果我们需要在JavaScript中对此数据进行操作,我们需要将返回的指针转换为JavaScript Buffer对象。 请看以下示例: 在C应用程序中,我们有一个函数返回指向double数组的指针:
double *create_array(){
double *arr = (double *)malloc(3 * sizeof(double));
arr[0] = 1.1;
arr[1] = 2.2;
arr[2] = 3.3;
return arr;
}
我们可以使用Node-ffi调用该函数:
let lib = ffi.Library("mylib", {
"create_array": ["pointer", []]
});
let arr = lib.create_array(); //arr是一个指针类型
let size = 3 * ref.sizeof.double; // size为数组的大小
let doubleArray = Buffer.alloc(size); //创建一个新的Buffer,该Buffer可以理解为是一个double指针数组
doubleArray.writeDoubleLE(arr[0], 0); // 将返回的指针中的值写入Buffer
doubleArray.writeDoubleLE(arr[1], 8); // 参数2是写入Buffer的偏移量,8表示下标为1
doubleArray.writeDoubleLE(arr[2], 16);
通过将返回的指针转换为JavaScript Buffer对象,我们就可以在JavaScript中处理C返回的所有数据了。
4. 传递复合类型的参数
如果一个C函数的参数是复合类型,则需要在JavaScript中定义一个结构体,以便在调用该函数时传递正确的参数。 请看下面的示例: 在C应用程序中,我们有一个名为print_person()的函数,它需要Person结构作为参数:
struct Person {
char *name;
int age;
double salary;
};
void print_person(struct Person p){
printf("Name: %s, Age: %d, Salary: %f", p.name, p.age, p.salary);
}
在Node.js中,我们必须先定义一个相对应的Person结构体,然后使用该结构体作为函数的参数:
let Person = StructType({
name: "string",
age: "int",
salary: "double"
});
let person = new Person();
person.name = "Tom";
person.age = 30;
person.salary = 50000;
let printPerson = ffi.Library("mylib", {
"print_person": ["void", [Person]]
});
printPerson.print_person(person);
5. 应将C字符串返回转换为JavaScript字符串
在C中,字符串是由字符数组表示的,结尾会附有一个空字符('\0')。当C程序返回一个字符串时,它实际上是返回了一个指向字符数组的指针。 这是一个简单的返回字符串的C函数示例:
char *get_string(int id){
if (id == 0) {
return "Hello World";
} else {
return "Node.js is awesome";
}
}
我们可以使用Node-ffi调用该函数:
let lib = ffi.Library("mylib", {
"get_string": ["string", ["int"]]
});
let str = lib.get_string(1); // str是c字符串
let offset = str.indexOf("\0");
if (offset != -1) {
str = str.slice(0,offset); //截取字符串直到"\0"
}
需要注意的是,在JavaScript中,我们需要手动去除C字符数组末尾的空字符.
三、总结
Node-ffi可以为Node.js提供一种与外部C/C++库交互的简便方式。该模块适用于需要带有高性能C/C++代码的应用程序,但同时不想牺牲Node.js中所带来的其他便利功能的情况。我们可以使用Node-ffi的API轻松地从Node.js中调用现有的C代码,这使得我们能够利用已经存在的模块,而无需使用Node.js重新实现这些模块。Node-ffi扩展了Node.js,并提供了C和JavaScript之间无缝互操作所需的翻译功能。