koffi - npm Package Compare versions

Comparing version 2.6.12 to 2.7.0

CHANGELOG.md

@@ -5,2 +5,10 @@ # Changelog
 
+### Koffi 2.7
+
+#### Koffi 2.7.0 (2023-12-21)
+
+- Support alternative [callback calling convention](callbacks.md#callback-types) in classic syntax
+- Change syntax for [calling conventions](functions.md#calling-conventions) with classic syntax
+- Drop unused "internal" property from Koffi
+
 ### Koffi 2.6
@@ -7,0 +15,0 @@

doc/callbacks.md

@@ -11,2 +11,4 @@ # Javascript callbacks
 
+*Changed in Koffi 2.7*
+
 In order to pass a JS function to a C function expecting a callback, you must first create a callback type with the expected return type and parameters. The syntax is similar to the one used to load functions from a shared library.
@@ -25,2 +27,19 @@
 
+For alternative [calling conventions](functions.md#calling-conventions) (such as `stdcall` on Windows x86 32-bit), you can specify as the first argument with the classic syntax, or after the return type in prototype strings, like this:
+
+```js
+const HANDLE = koffi.pointer('HANDLE', koffi.opaque());
+const HWND = koffi.alias('HWND', HANDLE);
+
+// These two declarations work the same, and use the __stdcall convention on Windows x86
+const EnumWindowsProc = koffi.proto('bool __stdcall EnumWindowsProc (HWND hwnd, long lParam)');
+const EnumWindowsProc = koffi.proto('__stdcall', 'EnumWindowsProc', 'bool', ['HWND', 'long']);
+```
+
+```{warning}
+You have to make sure you **get the calling convention right** (such as specifying __stdcall for a Windows API callback), or your code will crash on Windows 32-bit.
+
+Before Koffi 2.7, it was *impossible to use an alternative callback calling convention with the classic syntax*. Use a prototype string or *upgrade to Koffi 2.7* to solve this limitation.
+```
+
 Once your callback type is declared, you can use a pointer to it in struct definitions, as function parameters and/or return types, or to call/decode function pointers.
@@ -27,0 +46,0 @@

doc/functions.md

@@ -86,2 +86,4 @@ # Function calls
 
+*Changed in Koffi 2.7*
+
 By default, calling a C function happens synchronously.
@@ -91,11 +93,17 @@
 
- Convention   | Classic form                  | Prototype form | Description
-------------- | ----------------------------- | -------------- | -------------------------------------------------------------------
- **Cdecl**    | `koffi.cdecl` or `koffi.func` | _(default)_    | This is the default convention, and the only one on other platforms
- **Stdcall**  | `koffi.stdcall`               | __stdcall      | This convention is used extensively within the Win32 API
- **Fastcall** | `koffi.fastcall`              | __fastcall     | Rarely used, uses ECX and EDX for first two parameters
- **Thiscall** | `koffi.thiscall`              | __thiscall     | Rarely used, uses ECX for first parameter
+ Convention   | Classic form                                  | Prototype form | Description
+------------- | --------------------------------------------- | -------------- | -------------------------------------------------------------------
+ **Cdecl**    | `koffi.func(name, ret, params)`               | _(default)_    | This is the default convention, and the only one on other platforms
+ **Stdcall**  | `koffi.func('__stdcall', name, ret, params)`  | __stdcall      | This convention is used extensively within the Win32 API
+ **Fastcall** | `koffi.func('__fastcall', name, ret, params)` | __fastcall     | Rarely used, uses ECX and EDX for first two parameters
+ **Thiscall** | `koffi.func('__thiscall', name, ret, params)` | __thiscall     | Rarely used, uses ECX for first parameter
 
 You can safely use these on non-x86 platforms, they are simply ignored.
 
+```{note}
+Support for specifying the convention as the first argument of the classic form was introduced in Koffi 2.7.
+
+In earlier versions, you had to use `koffi.stdcall()` and similar functions. These functions are still supported but deprecated, and will be removed in Koffi 3.0.
+```
+
 Below you can find a small example showing how to use a non-default calling convention, with the two syntaxes:
@@ -110,3 +118,3 @@
 // The following two declarations are equivalent, and use stdcall on x86 (and the default ABI on other platforms)
-const MessageBoxA_1 = lib.stdcall('MessageBoxA', 'int', ['void *', 'str', 'str', 'uint']);
+const MessageBoxA_1 = lib.func('__stdcall', 'MessageBoxA', 'int', ['void *', 'str', 'str', 'uint']);
 const MessageBoxA_2 = lib.func('int __stdcall MessageBoxA(void *hwnd, str text, str caption, uint type)');
@@ -113,0 +121,0 @@ ```

doc/start.md

@@ -102,4 +102,4 @@ # Get started
 // Find functions
-const MessageBoxA = lib.stdcall('MessageBoxA', 'int', ['void *', 'str', 'str', 'uint']);
-const MessageBoxW = lib.stdcall('MessageBoxW', 'int', ['void *', 'str16', 'str16', 'uint']);
+const MessageBoxA = lib.func('__stdcall', 'MessageBoxA', 'int', ['void *', 'str', 'str', 'uint']);
+const MessageBoxW = lib.func('__stdcall', 'MessageBoxW', 'int', ['void *', 'str16', 'str16', 'uint']);
 
@@ -106,0 +106,0 @@ let ret = MessageBoxA(null, 'Do you want another message box?', 'Koffi', MB_YESNO | MB_ICONQUESTION);

index.d.ts

@@ -70,15 +70,13 @@ // Copyright 2023 Niels Martignène <[e-mail]>
         func(name: string, result: TypeSpec, arguments: TypeSpec[]): KoffiFunction;
+        func(convention: string, name: string, result: TypeSpec, arguments: TypeSpec[]): KoffiFunction;
 
-        cdecl(definition: string): KoffiFunction;
-        cdecl(name: string, result: TypeSpec, arguments: TypeSpec[]): KoffiFunction;
+        /** @deprecated */ cdecl(definition: string): KoffiFunction;
+        /** @deprecated */ cdecl(name: string, result: TypeSpec, arguments: TypeSpec[]): KoffiFunction;
+        /** @deprecated */ stdcall(definition: string): KoffiFunction;
+        /** @deprecated */ stdcall(name: string, result: TypeSpec, arguments: TypeSpec[]): KoffiFunction;
+        /** @deprecated */ fastcall(definition: string): KoffiFunction;
+        /** @deprecated */ fastcall(name: string, result: TypeSpec, arguments: TypeSpec[]): KoffiFunction;
+        /** @deprecated */ thiscall(definition: string): KoffiFunction;
+        /** @deprecated */ thiscall(name: string, result: TypeSpec, arguments: TypeSpec[]): KoffiFunction;
 
-        stdcall(definition: string): KoffiFunction;
-        stdcall(name: string, result: TypeSpec, arguments: TypeSpec[]): KoffiFunction;
-
-        fastcall(definition: string): KoffiFunction;
-        fastcall(name: string, result: TypeSpec, arguments: TypeSpec[]): KoffiFunction;
-
-        thiscall(definition: string): KoffiFunction;
-        thiscall(name: string, result: TypeSpec, arguments: TypeSpec[]): KoffiFunction;
-
         symbol(name: string, type: TypeSpec): any;
@@ -122,4 +120,6 @@
     export function proto(name: string, result: TypeSpec, arguments: TypeSpec[]): IKoffiCType;
+    export function proto(convention: string, name: string, result: TypeSpec, arguments: TypeSpec[]): IKoffiCType;
     /** @deprecated */ export function callback(definition: string): IKoffiCType;
     /** @deprecated */ export function callback(name: string, result: TypeSpec, arguments: TypeSpec[]): IKoffiCType;
+    /** @deprecated */ export function callback(convention: string, name: string, result: TypeSpec, arguments: TypeSpec[]): IKoffiCType;
 
@@ -126,0 +126,0 @@ export function register(callback: Function, type: TypeSpec): IKoffiRegisteredCallback;

index.js

@@ -381,4 +381,4 @@ "use strict";
       name: "koffi",
-      version: "2.6.12",
-      stable: "2.6.12",
+      version: "2.7.0",
+      stable: "2.7.0",
       description: "Fast and simple C FFI (foreign function interface) for Node.js",
@@ -561,1 +561,10 @@ keywords: [
 };
+var load = module.exports.load;
+module.exports.load = (...args) => {
+  let lib = load(...args);
+  lib.cdecl = util.deprecate((...args2) => lib.func("__cdecl", ...args2), "The koffi.stdcall() function was deprecated in Koffi 2.7, use koffi.func(...) instead", "KOFFI003");
+  lib.stdcall = util.deprecate((...args2) => lib.func("__stdcall", ...args2), 'The koffi.stdcall() function was deprecated in Koffi 2.7, use koffi.func("__stdcall", ...) instead', "KOFFI004");
+  lib.fastcall = util.deprecate((...args2) => lib.func("__fastcall", ...args2), 'The koffi.fastcall() function was deprecated in Koffi 2.7, use koffi.func("__fastcall", ...) instead', "KOFFI005");
+  lib.thiscall = util.deprecate((...args2) => lib.func("__thiscall", ...args2), 'The koffi.thiscall() function was deprecated in Koffi 2.7, use koffi.func("__thiscall", ...) instead', "KOFFI006");
+  return lib;
+};

indirect.js

@@ -381,4 +381,4 @@ "use strict";
       name: "koffi",
-      version: "2.6.12",
-      stable: "2.6.12",
+      version: "2.7.0",
+      stable: "2.7.0",
       description: "Fast and simple C FFI (foreign function interface) for Node.js",
@@ -481,1 +481,10 @@ keywords: [
 };
+var load = module.exports.load;
+module.exports.load = (...args) => {
+  let lib = load(...args);
+  lib.cdecl = util.deprecate((...args2) => lib.func("__cdecl", ...args2), "The koffi.stdcall() function was deprecated in Koffi 2.7, use koffi.func(...) instead", "KOFFI003");
+  lib.stdcall = util.deprecate((...args2) => lib.func("__stdcall", ...args2), 'The koffi.stdcall() function was deprecated in Koffi 2.7, use koffi.func("__stdcall", ...) instead', "KOFFI004");
+  lib.fastcall = util.deprecate((...args2) => lib.func("__fastcall", ...args2), 'The koffi.fastcall() function was deprecated in Koffi 2.7, use koffi.func("__fastcall", ...) instead', "KOFFI005");
+  lib.thiscall = util.deprecate((...args2) => lib.func("__thiscall", ...args2), 'The koffi.thiscall() function was deprecated in Koffi 2.7, use koffi.func("__thiscall", ...) instead', "KOFFI006");
+  return lib;
+};

package.json

 {
     "name": "koffi",
-    "version": "2.6.12",
-    "stable": "2.6.12",
+    "version": "2.7.0",
+    "stable": "2.7.0",
     "description": "Fast and simple C FFI (foreign function interface) for Node.js",
@@ -6,0 +6,0 @@ "keywords": [

No alert changes

Improved metrics

Lines of code

8416

increased by0.25%

Worsened metrics

Total package byte prevSize

69664827

decreased by-0.08%

No dependency changes