node-ctypes 1.3.0 → 1.5.0

package/README.md

@@ -835,7 +835,7 @@ Base class for Python-like union definitions. Subclasses should define `static _
 | **Unions** | `class U(Union):`<br>&nbsp;&nbsp;`_fields_ = [("i", c_int)]` | `class U extends Union`<br>&nbsp;&nbsp;`{ static _fields_ = [["i", c_int]] }` |
 | **Arrays** | `c_int * 5` | `array(c_int, 5)` |
 | **Bit fields** | `("flags", c_uint, 3)` | `["flags", c_uint32, 3]`<br>**or** `bitfield(c_uint32, 3)` |
-| **Callbacks** | `CFUNCTYPE(c_int, c_int)` | `callback(fn, c_int, [c_int])` |
+| **Callbacks** | `CFUNCTYPE(c_int, c_int)` | `CFUNCTYPE(c_int, c_int)`<br>**or** ` callback(fn, c_int, [c_int])` |
 | **Strings** | `c_char_p(b"hello")` | `create_string_buffer("hello")`<br>**or**<br>`new c_char_p(b"hello")` |
 | **Pointers** | `POINTER(c_int)`<br>`p.contents`<br>`p[0]` | `POINTER(c_int)`<br>`p.contents`<br>`p[0]` |
 | **pointer()** | `pointer(obj)` | `pointer(obj)` |
@@ -902,8 +902,10 @@ npm run bench:koffi        # Benchmark vs koffi
 
 For practical GUI application examples using the Windows API:
 
-- **Simple GUI Demo**: [examples/windows/simple.js](examples/windows/simple.js) - Message boxes and basic Windows API GUI elements
-- **Windows Controls Showcase Demo**: [examples/windows/windows_controls.js](examples/windows/windows_controls.js) - Comprehensive demo with a wide set of common Win32 controls
+- **Windows Controls Showcase Demo**: [examples/windows/demo_controls.js](examples/windows/demo_controls.js) - Comprehensive demo with a wide set of common Win32 controls
+- **Windows Registry Demo**: [examples/windows/demo_registry](examples/windows/demo_registry) - Comprehensive demo with setValue, getValue, openKey, deleteValue, deleteKey
+- **Windows Tray Demo**: [examples/windows/demo_tray.js](examples/windows/demo_tray.js) - Comprehensive demo for tray menu inspired by [pit-ray/fluent-tray](https://github.com/pit-ray/fluent-tray)
+- **WinScard - PC/SC Smart Card**: [examples/demo_scard.js](examples/demo_scard.js) - Comprehensive demo for Windows Smart Card API on Windows and PC/SC Lite (pcsclite) on macOS and Linux
 
 ## License
 

package/lib/core/Library.js

@@ -74,6 +74,15 @@ export function createLibraryClasses(Library, LRUCache, _toNativeType, _toNative
           if (prop === "argtypes") return argtypes;
           if (prop === "restype") return restype;
           if (prop === "errcheck") return cachedFunc ? cachedFunc.errcheck : undefined;
+          if (prop === "callAsync") {
+            if (restype === undefined) {
+              throw new Error(`Function ${name}: restype not set`);
+            }
+            if (!cachedFunc) {
+              cachedFunc = cdll.func(name, restype, argtypes);
+            }
+            return cachedFunc.callAsync;
+          }
           return target[prop];
         },
         set(target, prop, value) {
@@ -172,39 +181,19 @@ export function createLibraryClasses(Library, LRUCache, _toNativeType, _toNative
       let callMethod;
 
       if (argCount === 0) {
-        // FAST PATH: No arguments - direct call
-        callMethod = function () {
-          return ffiFunc.call();
+        // FAST PATH: No declared arguments - but still support variadic
+        callMethod = function (...args) {
+          if (args.length === 0) {
+            return ffiFunc.call();
+          }
+          // Variadic: pass all args directly
+          return ffiFunc.call(...args);
         };
       } else if (allPrimitive) {
-        // FAST PATH: All primitive args - direct call without processing
-        switch (argCount) {
-          case 1:
-            callMethod = function (a0) {
-              return ffiFunc.call(a0);
-            };
-            break;
-          case 2:
-            callMethod = function (a0, a1) {
-              return ffiFunc.call(a0, a1);
-            };
-            break;
-          case 3:
-            callMethod = function (a0, a1, a2) {
-              return ffiFunc.call(a0, a1, a2);
-            };
-            break;
-          case 4:
-            callMethod = function (a0, a1, a2, a3) {
-              return ffiFunc.call(a0, a1, a2, a3);
-            };
-            break;
-          default:
-            // Fallback for many args
-            callMethod = function (...args) {
-              return ffiFunc.call(...args);
-            };
-        }
+        // FAST PATH: All primitive args - use rest args to support variadic
+        callMethod = function (...args) {
+          return ffiFunc.call(...args);
+        };
       } else {
         // SLOW PATH: Has buffer/struct args - need to extract _buffer
         callMethod = function (...args) {
@@ -237,11 +226,54 @@ export function createLibraryClasses(Library, LRUCache, _toNativeType, _toNative
         };
       }
 
+      // =========================================================================
+      // ASYNC WRAPPER: same argument processing, but calls callAsync
+      // Returns a Promise instead of the result directly
+      // =========================================================================
+
+      let asyncCallMethod;
+
+      if (argCount === 0) {
+        asyncCallMethod = function (...args) {
+          if (args.length === 0) {
+            return ffiFunc.callAsync();
+          }
+          // Variadic: pass all args directly
+          return ffiFunc.callAsync(...args);
+        };
+      } else if (allPrimitive) {
+        asyncCallMethod = function (...args) {
+          return ffiFunc.callAsync(...args);
+        };
+      } else {
+        asyncCallMethod = function (...args) {
+          const processedArgs = [];
+
+          for (let i = 0; i < args.length; i++) {
+            const arg = args[i];
+            if (arg && typeof arg === "object") {
+              if (arg._buffer !== undefined && Buffer.isBuffer(arg._buffer)) {
+                processedArgs.push(arg._buffer);
+              } else if (Buffer.isBuffer(arg)) {
+                processedArgs.push(arg);
+              } else {
+                processedArgs.push(arg);
+              }
+            } else {
+              processedArgs.push(arg);
+            }
+          }
+
+          return ffiFunc.callAsync(...processedArgs);
+        };
+      }
+
       // Aggiungi metadata come proprietà non-enumerable per non interferire
       Object.defineProperties(callMethod, {
         funcName: { value: name },
         address: { value: ffiFunc.address },
         _ffi: { value: ffiFunc },
+        callAsync: { value: asyncCallMethod, writable: false, enumerable: false, configurable: false },
         // Esponi errcheck come setter/getter
         errcheck: {
           get() {

package/lib/core/callback.js

@@ -150,8 +150,10 @@ import { _toNativeType, _toNativeTypes } from "./types.js";
  * @throws {Error} If callback creation fails or type conversion fails
  * @see {@link threadSafeCallback} for thread-safe callbacks
  */
-export function callback(fn, returnType, argTypes = [], native) {
-  const cb = new native.Callback(fn, _toNativeType(returnType, native), _toNativeTypes(argTypes, native));
+export function callback(fn, returnType, argTypes = [], native, abi = undefined) {
+  const args = [fn, _toNativeType(returnType, native), _toNativeTypes(argTypes, native)];
+  if (abi) args.push(abi);
+  const cb = new native.Callback(...args);
 
   return {
     get pointer() {
@@ -260,8 +262,10 @@ export function callback(fn, returnType, argTypes = [], native) {
  * @throws {Error} If callback creation fails or type conversion fails
  * @see {@link callback} for main-thread-only callbacks
  */
-export function threadSafeCallback(fn, returnType, argTypes = [], native) {
-  const cb = new native.ThreadSafeCallback(fn, _toNativeType(returnType, native), _toNativeTypes(argTypes, native));
+export function threadSafeCallback(fn, returnType, argTypes = [], native, abi = undefined) {
+  const args = [fn, _toNativeType(returnType, native), _toNativeTypes(argTypes, native)];
+  if (abi) args.push(abi);
+  const cb = new native.ThreadSafeCallback(...args);
 
   return {
     get pointer() {

package/lib/core/funcptr.js

@@ -0,0 +1,188 @@
+/**
+ * @file funcptr.js
+ * @module core/funcptr
+ * @description Function pointer type factories for calling raw function pointers.
+ *
+ * Provides CFUNCTYPE and WINFUNCTYPE factories that create callable function
+ * types from raw memory addresses (BigInt). This enables COM vtable dispatch
+ * and other scenarios where function pointers are obtained at runtime.
+ *
+ * **Python ctypes Compatibility**:
+ * - `CFUNCTYPE(restype, ...argtypes)` ≈ Python's `ctypes.CFUNCTYPE`
+ * - `WINFUNCTYPE(restype, ...argtypes)` ≈ Python's `ctypes.WINFUNCTYPE`
+ *
+ * @example Calling a function by address
+ * ```javascript
+ * import { WinDLL, WINFUNCTYPE, c_int32, c_void_p, c_wchar_p, c_uint32 } from 'node-ctypes';
+ *
+ * const user32 = new WinDLL('user32.dll');
+ * const msgBoxAddr = user32.symbol('MessageBoxW');
+ *
+ * const MsgBoxProto = WINFUNCTYPE(c_int32, c_void_p, c_wchar_p, c_wchar_p, c_uint32);
+ * const msgBox = MsgBoxProto(msgBoxAddr);
+ * msgBox(null, 'Hello from FuncPtr!', 'Test', 0);
+ * ```
+ *
+ * @example COM vtable dispatch
+ * ```javascript
+ * import { WINFUNCTYPE, c_int32, c_void_p, ptrToBuffer } from 'node-ctypes';
+ *
+ * // Read vtable pointer from COM object
+ * const vtableBuf = ptrToBuffer(objPtr, 8);
+ * const vtableAddr = vtableBuf.readBigUInt64LE(0);
+ * const vtable = ptrToBuffer(vtableAddr, 24); // 3 IUnknown methods * 8 bytes
+ *
+ * // QueryInterface is the first vtable entry
+ * const QueryInterface = WINFUNCTYPE(c_int32, c_void_p, c_void_p, c_void_p);
+ * const qi = QueryInterface(vtable.readBigUInt64LE(0));
+ * ```
+ */
+
+import { _toNativeType, _toNativeTypes } from "./types.js";
+
+/**
+ * Creates a function pointer type factory with cdecl calling convention.
+ *
+ * @param {Function|Object|number} restype - Return type
+ * @param {...(Function|Object|number)} argtypes - Argument types
+ * @returns {Function} Factory that accepts a BigInt address and returns a callable
+ */
+export function createCFUNCTYPE(native) {
+  return function CFUNCTYPE(restype, ...argtypes) {
+    const nativeRestype = _toNativeType(restype, native);
+    const nativeArgtypes = _toNativeTypes(argtypes, native);
+
+    function createFromAddress(address) {
+      if (typeof address !== "bigint") {
+        throw new TypeError("CFUNCTYPE: address must be a BigInt");
+      }
+
+      const ffiFunc = new native.FFIFunction(address, null, nativeRestype, nativeArgtypes);
+
+      const callMethod = function (...args) {
+        const processedArgs = processArgs(args);
+        return ffiFunc.call(...processedArgs);
+      };
+
+      Object.defineProperties(callMethod, {
+        funcName: { value: `0x${address.toString(16)}` },
+        address: { value: ffiFunc.address },
+        _ffi: { value: ffiFunc },
+        callAsync: {
+          value: function (...args) {
+            const processedArgs = processArgs(args);
+            return ffiFunc.callAsync(...processedArgs);
+          },
+          writable: false,
+          enumerable: false,
+          configurable: false,
+        },
+        errcheck: {
+          get() {
+            return ffiFunc._errcheck;
+          },
+          set(callback) {
+            ffiFunc._errcheck = callback;
+            ffiFunc.setErrcheck(callback);
+          },
+          enumerable: false,
+          configurable: true,
+        },
+      });
+
+      return callMethod;
+    }
+
+    // Attach metadata to the factory
+    createFromAddress.restype = restype;
+    createFromAddress.argtypes = argtypes;
+    createFromAddress._isFuncPtr = true;
+
+    return createFromAddress;
+  };
+}
+
+/**
+ * Creates a function pointer type factory with stdcall calling convention.
+ *
+ * @param {Function|Object|number} restype - Return type
+ * @param {...(Function|Object|number)} argtypes - Argument types
+ * @returns {Function} Factory that accepts a BigInt address and returns a callable
+ */
+export function createWINFUNCTYPE(native) {
+  return function WINFUNCTYPE(restype, ...argtypes) {
+    const nativeRestype = _toNativeType(restype, native);
+    const nativeArgtypes = _toNativeTypes(argtypes, native);
+
+    function createFromAddress(address) {
+      if (typeof address !== "bigint") {
+        throw new TypeError("WINFUNCTYPE: address must be a BigInt");
+      }
+
+      const ffiFunc = new native.FFIFunction(address, null, nativeRestype, nativeArgtypes, { abi: "stdcall" });
+
+      const callMethod = function (...args) {
+        const processedArgs = processArgs(args);
+        return ffiFunc.call(...processedArgs);
+      };
+
+      Object.defineProperties(callMethod, {
+        funcName: { value: `0x${address.toString(16)}` },
+        address: { value: ffiFunc.address },
+        _ffi: { value: ffiFunc },
+        callAsync: {
+          value: function (...args) {
+            const processedArgs = processArgs(args);
+            return ffiFunc.callAsync(...processedArgs);
+          },
+          writable: false,
+          enumerable: false,
+          configurable: false,
+        },
+        errcheck: {
+          get() {
+            return ffiFunc._errcheck;
+          },
+          set(callback) {
+            ffiFunc._errcheck = callback;
+            ffiFunc.setErrcheck(callback);
+          },
+          enumerable: false,
+          configurable: true,
+        },
+      });
+
+      return callMethod;
+    }
+
+    // Attach metadata to the factory
+    createFromAddress.restype = restype;
+    createFromAddress.argtypes = argtypes;
+    createFromAddress._isFuncPtr = true;
+
+    return createFromAddress;
+  };
+}
+
+/**
+ * Process arguments, extracting _buffer from struct/union proxies.
+ * @private
+ */
+function processArgs(args) {
+  const processedArgs = [];
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg && typeof arg === "object") {
+      if (arg._buffer !== undefined && Buffer.isBuffer(arg._buffer)) {
+        processedArgs.push(arg._buffer);
+      } else if (Buffer.isBuffer(arg)) {
+        processedArgs.push(arg);
+      } else {
+        processedArgs.push(arg);
+      }
+    } else {
+      processedArgs.push(arg);
+    }
+  }
+  return processedArgs;
+}

package/lib/index.d.ts

@@ -79,6 +79,8 @@ export type ErrcheckCallback = (result: any, func: CallableFunction, args: any[]
 /** FFI function wrapper */
 export interface FFIFunction {
   (...args: any[]): any;
+  /** Async version: executes the native call on a worker thread, returns a Promise */
+  callAsync(...args: any[]): Promise<any>;
   readonly funcName: string;
   readonly address: bigint;
   errcheck: ErrcheckCallback | null;
@@ -87,7 +89,7 @@ export interface FFIFunction {
 /** CDLL - C calling convention library */
 export class CDLL {
   constructor(path: string | null);
-  func(name: string, returnType: AnyType, argTypes?: AnyType[], options?: FunctionOptions): CallableFunction & { errcheck: ErrcheckCallback | null };
+  func(name: string, returnType: AnyType, argTypes?: AnyType[], options?: FunctionOptions): CallableFunction & { callAsync(...args: any[]): Promise<any>; errcheck: ErrcheckCallback | null };
   symbol(name: string): bigint;
   close(): void;
   readonly path: string;
@@ -99,6 +101,8 @@ export class CDLL {
 /** FunctionWrapper for Python-like argtypes/restype syntax */
 export interface FunctionWrapper {
   (...args: any[]): any;
+  /** Async version: executes the native call on a worker thread, returns a Promise */
+  callAsync(...args: any[]): Promise<any>;
   argtypes: AnyType[];
   restype: AnyType;
   errcheck: ErrcheckCallback | null;

package/lib/index.js

@@ -23,6 +23,7 @@ import { LRUCache } from "./utils/cache.js";
 import { _initConstants } from "./platform/constants.js";
 import { _toNativeType, _toNativeTypes } from "./core/types.js";
 import { callback as createCallback, threadSafeCallback as createThreadSafeCallback } from "./core/callback.js";
+import { createCFUNCTYPE, createWINFUNCTYPE } from "./core/funcptr.js";
 import { createLibraryClasses } from "./core/Library.js";
 import {
   alloc as _alloc,
@@ -138,6 +139,10 @@ function load(libPath) {
 // Create Library classes (FunctionWrapper, CDLL, WinDLL)
 const { FunctionWrapper, CDLL, WinDLL } = createLibraryClasses(Library, LRUCache, _toNativeType, _toNativeTypes, native);
 
+// Function pointer type factories (Python ctypes CFUNCTYPE/WINFUNCTYPE)
+const CFUNCTYPE = createCFUNCTYPE(native);
+const WINFUNCTYPE = createWINFUNCTYPE(native);
+
 // ============================================================================
 // Callback Functions
 // Now imported from ./core/callback.js - see that file for implementation details
@@ -147,16 +152,16 @@ const { FunctionWrapper, CDLL, WinDLL } = createLibraryClasses(Library, LRUCache
  * Crea un callback JS chiamabile da C (solo main thread)
  * @see ./core/callback.js for full documentation
  */
-function callback(fn, returnType, argTypes = []) {
-  return createCallback(fn, returnType, argTypes, native);
+function callback(fn, returnType, argTypes = [], abi = undefined) {
+  return createCallback(fn, returnType, argTypes, native, abi);
 }
 
 /**
  * Crea un callback JS chiamabile da qualsiasi thread
  * @see ./core/callback.js for full documentation
  */
-function threadSafeCallback(fn, returnType, argTypes = []) {
-  return createThreadSafeCallback(fn, returnType, argTypes, native);
+function threadSafeCallback(fn, returnType, argTypes = [], abi = undefined) {
+  return createThreadSafeCallback(fn, returnType, argTypes, native, abi);
 }
 
 // ============================================================================
@@ -484,6 +489,8 @@ export {
   load,
   callback,
   threadSafeCallback,
+  CFUNCTYPE,
+  WINFUNCTYPE,
 
   // Memory Management - Python-compatibili
   create_string_buffer,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "node-ctypes",
-  "version": "1.3.0",
+  "version": "1.5.0",
   "description": "Python ctypes-like FFI for Node.js using libffi",
   "author": "Damiano Mazzella",
   "license": "MIT",