Get started#
Install Koffi#
You can install Koffi with npm:
1npm install koffi
Once you have installed Koffi, you can start by loading it:
1// CommonJS syntax
2const koffi = require('koffi');
3
4// ES6 modules
5import koffi from 'koffi';
Simple examples#
Below you can find two examples:
The first one runs on Linux. The functions are declared with the C-like prototype language.
The second one runs on Windows, and uses the node-ffi like syntax to declare functions.
For Linux#
This is a small example for Linux systems, which uses gettimeofday()
, localtime_r()
and printf()
to print the current time.
It illustrates the use of output parameters.
1// ES6 syntax: import koffi from 'koffi';
2const koffi = require('koffi');
3
4// Load the shared library
5const lib = koffi.load('libc.so.6');
6
7// Declare struct types
8const timeval = koffi.struct('timeval', {
9 tv_sec: 'unsigned int',
10 tv_usec: 'unsigned int'
11});
12const timezone = koffi.struct('timezone', {
13 tz_minuteswest: 'int',
14 tz_dsttime: 'int'
15});
16const time_t = koffi.struct('time_t', { value: 'int64_t' });
17const tm = koffi.struct('tm', {
18 tm_sec: 'int',
19 tm_min: 'int',
20 tm_hour: 'int',
21 tm_mday: 'int',
22 tm_mon: 'int',
23 tm_year: 'int',
24 tm_wday: 'int',
25 tm_yday: 'int',
26 tm_isdst: 'int'
27});
28
29// Find functions
30const gettimeofday = lib.func('int gettimeofday(_Out_ timeval *tv, _Out_ timezone *tz)');
31const localtime_r = lib.func('tm *localtime_r(const time_t *timeval, _Out_ tm *result)');
32const printf = lib.func('int printf(const char *format, ...)');
33
34// Get local time
35let tv = {};
36let now = {};
37gettimeofday(tv, null);
38localtime_r({ value: tv.tv_sec }, now);
39
40// And format it with printf (variadic function)
41printf('Hello World!\n');
42printf('Local time: %02d:%02d:%02d\n', 'int', now.tm_hour, 'int', now.tm_min, 'int', now.tm_sec);
For Windows#
This is a small example targeting the Win32 API, using MessageBox()
to show a Hello World! message to the user.
It illustrates the use of the x86 stdcall calling convention, and the use of UTF-8 and UTF-16 string arguments.
1// ES6 syntax: import koffi from 'koffi';
2const koffi = require('koffi');
3
4// Load the shared library
5const lib = koffi.load('user32.dll');
6
7// Declare constants
8const MB_OK = 0x0;
9const MB_YESNO = 0x4;
10const MB_ICONQUESTION = 0x20;
11const MB_ICONINFORMATION = 0x40;
12const IDOK = 1;
13const IDYES = 6;
14const IDNO = 7;
15
16// Find functions
17const MessageBoxA = lib.stdcall('MessageBoxA', 'int', ['void *', 'str', 'str', 'uint']);
18const MessageBoxW = lib.stdcall('MessageBoxW', 'int', ['void *', 'str16', 'str16', 'uint']);
19
20let ret = MessageBoxA(null, 'Do you want another message box?', 'Koffi', MB_YESNO | MB_ICONQUESTION);
21if (ret == IDYES)
22 MessageBoxW(null, 'Hello World!', 'Koffi', MB_ICONINFORMATION);
Bundling Koffi#
Please read the dedicated page for information about bundling and packaging applications using Koffi.