node-ctypes 1.4.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/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.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.4.0",
+  "version": "1.5.0",
   "description": "Python ctypes-like FFI for Node.js using libffi",
   "author": "Damiano Mazzella",
   "license": "MIT",