node-ctypes 1.2.0 → 1.3.0

package/lib/core/types.js

@@ -88,6 +88,13 @@ export function _toNativeType(type, native) {
     return type._type;
   }
 
+  // POINTER types: return CType.POINTER (11)
+  // POINTER(baseType) returns an object with _pointerTo property
+  if (type && typeof type === "object" && type._pointerTo !== undefined) {
+    // All pointer types are passed as generic pointers to FFI
+    return native.CType.POINTER;
+  }
+
   // Structure/Union classes: pass through unchanged
   // These are handled specially by the FFI layer
   if (typeof type === "function" && type.prototype) {

package/lib/index.d.ts

@@ -92,6 +92,16 @@ export class CDLL {
   close(): void;
   readonly path: string;
   readonly loaded: boolean;
+  /** Python-like function access: lib.FuncName returns a FunctionWrapper */
+  [funcName: string]: FunctionWrapper | any;
+}
+
+/** FunctionWrapper for Python-like argtypes/restype syntax */
+export interface FunctionWrapper {
+  (...args: any[]): any;
+  argtypes: AnyType[];
+  restype: AnyType;
+  errcheck: ErrcheckCallback | null;
 }
 
 /** WinDLL - stdcall calling convention library (Windows) */
@@ -326,6 +336,7 @@ export function bitfield(baseType: AnyType, bits: number): BitFieldDef;
 export function byref(obj: Buffer | SimpleCDataInstance | { _buffer: Buffer }): Buffer;
 export function cast(ptr: Buffer | bigint, targetType: AnyType | StructDef): Buffer | { [key: string]: any };
 export function POINTER(baseType: AnyType | StructDef): PointerTypeDef;
+export function pointer(obj: SimpleCDataInstance | { _buffer: Buffer }): SimpleCDataInstance & { contents: any; [index: number]: any };
 
 // Error handling
 export function get_errno(): number;
@@ -343,7 +354,7 @@ export function WinError(code?: number): Error & { winerror: number };
 export interface SimpleCDataConstructor {
   new (value?: any): SimpleCDataInstance;
   readonly _size: number;
-  readonly _type: number;  // CType numeric value from native module
+  readonly _type: number; // CType numeric value from native module
   readonly _isSimpleCData: true;
   _reader(buf: Buffer, offset: number): any;
   _writer(buf: Buffer, offset: number, value: any): void;
@@ -385,6 +396,17 @@ export const c_size_t: SimpleCDataConstructor;
 export const c_long: SimpleCDataConstructor;
 export const c_ulong: SimpleCDataConstructor;
 
+// Python-compatible aliases
+export const c_byte: SimpleCDataConstructor;
+export const c_ubyte: SimpleCDataConstructor;
+export const c_short: SimpleCDataConstructor;
+export const c_ushort: SimpleCDataConstructor;
+export const c_longlong: SimpleCDataConstructor;
+export const c_ulonglong: SimpleCDataConstructor;
+
+/** SimpleCData base class for creating custom simple types */
+export const SimpleCData: SimpleCDataConstructor;
+
 // =============================================================================
 // Constants
 // =============================================================================

package/lib/index.js

@@ -35,39 +35,12 @@ import {
   memmove as _memmove,
   memset as _memset,
 } from "./memory/buffer.js";
-import {
-  readValue as _readValue,
-  writeValue as _writeValue,
-  sizeof as _sizeof,
-} from "./memory/operations.js";
-import {
-  addressOf as _addressOf,
-  byref as _byref,
-  cast as _cast,
-  ptrToBuffer as _ptrToBuffer,
-  POINTER as _POINTER,
-} from "./memory/pointer.js";
-import {
-  get_errno as _get_errno,
-  set_errno as _set_errno,
-  GetLastError as _GetLastError,
-  SetLastError as _SetLastError,
-  FormatError as _FormatError,
-  WinError as _WinError,
-} from "./platform/errors.js";
-import {
-  bitfield as _bitfield,
-  _isStruct,
-  _isArrayType,
-  _isBitField,
-} from "./structures/helpers/common.js";
+import { readValue as _readValue, writeValue as _writeValue, sizeof as _sizeof } from "./memory/operations.js";
+import { addressOf as _addressOf, byref as _byref, cast as _cast, ptrToBuffer as _ptrToBuffer, POINTER as _POINTER, pointer as _pointer } from "./memory/pointer.js";
+import { get_errno as _get_errno, set_errno as _set_errno, GetLastError as _GetLastError, SetLastError as _SetLastError, FormatError as _FormatError, WinError as _WinError } from "./platform/errors.js";
+import { bitfield as _bitfield, _isStruct, _isArrayType, _isBitField } from "./structures/helpers/common.js";
 import { array as _array } from "./structures/helpers/array.js";
-import {
-  _readBitField as _readBitFieldHelper,
-  _writeBitField as _writeBitFieldHelper,
-  _readUintFromBuffer,
-  _writeUintToBuffer,
-} from "./structures/helpers/bitfield.js";
+import { _readBitField as _readBitFieldHelper, _writeBitField as _writeBitFieldHelper, _readUintFromBuffer, _writeUintToBuffer } from "./structures/helpers/bitfield.js";
 import { union as _union } from "./structures/helpers/union.js";
 import { struct as _struct } from "./structures/helpers/struct.js";
 import { createStructureClass } from "./structures/Structure.js";
@@ -163,13 +136,7 @@ function load(libPath) {
  * Wrapper per funzioni con sintassi Python-like ctypes (argtypes/restype)
  */
 // Create Library classes (FunctionWrapper, CDLL, WinDLL)
-const { FunctionWrapper, CDLL, WinDLL } = createLibraryClasses(
-  Library,
-  LRUCache,
-  _toNativeType,
-  _toNativeTypes,
-  native
-);
+const { FunctionWrapper, CDLL, WinDLL } = createLibraryClasses(Library, LRUCache, _toNativeType, _toNativeTypes, native);
 
 // ============================================================================
 // Callback Functions
@@ -260,6 +227,26 @@ function POINTER(baseType) {
   return _POINTER(baseType, sizeof, alloc, readValue, writeValue, c_void_p, native);
 }
 
+/**
+ * Creates a pointer to an existing ctypes object.
+ * Python ctypes compatible: pointer(obj) returns a pointer to obj.
+ *
+ * @param {Object} obj - Object to create pointer to (must have ._buffer or be a Buffer)
+ * @returns {Object} Pointer instance pointing to obj
+ *
+ * @example
+ * ```javascript
+ * const x = new c_int32(42);
+ * const p = pointer(x);
+ * console.log(p.contents); // 42
+ * p.contents = 100;
+ * console.log(x.value); // 100
+ * ```
+ */
+function pointer(obj) {
+  return _pointer(obj, _POINTER, sizeof, alloc, readValue, writeValue, c_void_p, native);
+}
+
 /**
  * Helper per definire union (tutti i campi condividono offset 0)
  * Supporta nested structs e bitfields come struct()
@@ -304,9 +291,8 @@ function defineUnion(fields) {
 // --------------------------------------------------------------------------
 
 // Create Structure and Union classes with injected dependencies
-const Structure = createStructureClass(alloc, struct);
-const Union = createUnionClass(Structure, union);
-
+const Structure = createStructureClass(alloc, struct, bitfield);
+const Union = createUnionClass(Structure, union, bitfield);
 
 /**
  * Helper per creare array a dimensione fissa (come c_int * 5 in Python)
@@ -412,28 +398,38 @@ function struct(fields, options = {}) {
 const SimpleCData = createSimpleCDataClass(alloc);
 
 // Create all primitive type classes
-const primitiveTypes = createPrimitiveTypes(
-  SimpleCData,
-  native,
-  addressOf,
-  cstring,
-  wstring,
-  readCString,
-  readWString
-);
+const primitiveTypes = createPrimitiveTypes(SimpleCData, native, addressOf, cstring, wstring, readCString, readWString);
 
 // Destructure all types for easy access
 const {
   c_void,
-  c_int8, c_int16, c_int32, c_int64,
-  c_uint8, c_uint16, c_uint32, c_uint64,
-  c_float, c_double,
+  c_int8,
+  c_int16,
+  c_int32,
+  c_int64,
+  c_uint8,
+  c_uint16,
+  c_uint32,
+  c_uint64,
+  c_float,
+  c_double,
   c_bool,
-  c_char, c_wchar,
-  c_void_p, c_char_p, c_wchar_p,
-  c_size_t, c_long, c_ulong,
-  c_byte, c_ubyte, c_short, c_ushort,
-  c_int, c_uint, c_longlong, c_ulonglong,
+  c_char,
+  c_wchar,
+  c_void_p,
+  c_char_p,
+  c_wchar_p,
+  c_size_t,
+  c_long,
+  c_ulong,
+  c_byte,
+  c_ubyte,
+  c_short,
+  c_ushort,
+  c_int,
+  c_uint,
+  c_longlong,
+  c_ulonglong,
 } = primitiveTypes;
 
 // ============================================================================
@@ -523,6 +519,7 @@ export {
   byref,
   cast,
   POINTER,
+  pointer,
 
   // Error handling
   get_errno,

package/lib/memory/pointer.js

@@ -289,54 +289,225 @@ export function POINTER(baseType, sizeof, alloc, readValue, writeValue, c_void_p
   const baseSize = typeof baseType === "object" ? baseType.size : sizeof(baseType);
   const typeName = typeof baseType === "object" ? "struct" : baseType._type || "unknown";
 
-  return {
+  /**
+   * Helper to get buffer's memory address using native writeValue
+   */
+  function getBufferAddress(buf) {
+    const tempBuf = alloc(native.POINTER_SIZE);
+    native.writeValue(tempBuf, native.CType.POINTER, buf, 0);
+    if (native.POINTER_SIZE === 8) return tempBuf.readBigUInt64LE(0);
+    return BigInt(tempBuf.readUInt32LE(0));
+  }
+
+  /**
+   * Creates a pointer instance with Python ctypes-compatible API.
+   * Supports .contents property and [index] access for pointer arithmetic.
+   */
+  function createPointerInstance(addressOrBuffer) {
+    let _address = 0n;
+    let _buffer = null;
+
+    if (addressOrBuffer === undefined || addressOrBuffer === null) {
+      _address = 0n;
+    } else if (typeof addressOrBuffer === "bigint") {
+      _address = addressOrBuffer;
+    } else if (typeof addressOrBuffer === "number") {
+      _address = BigInt(addressOrBuffer);
+    } else if (Buffer.isBuffer(addressOrBuffer)) {
+      // This is a buffer we're pointing TO
+      _buffer = addressOrBuffer;
+      _address = getBufferAddress(addressOrBuffer);
+    }
+
+    const instance = {
+      _pointerType: PointerType,
+      _baseType: baseType,
+      _baseSize: baseSize,
+
+      /**
+       * Get the raw address as BigInt
+       */
+      get address() {
+        return _address;
+      },
+
+      /**
+       * Python ctypes compatible: get/set the value at the pointed location.
+       * In Python: p.contents returns the dereferenced value.
+       */
+      get contents() {
+        if (_address === 0n && !_buffer) {
+          throw new Error("NULL pointer access");
+        }
+        if (_buffer) {
+          // We have the actual buffer, read from it
+          return readValue(_buffer, baseType, 0);
+        }
+        // We only have address - need native support to read
+        const buf = native.ptrToBuffer(_address, baseSize);
+        return readValue(buf, baseType, 0);
+      },
+
+      set contents(value) {
+        if (_address === 0n && !_buffer) {
+          throw new Error("NULL pointer access");
+        }
+        if (_buffer) {
+          writeValue(_buffer, baseType, value, 0);
+        } else {
+          const buf = native.ptrToBuffer(_address, baseSize);
+          writeValue(buf, baseType, value, 0);
+        }
+      },
+
+      /**
+       * Returns the buffer this pointer points to (if available)
+       */
+      get _buffer() {
+        return _buffer;
+      },
+
+      /**
+       * Dereference - alias for contents getter
+       */
+      deref() {
+        return this.contents;
+      },
+
+      /**
+       * Set pointer to point to a new address/buffer
+       */
+      set(value) {
+        if (Buffer.isBuffer(value)) {
+          _buffer = value;
+          _address = getBufferAddress(value);
+        } else if (typeof value === "bigint") {
+          _address = value;
+          _buffer = null;
+        } else if (typeof value === "number") {
+          _address = BigInt(value);
+          _buffer = null;
+        }
+      },
+
+      /**
+       * Check if pointer is NULL
+       */
+      get isNull() {
+        return _address === 0n && !_buffer;
+      },
+
+      /**
+       * For compatibility - get pointer as buffer (8 bytes containing address)
+       */
+      toBuffer() {
+        const buf = alloc(native.POINTER_SIZE);
+        writeValue(buf, c_void_p, _address);
+        return buf;
+      },
+
+      toString() {
+        return `<${typeName} pointer at 0x${_address.toString(16)}>`;
+      },
+    };
+
+    // Use Proxy for [index] access (pointer arithmetic)
+    return new Proxy(instance, {
+      get(target, prop, receiver) {
+        // Numeric index access: p[0], p[1], etc.
+        if (typeof prop === "string" && /^\d+$/.test(prop)) {
+          const index = parseInt(prop, 10);
+          if (target.isNull) {
+            throw new Error("NULL pointer access");
+          }
+          const offset = index * baseSize;
+          if (_buffer && offset + baseSize <= _buffer.length) {
+            return readValue(_buffer, baseType, offset);
+          }
+          // Use native to read at address + offset
+          const addr = _address + BigInt(offset);
+          const buf = native.ptrToBuffer(addr, baseSize);
+          return readValue(buf, baseType, 0);
+        }
+        return Reflect.get(target, prop, receiver);
+      },
+
+      set(target, prop, value, receiver) {
+        // Numeric index access: p[0] = value, p[1] = value, etc.
+        if (typeof prop === "string" && /^\d+$/.test(prop)) {
+          const index = parseInt(prop, 10);
+          if (target.isNull) {
+            throw new Error("NULL pointer access");
+          }
+          const offset = index * baseSize;
+          if (_buffer && offset + baseSize <= _buffer.length) {
+            writeValue(_buffer, baseType, value, offset);
+            return true;
+          }
+          // Use native to write at address + offset
+          const addr = _address + BigInt(offset);
+          const buf = native.ptrToBuffer(addr, baseSize);
+          writeValue(buf, baseType, value, 0);
+          return true;
+        }
+        return Reflect.set(target, prop, value, receiver);
+      },
+    });
+  }
+
+  /**
+   * Pointer type factory - creates pointer instances
+   */
+  const PointerType = {
     _pointerTo: baseType,
     _baseSize: baseSize,
     size: native.POINTER_SIZE,
 
     /**
-     * Creates a NULL pointer.
-     * @returns {Buffer} Buffer containing NULL pointer
+     * Creates a new pointer instance.
+     * @param {Buffer|bigint|number} [value] - Initial value (buffer to point to, or address)
+     * @returns {Object} Pointer instance with .contents and [index] access
      */
-    create() {
-      const buf = alloc(native.POINTER_SIZE);
-      writeValue(buf, c_void_p, 0n);
-      return buf;
+    create(value) {
+      return createPointerInstance(value);
     },
 
     /**
-     * Creates a pointer to an existing buffer.
-     * @param {Buffer} targetBuf - Target buffer to point to
-     * @returns {Buffer} Buffer containing pointer to targetBuf
+     * Creates a pointer from an existing buffer (points to that buffer).
+     * @param {Buffer} targetBuf - Buffer to point to
+     * @returns {Object} Pointer instance
      */
     fromBuffer(targetBuf) {
-      const buf = alloc(native.POINTER_SIZE);
-      writeValue(buf, c_void_p, targetBuf);
-      return buf;
+      return createPointerInstance(targetBuf);
+    },
+
+    /**
+     * Creates a pointer from a raw address.
+     * @param {bigint|number} address - Memory address
+     * @returns {Object} Pointer instance
+     */
+    fromAddress(address) {
+      return createPointerInstance(typeof address === "bigint" ? address : BigInt(address));
     },
 
     /**
-     * Dereferences the pointer (reads the address it points to).
-     * @param {Buffer} ptrBuf - Buffer containing the pointer
-     * @returns {bigint|null} Address value, or null if NULL pointer
+     * Legacy API: Dereferences a pointer buffer.
+     * @deprecated Use pointer instance .contents instead
      */
     deref(ptrBuf) {
       const addr = readValue(ptrBuf, c_void_p);
       if (addr === 0n || addr === null) {
         return null;
       }
-      // For struct types, return address (can't safely create buffer without native support)
       if (typeof baseType === "object" && baseType.toObject) {
         return addr;
       }
-      // For primitive types, return address
       return addr;
     },
 
     /**
-     * Sets the pointer to point to a value or buffer.
-     * @param {Buffer} ptrBuf - Buffer containing the pointer
-     * @param {Buffer|bigint|number} value - Value to set (buffer or address)
+     * Legacy API: Sets pointer buffer value.
+     * @deprecated Use pointer instance .set() instead
      */
     set(ptrBuf, value) {
       if (Buffer.isBuffer(value)) {
@@ -346,12 +517,59 @@ export function POINTER(baseType, sizeof, alloc, readValue, writeValue, c_void_p
       }
     },
 
-    /**
-     * Returns string representation of pointer type.
-     * @returns {string} Type name
-     */
     toString() {
       return `POINTER(${typeName})`;
     },
   };
+
+  return PointerType;
+}
+
+/**
+ * Creates a pointer to an existing ctypes object.
+ * Python ctypes compatible: pointer(obj) returns a pointer to obj.
+ *
+ * @param {Object} obj - Object to create pointer to (must have ._buffer or be a Buffer)
+ * @param {Function} POINTER_fn - POINTER function reference
+ * @param {Function} sizeof - sizeof function reference
+ * @param {Function} alloc - alloc function reference
+ * @param {Function} readValue - readValue function reference
+ * @param {Function} writeValue - writeValue function reference
+ * @param {Function} c_void_p - c_void_p type reference
+ * @param {Object} native - Native module reference
+ * @returns {Object} Pointer instance pointing to obj
+ *
+ * @example
+ * ```javascript
+ * const x = new c_int32(42);
+ * const p = pointer(x);
+ * console.log(p.contents); // 42
+ * p.contents = 100;
+ * console.log(x.value); // 100
+ * ```
+ */
+export function pointer(obj, POINTER_fn, sizeof, alloc, readValue, writeValue, c_void_p, native) {
+  let targetBuffer;
+  let baseType;
+
+  if (Buffer.isBuffer(obj)) {
+    targetBuffer = obj;
+    baseType = c_void_p; // Generic pointer
+  } else if (obj && obj._buffer) {
+    // Structure/Union instance or SimpleCData with _buffer
+    targetBuffer = obj._buffer;
+    // Get the base type - use constructor for SimpleCData, _structDef for structures
+    if (obj.constructor && obj.constructor._type) {
+      // SimpleCData instance - use the class itself
+      baseType = obj.constructor;
+    } else {
+      // Structure/Union instance
+      baseType = obj._structDef || obj.__structDef || c_void_p;
+    }
+  } else {
+    throw new TypeError("pointer() argument must be a ctypes instance or Buffer");
+  }
+
+  const PtrType = POINTER_fn(baseType, sizeof, alloc, readValue, writeValue, c_void_p, native);
+  return PtrType.fromBuffer(targetBuffer);
 }