node-ctypes 1.13.0 → 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/lib/index.d.ts CHANGED
@@ -47,7 +47,7 @@
47
47
  *
48
48
  * const x = new c_int32(42);
49
49
  * const p = pointer(x);
50
- * console.log(p.contents); // 42
50
+ * console.log(p.contents.value); // 42
51
51
  * ```
52
52
  *
53
53
  * @packageDocumentation
@@ -91,6 +91,8 @@ export interface CTypeValues {
91
91
  readonly STRUCT: number;
92
92
  readonly UNION: number;
93
93
  readonly ARRAY: number;
94
+ /** `char` as a 1-byte character (Python `c_char`). */
95
+ readonly CHAR: number;
94
96
  readonly COUNT: number;
95
97
  }
96
98
 
@@ -106,6 +108,22 @@ export const CType: CTypeValues;
106
108
  */
107
109
  export type AnyType = SimpleCDataConstructor | number | StructDef | UnionDef;
108
110
 
111
+ /**
112
+ * A {@link Structure} or {@link Union} subclass used as a type
113
+ * (e.g. `class Point extends Structure { ... }` passed as `Point`).
114
+ * @category Types
115
+ */
116
+ export type StructureClass = abstract new (...args: any[]) => Structure<any>;
117
+
118
+ /**
119
+ * Any type accepted in a function signature (`argtypes` / `restype`):
120
+ * {@link AnyType}, a Structure/Union class (struct by value), a
121
+ * {@link POINTER} type, an {@link array} type or a {@link CFUNCTYPE} prototype
122
+ * (function pointer).
123
+ * @category Types
124
+ */
125
+ export type FFIType = AnyType | StructureClass | PointerTypeDef | ArrayTypeDef | FuncPtrFactory;
126
+
109
127
  // =============================================================================
110
128
  // Library & Function
111
129
  // =============================================================================
@@ -116,7 +134,7 @@ export type AnyType = SimpleCDataConstructor | number | StructDef | UnionDef;
116
134
  * @example
117
135
  * ```javascript
118
136
  * import { Version } from 'node-ctypes';
119
- * console.log(Version.toString()); // "1.5.0"
137
+ * console.log(Version.toString()); // "2.0.0"
120
138
  * ```
121
139
  *
122
140
  * @category Library Loading
@@ -138,8 +156,14 @@ export class Version {
138
156
  export class Library {
139
157
  constructor(path: string | null);
140
158
  /** Typed overload: narrows args/return when argTypes is a literal tuple. */
141
- func<TRet extends AnyType, const TArgs extends readonly AnyType[]>(name: string, returnType: TRet, argTypes: TArgs, options?: FunctionOptions): TypedFFIFunction<TArgs, TRet>;
142
- func(name: string, returnType: AnyType, argTypes?: AnyType[], options?: FunctionOptions): FFIFunction;
159
+ func<TRet extends FFIType | null, const TArgs extends readonly FFIType[]>(name: string, returnType: TRet, argTypes: TArgs, options?: FunctionOptions): NativeFFIFunction<TArgs, TRet>;
160
+ func(name: string, returnType: FFIType | null, argTypes?: FFIType[], options?: FunctionOptions): NativeFFIFunction;
161
+
162
+ /**
163
+ * Create a native callback. Note the argument order (return type, argument
164
+ * types, function), which differs from {@link callback} and {@link CDLL.callback}.
165
+ */
166
+ callback(returnType: AnyType, argTypes: AnyType[], fn: Function): Callback;
143
167
 
144
168
  /**
145
169
  * Get the address of a symbol in the library.
@@ -182,7 +206,7 @@ export interface FunctionOptions {
182
206
  export type ErrcheckCallback = (result: any, func: CallableFunction, args: any[]) => any;
183
207
 
184
208
  /**
185
- * A callable FFI function returned by {@link Library.func} or {@link CDLL.func}.
209
+ * A callable FFI function returned by {@link CDLL.func}.
186
210
  * @category Library Loading
187
211
  */
188
212
  export interface FFIFunction {
@@ -199,14 +223,45 @@ export interface FFIFunction {
199
223
  readonly address: bigint;
200
224
 
201
225
  /**
202
- * Error checking callback, called after every invocation.
226
+ * Error checking callback, called after every invocation (`null` when not set).
203
227
  * @see {@link ErrcheckCallback}
204
228
  */
205
229
  errcheck: ErrcheckCallback | null;
206
230
  }
207
231
 
208
232
  /**
209
- * Strongly-typed FFI function returned by `CDLL.func`/`Library.func` when the
233
+ * Low-level native function handle returned by {@link Library.func}.
234
+ *
235
+ * Unlike the functions returned by {@link CDLL.func}, it is not directly
236
+ * callable: invoke it with {@link NativeFFIFunction.call | call()}.
237
+ *
238
+ * @category Library Loading
239
+ */
240
+ export interface NativeFFIFunction<TArgs extends readonly FFIType[] = FFIType[], TRet extends FFIType | null = FFIType> {
241
+ /** Call the native function synchronously. */
242
+ call(...args: FFIArgs<TArgs>): FFIReturn<TRet>;
243
+
244
+ /** Call the native function asynchronously on a worker thread. */
245
+ callAsync(...args: FFIArgs<TArgs>): Promise<FFIReturn<TRet>>;
246
+
247
+ /** Set (or clear with `null`) the error checking callback. */
248
+ setErrcheck(callback: ErrcheckCallback | null): void;
249
+
250
+ /** `GetLastError()` (Windows) or `errno` captured after the last call, with `use_last_error`. */
251
+ getCapturedLastError(): number;
252
+
253
+ /** `errno` captured after the last call, with `use_errno`. */
254
+ getCapturedErrno(): number;
255
+
256
+ /** The function name, or its hex address for raw function pointers. */
257
+ readonly name: string;
258
+
259
+ /** The function address as BigInt. */
260
+ readonly address: bigint;
261
+ }
262
+
263
+ /**
264
+ * Strongly-typed FFI function returned by `CDLL.func` when the
210
265
  * argument types and return type are given as a literal tuple and constant respectively.
211
266
  *
212
267
  * Args and return are narrowed from the supplied CType constructors.
@@ -214,9 +269,9 @@ export interface FFIFunction {
214
269
  *
215
270
  * @category Library Loading
216
271
  */
217
- export interface TypedFFIFunction<TArgs extends readonly AnyType[], TRet extends AnyType> {
218
- (...args: ArgsFromCTypes<TArgs>): JsFromCType<TRet>;
219
- callAsync(...args: ArgsFromCTypes<TArgs>): Promise<JsFromCType<TRet>>;
272
+ export interface TypedFFIFunction<TArgs extends readonly FFIType[], TRet extends FFIType | null> {
273
+ (...args: FFIArgs<TArgs>): FFIReturn<TRet>;
274
+ callAsync(...args: FFIArgs<TArgs>): Promise<FFIReturn<TRet>>;
220
275
  readonly funcName: string;
221
276
  readonly address: bigint;
222
277
  errcheck: ErrcheckCallback | null;
@@ -256,6 +311,14 @@ export interface TypedFFIFunction<TArgs extends readonly AnyType[], TRet extends
256
311
  * @category Library Loading
257
312
  */
258
313
  export interface LibraryOptions {
314
+ /**
315
+ * `dlopen` flags combined with `RTLD_LAZY` (e.g. {@link RTLD_GLOBAL}).
316
+ * Ignored on Windows. Default: {@link DEFAULT_MODE}.
317
+ *
318
+ * Python ctypes parity: the `mode` argument of `CDLL(name, mode)`.
319
+ */
320
+ mode?: number;
321
+
259
322
  /**
260
323
  * Maximum size of the internal function cache. Default: 1000.
261
324
  */
@@ -282,9 +345,10 @@ export interface LibraryOptions {
282
345
  export class CDLL {
283
346
  /**
284
347
  * @param path - Path to the shared library, or `null` to load the current process
285
- * @param options - Optional library settings (cache size, use_last_error, use_errno)
348
+ * @param options - `dlopen` mode (as Python's `CDLL(name, mode)`) or library
349
+ * settings (mode, cache size, use_last_error, use_errno)
286
350
  */
287
- constructor(path: string | null, options?: LibraryOptions);
351
+ constructor(path: string | null, options?: number | LibraryOptions);
288
352
 
289
353
  /**
290
354
  * Get a callable function from the library.
@@ -296,8 +360,8 @@ export class CDLL {
296
360
  * @returns A callable function
297
361
  */
298
362
  /** Typed overload: narrows args/return when argTypes is a literal tuple. */
299
- func<TRet extends AnyType, const TArgs extends readonly AnyType[]>(name: string, returnType: TRet, argTypes: TArgs, options?: FunctionOptions): TypedFFIFunction<TArgs, TRet>;
300
- func(name: string, returnType: AnyType, argTypes?: AnyType[], options?: FunctionOptions): CallableFunction & { callAsync(...args: any[]): Promise<any>; errcheck: ErrcheckCallback | null };
363
+ func<TRet extends FFIType | null, const TArgs extends readonly FFIType[]>(name: string, returnType: TRet, argTypes: TArgs, options?: FunctionOptions): TypedFFIFunction<TArgs, TRet>;
364
+ func(name: string, returnType: FFIType | null, argTypes?: FFIType[], options?: FunctionOptions): FFIFunction;
301
365
 
302
366
  /**
303
367
  * Get the address of a symbol.
@@ -309,6 +373,15 @@ export class CDLL {
309
373
  /** Close the library and clear the function cache. */
310
374
  close(): void;
311
375
 
376
+ /** Close the library at the end of a `using` block. */
377
+ [Symbol.dispose](): void;
378
+
379
+ /**
380
+ * Create a native callback bound to this library's context.
381
+ * Call `release()` when it is no longer needed.
382
+ */
383
+ callback(fn: Function, returnType: AnyType | null, argTypes?: AnyType[]): Callback;
384
+
312
385
  /**
313
386
  * Read the snapshotted `GetLastError()` (Windows) or `errno` from the most
314
387
  * recent call on this library. Requires `use_last_error: true` at
@@ -362,12 +435,12 @@ export interface FunctionWrapper {
362
435
  callAsync(...args: any[]): Promise<any>;
363
436
 
364
437
  /** Argument types. Set before calling. */
365
- argtypes: AnyType[];
438
+ argtypes: FFIType[];
366
439
 
367
- /** Return type. Set before calling. */
368
- restype: AnyType;
440
+ /** Return type (`null` for `void`, as Python's `None`). Set before calling. */
441
+ restype: FFIType | null;
369
442
 
370
- /** Optional error checking callback. */
443
+ /** Optional error checking callback (`null` when not set). */
371
444
  errcheck: ErrcheckCallback | null;
372
445
  }
373
446
 
@@ -389,7 +462,7 @@ export interface FunctionWrapper {
389
462
  * @category Library Loading
390
463
  */
391
464
  export class WinDLL extends CDLL {
392
- constructor(path: string, options?: LibraryOptions);
465
+ constructor(path: string, options?: number | LibraryOptions);
393
466
  }
394
467
 
395
468
  /**
@@ -439,7 +512,35 @@ export const HRESULT: SimpleCDataConstructor<"int32"> & { _isHResult: true };
439
512
  *
440
513
  * @category Library Loading
441
514
  */
442
- export const cdll: { [libName: string]: CDLL };
515
+ export const cdll: LibraryNamespace<CDLL>;
516
+
517
+ /**
518
+ * Lazy library namespace: attribute access loads (and caches) the library,
519
+ * `LoadLibrary(name)` always creates a new instance.
520
+ *
521
+ * Python equivalent: `ctypes.LibraryLoader` instances (`cdll`, `windll`, ...)
522
+ *
523
+ * @category Library Loading
524
+ */
525
+ export type LibraryNamespace<T extends CDLL> = { [libName: string]: T } & {
526
+ /** Load a library (new instance each time). Python: `cdll.LoadLibrary(name)`. */
527
+ LoadLibrary(name: string | null, options?: number | LibraryOptions): T;
528
+ };
529
+
530
+ /**
531
+ * Create a lazy library namespace for a DLL class.
532
+ *
533
+ * Python equivalent: `ctypes.LibraryLoader(dlltype)`
534
+ *
535
+ * @example
536
+ * ```javascript
537
+ * const mydll = new LibraryLoader(CDLL);
538
+ * const libm = mydll.LoadLibrary(find_library("m"));
539
+ * ```
540
+ *
541
+ * @category Library Loading
542
+ */
543
+ export const LibraryLoader: new <T extends CDLL>(dlltype: new (path: string, ...args: any[]) => T) => LibraryNamespace<T>;
443
544
 
444
545
  /**
445
546
  * Lazy-loading namespace for WinDLL libraries (Windows only).
@@ -449,7 +550,7 @@ export const cdll: { [libName: string]: CDLL };
449
550
  *
450
551
  * @category Library Loading
451
552
  */
452
- export const windll: { [libName: string]: WinDLL } | undefined;
553
+ export const windll: LibraryNamespace<WinDLL> | undefined;
453
554
 
454
555
  /**
455
556
  * Lazy-loading namespace for OleDLL libraries (Windows only).
@@ -459,7 +560,7 @@ export const windll: { [libName: string]: WinDLL } | undefined;
459
560
  *
460
561
  * @category Library Loading
461
562
  */
462
- export const oledll: { [libName: string]: OleDLL } | undefined;
563
+ export const oledll: LibraryNamespace<OleDLL> | undefined;
463
564
 
464
565
  // =============================================================================
465
566
  // Callbacks
@@ -477,8 +578,14 @@ export interface CallbackWrapper {
477
578
  /** The callback function pointer, passable to native functions. */
478
579
  readonly pointer: bigint;
479
580
 
581
+ /** Same as `pointer`: lets the callback be passed directly as an argument. */
582
+ readonly _as_parameter_: bigint;
583
+
480
584
  /** Release the callback and free native resources. Must be called when done. */
481
585
  release(): void;
586
+
587
+ /** Release the callback at the end of a `using` block. */
588
+ [Symbol.dispose](): void;
482
589
  }
483
590
 
484
591
  /**
@@ -487,8 +594,21 @@ export interface CallbackWrapper {
487
594
  */
488
595
  export class Callback {
489
596
  constructor(fn: Function, returnType: AnyType, argTypes?: AnyType[]);
597
+ /** The callback function pointer, passable to native functions. */
490
598
  readonly pointer: bigint;
599
+ /** Same as {@link Callback.pointer}. */
600
+ getPointer(): bigint;
601
+ /** Same as `pointer`: lets the callback be passed directly as an argument. */
602
+ readonly _as_parameter_: bigint;
603
+ /** Release the callback and free native resources. Must be called when done. */
491
604
  release(): void;
605
+ /**
606
+ * Handler called with the error message when the JS function throws.
607
+ * Without a handler the error is reported with `process.emitWarning`.
608
+ */
609
+ setErrorHandler(handler: (message: string) => void): void;
610
+ /** Message of the last exception thrown by the JS function, or `null`. */
611
+ getLastError(): string | null;
492
612
  }
493
613
 
494
614
  /**
@@ -531,7 +651,7 @@ export interface FieldDef {
531
651
  *
532
652
  * @category Structures
533
653
  */
534
- export interface StructDef {
654
+ export interface StructDef<F extends Record<string, FieldSpec> = Record<string, any>> {
535
655
  /** Total size of the struct in bytes. */
536
656
  readonly size: number;
537
657
  /** Alignment requirement in bytes. */
@@ -544,19 +664,27 @@ export interface StructDef {
544
664
  readonly _isStructType: true;
545
665
 
546
666
  /** Allocate a buffer and optionally initialize field values. */
547
- create(values?: Record<string, any>): Buffer;
667
+ create(values?: FieldsInput<F>): Buffer;
548
668
  /** Read a field value from a buffer. */
549
- get(buf: Buffer, fieldName: string): any;
669
+ get<K extends keyof F & string>(buf: Buffer, fieldName: K): FieldValue<F, K>;
550
670
  /** Write a field value to a buffer. */
551
- set(buf: Buffer, fieldName: string, value: any): void;
671
+ set<K extends keyof F & string>(buf: Buffer, fieldName: K, value: FieldArg<F, K>): void;
552
672
  /** Convert all fields to a plain JavaScript object. */
553
- toObject(buf: Buffer): Record<string, any>;
673
+ toObject(buf: Buffer): FieldsObject<F>;
554
674
  /** Get a view of a nested struct's buffer region. */
555
675
  getNestedBuffer(buf: Buffer, fieldName: string): Buffer;
556
676
  }
557
677
 
678
+ /**
679
+ * One entry of `_fields_`: `[name, type]` or `[name, type, bits]` for bit fields.
680
+ * The loose element form lets `static _fields_ = [["x", c_int]]` compile
681
+ * without `as const`, as written in Python.
682
+ * @category Structures
683
+ */
684
+ export type FieldEntry = readonly [string, FieldSpec] | readonly [string, FieldSpec, number] | ReadonlyArray<string | number | FieldSpec>;
685
+
558
686
  /** @category Structures */
559
- export type FieldSpec = AnyType | StructDef | ArrayTypeDef | BitFieldDef | AnonymousField | PointerTypeDef;
687
+ export type FieldSpec = AnyType | StructDef | ArrayTypeDef | BitFieldDef | AnonymousField | PointerTypeDef | StructureClass | FuncPtrFactory;
560
688
 
561
689
  /**
562
690
  * Map a field/arg type (CType constructor, struct, array, bitfield, pointer) to its
@@ -565,7 +693,21 @@ export type FieldSpec = AnyType | StructDef | ArrayTypeDef | BitFieldDef | Anony
565
693
  * @category Types
566
694
  */
567
695
  export type JsFromCType<T> =
568
- T extends SimpleCDataConstructor<infer Tag> ? JsFromTag<Tag> : T extends BitFieldDef ? number : T extends PointerTypeDef ? PointerInstance : T extends StructDef ? any : T extends UnionDef ? any : T extends ArrayTypeDef ? any : any;
696
+ T extends SimpleCDataConstructor<infer Tag>
697
+ ? JsFromTag<Tag>
698
+ : T extends BitFieldDef
699
+ ? number
700
+ : T extends PointerTypeDef<infer B>
701
+ ? PointerInstance<B> | null
702
+ : T extends FuncPtrFactory
703
+ ? ((...args: any[]) => any) | null
704
+ : T extends StructureClass
705
+ ? InstanceType<T>
706
+ : T extends StructDef<infer F>
707
+ ? FieldsObject<F>
708
+ : T extends ArrayTypeDef<infer E>
709
+ ? CharArrayValue<E, ArrayInstance<E>>
710
+ : any;
569
711
 
570
712
  /**
571
713
  * Map a field/arg type to accepted JavaScript **input** types (for writes / function args).
@@ -579,23 +721,101 @@ export type JsArgFromCType<T> =
579
721
  : T extends BitFieldDef
580
722
  ? number
581
723
  : T extends PointerTypeDef
582
- ? PointerInstance | Buffer | bigint | null
583
- : T extends StructDef
584
- ? Buffer | { _buffer: Buffer } | Record<string, any>
585
- : T extends UnionDef
724
+ ? PointerInstance | Buffer | bigint | null | { readonly _buffer: Buffer }
725
+ : T extends FuncPtrFactory
726
+ ? { readonly _as_parameter_: unknown } | bigint | null
727
+ : T extends StructDef
586
728
  ? Buffer | { _buffer: Buffer } | Record<string, any>
587
- : T extends ArrayTypeDef
588
- ? Buffer | ReadonlyArray<any>
589
- : any;
729
+ : T extends UnionDef
730
+ ? Buffer | { _buffer: Buffer } | Record<string, any>
731
+ : T extends ArrayTypeDef<infer E>
732
+ ? Buffer | ReadonlyArray<any> | CharArrayValue<E, never>
733
+ : any;
590
734
 
591
735
  type FieldsToInstance<F extends Record<string, FieldSpec>> = {
592
736
  [K in keyof F]: JsFromCType<F[K]>;
593
737
  };
594
738
 
739
+ /** `true` when `T` is `any`. */
740
+ type IsAny<T> = 0 extends 1 & T ? true : false;
741
+
742
+ /** Field values of a definition; `any` when the fields are not statically known. */
743
+ type FieldsObject<F extends Record<string, FieldSpec>> = string extends keyof F ? Record<string, any> : FieldsToInstance<F>;
744
+
745
+ /** Initial values accepted by `create()`. */
746
+ type FieldsInput<F extends Record<string, FieldSpec>> = string extends keyof F ? Record<string, any> : { [K in keyof F]?: JsArgFromCType<F[K]> };
747
+
748
+ /** Value read from field `K`. */
749
+ type FieldValue<F extends Record<string, FieldSpec>, K extends keyof F> = string extends keyof F ? any : JsFromCType<F[K]>;
750
+
751
+ /** Value accepted when writing field `K`. */
752
+ type FieldArg<F extends Record<string, FieldSpec>, K extends keyof F> = string extends keyof F ? any : JsArgFromCType<F[K]>;
753
+
754
+ /**
755
+ * Element read from an array of `E`. Narrowed only to `number`: arrays are
756
+ * also Buffers, whose numeric index is `number`, so other element types stay `any`.
757
+ */
758
+ type ArrayElement<E> = IsAny<E> extends true ? any : JsFromCType<E> extends number ? number : any;
759
+
760
+ /** Element accepted when writing an array of `E`. */
761
+ type ArrayElementArg<E> = IsAny<E> extends true ? any : E extends StructureClass ? Buffer | Record<string, any> : JsArgFromCType<E>;
762
+
763
+ /** Value read through a pointer to `T` (`p[i]`): the value for simple types, a live instance for structures. */
764
+ type PointerValue<T> = IsAny<T> extends true ? any : T extends StructureClass ? InstanceType<T> : JsFromCType<T>;
765
+
766
+ /** `p.contents`: a live instance on the pointed memory (Python parity). */
767
+ type PointerContents<T> = IsAny<T> extends true ? any : T extends SimpleCDataConstructor<infer Tag> ? SimpleCDataInstance<JsFromTag<Tag>> : T extends StructureClass ? InstanceType<T> : JsFromCType<T>;
768
+
769
+ /** `string` for `c_char`/`c_wchar` arrays (read as text, as Python), otherwise `Else`. */
770
+ type CharArrayValue<E, Else> = IsAny<E> extends true ? Else : [E] extends [SimpleCDataConstructor<"char">] ? string : [E] extends [SimpleCDataConstructor<"wchar">] ? string : Else;
771
+
772
+ /**
773
+ * Array instance: a Buffer with index access; `c_char` arrays also expose
774
+ * `.value`/`.raw` and `c_wchar` arrays `.value`, as in Python.
775
+ * @category Structures
776
+ */
777
+ export type ArrayInstance<E = any> = Buffer & ArrayProxy<ArrayElement<E>> & (IsAny<E> extends true ? {} : [E] extends [SimpleCDataConstructor<"char">] ? CharBufferValue : [E] extends [SimpleCDataConstructor<"wchar">] ? WideBufferValue : {});
778
+
779
+ /**
780
+ * Text accessors of `c_char` buffers (arrays, {@link create_string_buffer}).
781
+ * @category Memory
782
+ */
783
+ export interface CharBufferValue {
784
+ /** Bytes up to the first NUL, decoded as UTF-8. Python: `.value`. */
785
+ get value(): string;
786
+ set value(v: string | Uint8Array);
787
+ /** All bytes. Python: `.raw`. */
788
+ get raw(): Buffer;
789
+ set raw(v: string | Uint8Array);
790
+ }
791
+
792
+ /**
793
+ * Text accessor of `c_wchar` buffers (arrays, {@link create_unicode_buffer}).
794
+ * @category Memory
795
+ */
796
+ export interface WideBufferValue {
797
+ /** Characters up to the first NUL. Python: `.value`. */
798
+ get value(): string;
799
+ set value(v: string);
800
+ }
801
+
595
802
  type ArgsFromCTypes<TArgs extends readonly any[]> = {
596
803
  [K in keyof TArgs]: JsArgFromCType<TArgs[K]>;
597
804
  };
598
805
 
806
+ /** JS argument accepted for a function parameter of type `T`. */
807
+ type JsArgFromFFIType<T> = T extends StructureClass ? Buffer | { _buffer: Buffer } | Record<string, any> : JsArgFromCType<T>;
808
+
809
+ /** Function arguments for `argtypes` `TArgs` (`any[]` when not a literal tuple). */
810
+ type FFIArgs<TArgs extends readonly any[]> = FFIType[] extends TArgs ? any[] : { [K in keyof TArgs]: JsArgFromFFIType<TArgs[K]> };
811
+
812
+ /**
813
+ * JS value returned by a function with `restype` `T`. As in Python, a
814
+ * `POINTER(T)` restype returns a {@link PointerInstance} and a {@link CFUNCTYPE}
815
+ * restype a callable function (`null` for NULL).
816
+ */
817
+ type FFIReturn<T> = FFIType extends T ? any : T extends null ? undefined : T extends StructureClass ? Record<string, any> : JsFromCType<T>;
818
+
599
819
  /**
600
820
  * A union type definition created by the {@link union} function.
601
821
  *
@@ -604,7 +824,7 @@ type ArgsFromCTypes<TArgs extends readonly any[]> = {
604
824
  *
605
825
  * @category Structures
606
826
  */
607
- export interface UnionDef extends StructDef {
827
+ export interface UnionDef<F extends Record<string, FieldSpec> = Record<string, any>> extends StructDef<F> {
608
828
  readonly isUnion: true;
609
829
  }
610
830
 
@@ -637,18 +857,25 @@ export interface BitFieldDef {
637
857
  /**
638
858
  * An array type definition created by the {@link array} function.
639
859
  *
860
+ * Python equivalent: `c_int * 5`. Call it (with or without `new`) with the
861
+ * initial elements, as Python's `(c_int * 5)(1, 2, 3)`.
862
+ *
640
863
  * @example
641
864
  * ```javascript
642
865
  * const IntArray5 = array(c_int32, 5);
643
- * const arr = IntArray5.create([1, 2, 3, 4, 5]);
866
+ * const arr = IntArray5(1, 2, 3, 4, 5); // or IntArray5.create([1, 2, 3, 4, 5])
644
867
  * console.log(arr[0]); // 1
645
868
  * ```
646
869
  *
647
870
  * @category Structures
648
871
  */
649
- export interface ArrayTypeDef {
872
+ export interface ArrayTypeDef<E = any> {
873
+ /** Create an array initialized with the given elements (Python: `(c_int * 3)(1, 2, 3)`). */
874
+ (...values: ArrayElementArg<E>[]): ArrayInstance<E>;
875
+ /** Create an array initialized with the given elements. */
876
+ new (...values: ArrayElementArg<E>[]): ArrayInstance<E>;
650
877
  /** Element type. */
651
- readonly elementType: AnyType;
878
+ readonly elementType: AnyType | StructureClass | ArrayTypeDef | PointerTypeDef | FuncPtrFactory;
652
879
  /** Number of elements. */
653
880
  readonly length: number;
654
881
  /** @internal */
@@ -660,19 +887,22 @@ export interface ArrayTypeDef {
660
887
  getLength(): number;
661
888
  /** Element alignment. */
662
889
  getAlignment(): number;
663
- /** Create a new array, optionally initialized with values. Returns a Proxy with index access. */
664
- create(values?: any[]): Buffer & ArrayProxy;
890
+ /**
891
+ * Create a new array, optionally initialized with values (a string writes
892
+ * its char codes). Returns a Proxy with index access.
893
+ */
894
+ create(values?: ReadonlyArray<ArrayElementArg<E>> | string): ArrayInstance<E>;
665
895
  /** Wrap an existing buffer as an array with index access. */
666
- wrap(buffer: Buffer): Buffer & ArrayProxy;
896
+ wrap(buffer: Buffer): ArrayInstance<E>;
667
897
  }
668
898
 
669
899
  /**
670
900
  * Proxy interface for array index access and iteration.
671
901
  * @category Structures
672
902
  */
673
- export interface ArrayProxy {
674
- [index: number]: any;
675
- [Symbol.iterator](): Iterator<any>;
903
+ export interface ArrayProxy<T = any> {
904
+ [index: number]: T;
905
+ [Symbol.iterator](): Iterator<T>;
676
906
  }
677
907
 
678
908
  /**
@@ -707,7 +937,7 @@ export interface AnonymousField {
707
937
  * ```javascript
708
938
  * const IntPtr = POINTER(c_int32);
709
939
  * const p = IntPtr.fromBuffer(buf);
710
- * console.log(p.contents); // dereferenced value (like *p in C)
940
+ * console.log(p.contents.value); // dereferenced value (like *p in C)
711
941
  * console.log(p[0]); // same as p.contents
712
942
  * console.log(p[5]); // pointer arithmetic (like p[5] in C)
713
943
  * ```
@@ -723,9 +953,9 @@ export interface AnonymousField {
723
953
  *
724
954
  * @category Pointers
725
955
  */
726
- export interface PointerInstance {
956
+ export interface PointerInstance<T = any> {
727
957
  /** The pointer type definition this instance was created from. */
728
- readonly _pointerType: PointerTypeDef;
958
+ readonly _pointerType: PointerTypeDef<T>;
729
959
  /** The base type this pointer points to. */
730
960
  readonly _baseType: AnyType | StructDef;
731
961
  /** Size of the pointed-to type in bytes. */
@@ -735,24 +965,27 @@ export interface PointerInstance {
735
965
  readonly address: bigint;
736
966
 
737
967
  /**
738
- * Dereference the pointer — read/write the value at the pointed location.
739
- *
740
- * Python equivalent: `p.contents`
968
+ * The pointed object, as Python's `p.contents`: a live instance on the
969
+ * pointed memory (`p.contents.value` for simple types, `p.contents.x` for
970
+ * structures). Assigning an instance re-points the pointer to it; assigning
971
+ * a plain value writes it.
741
972
  *
742
973
  * @example
743
974
  * ```javascript
744
975
  * const p = POINTER(c_int32).fromBuffer(buf);
745
- * console.log(p.contents); // read value
746
- * p.contents = 42; // write value
976
+ * console.log(p.contents.value); // read value
977
+ * p.contents = 42; // write value
978
+ * p.contents = new c_int32(7); // re-point
747
979
  * ```
748
980
  */
749
- contents: any;
981
+ get contents(): PointerContents<T>;
982
+ set contents(value: PointerContents<T> | JsArgFromCType<T>);
750
983
 
751
984
  /** The underlying buffer (if created from a buffer), or null. */
752
985
  readonly _buffer: Buffer | null;
753
986
 
754
- /** Alias for contents getter. */
755
- deref(): any;
987
+ /** Alias for the contents getter. */
988
+ deref(): PointerContents<T>;
756
989
 
757
990
  /**
758
991
  * Set pointer to a new target (buffer or address).
@@ -782,19 +1015,19 @@ export interface PointerInstance {
782
1015
  * arr[2] = 99; // write to third element
783
1016
  * ```
784
1017
  */
785
- [index: number]: any;
1018
+ [index: number]: PointerValue<T>;
786
1019
 
787
1020
  /**
788
1021
  * Return a new pointer offset by `n` elements (not bytes), matching C's
789
1022
  * `ptr + n`. The pointer keeps the same element type.
790
1023
  */
791
- add(n: number): PointerInstance;
1024
+ add(n: number): PointerInstance<T>;
792
1025
 
793
1026
  /**
794
1027
  * Read `end - start` consecutive elements into a JS array, analogous to
795
1028
  * Python's `p[start:end]` on a POINTER(T).
796
1029
  */
797
- slice(start: number, end: number): any[];
1030
+ slice(start: number, end: number): PointerValue<T>[];
798
1031
  }
799
1032
 
800
1033
  /**
@@ -806,7 +1039,7 @@ export interface PointerInstance {
806
1039
  *
807
1040
  * // From existing buffer
808
1041
  * const p = IntPtr.fromBuffer(buf);
809
- * console.log(p.contents); // 42
1042
+ * console.log(p.contents.value); // 42
810
1043
  * console.log(p[0]); // 42
811
1044
  *
812
1045
  * // From raw address (e.g., from a struct's c_void_p field)
@@ -816,9 +1049,9 @@ export interface PointerInstance {
816
1049
  *
817
1050
  * @category Pointers
818
1051
  */
819
- export interface PointerTypeDef {
1052
+ export interface PointerTypeDef<T = any> {
820
1053
  /** The type this pointer points to. */
821
- readonly _pointerTo: AnyType | StructDef;
1054
+ readonly _pointerTo: AnyType | StructDef | StructureClass | PointerTypeDef;
822
1055
  /** Size of the pointed-to type. */
823
1056
  readonly _baseSize: number;
824
1057
  /** Pointer size (always 8 on 64-bit). */
@@ -833,7 +1066,7 @@ export interface PointerTypeDef {
833
1066
  * console.log(p.isNull); // true
834
1067
  * ```
835
1068
  */
836
- create(value?: Buffer | bigint | number): PointerInstance;
1069
+ create(value?: Buffer | bigint | number): PointerInstance<T>;
837
1070
 
838
1071
  /**
839
1072
  * Create a pointer from an existing buffer (points to that buffer's memory).
@@ -845,10 +1078,10 @@ export interface PointerTypeDef {
845
1078
  * const buf = Buffer.alloc(4);
846
1079
  * buf.writeInt32LE(42, 0);
847
1080
  * const p = POINTER(c_int32).fromBuffer(buf);
848
- * console.log(p.contents); // 42
1081
+ * console.log(p.contents.value); // 42
849
1082
  * ```
850
1083
  */
851
- fromBuffer(targetBuf: Buffer): PointerInstance;
1084
+ fromBuffer(targetBuf: Buffer): PointerInstance<T>;
852
1085
 
853
1086
  /**
854
1087
  * Create a pointer from a raw memory address.
@@ -867,7 +1100,7 @@ export interface PointerTypeDef {
867
1100
  * }
868
1101
  * ```
869
1102
  */
870
- fromAddress(address: bigint | number): PointerInstance;
1103
+ fromAddress(address: bigint | number): PointerInstance<T>;
871
1104
 
872
1105
  /**
873
1106
  * @deprecated Use pointer instance `.contents` instead.
@@ -959,17 +1192,20 @@ export class Structure<F extends Record<string, FieldSpec> = Record<string, any>
959
1192
  * ];
960
1193
  * ```
961
1194
  */
962
- static _fields_?: Array<[string, FieldSpec]> | Record<string, FieldSpec>;
1195
+ static _fields_?: ReadonlyArray<FieldEntry> | Record<string, FieldSpec>;
963
1196
 
964
- /** If `true`, disables padding between fields. */
965
- static _pack_?: boolean;
1197
+ /**
1198
+ * Maximum field alignment in bytes, as Python's `_pack_` (`1` = no padding).
1199
+ * `true` is accepted as `1`.
1200
+ */
1201
+ static _pack_?: number | boolean;
966
1202
 
967
1203
  /**
968
1204
  * List of field names whose members are promoted to the parent struct.
969
1205
  *
970
1206
  * Python equivalent: `_anonymous_`
971
1207
  */
972
- static _anonymous_?: string[];
1208
+ static _anonymous_?: ReadonlyArray<string>;
973
1209
 
974
1210
  /** Create instance with optional initial values. */
975
1211
  static create<ThisT extends Structure<F>>(this: new (...args: any[]) => ThisT, values?: Partial<FieldsToInstance<F>> | Buffer): ThisT;
@@ -1153,7 +1389,7 @@ export function load(path: string | null): Library;
1153
1389
  *
1154
1390
  * @category Callbacks
1155
1391
  */
1156
- export function callback(fn: Function, returnType: AnyType, argTypes?: AnyType[]): CallbackWrapper;
1392
+ export function callback(fn: Function, returnType: AnyType | null, argTypes?: AnyType[]): CallbackWrapper;
1157
1393
 
1158
1394
  /**
1159
1395
  * Create a thread-safe callback that can be invoked from any thread.
@@ -1166,7 +1402,7 @@ export function callback(fn: Function, returnType: AnyType, argTypes?: AnyType[]
1166
1402
  *
1167
1403
  * @category Callbacks
1168
1404
  */
1169
- export function threadSafeCallback(fn: Function, returnType: AnyType, argTypes?: AnyType[]): CallbackWrapper;
1405
+ export function threadSafeCallback(fn: Function, returnType: AnyType | null, argTypes?: AnyType[]): CallbackWrapper;
1170
1406
 
1171
1407
  /**
1172
1408
  * Create a function pointer type with cdecl calling convention.
@@ -1218,12 +1454,21 @@ export interface ParamFlag {
1218
1454
  */
1219
1455
  export interface FuncPtrFactory {
1220
1456
  /** Call with a raw address to produce a caller. */
1221
- (address: bigint): (...args: any[]) => any;
1222
- /** Call with a JS function to produce a C-callable callback closure. */
1223
- (fn: (...args: any[]) => any): { pointer: bigint; release(): void };
1457
+ (address: bigint | number): (...args: any[]) => any;
1458
+ /**
1459
+ * Call with a JS function to produce a C-callable callback closure, usable
1460
+ * as argument or struct field of this type. Keep it referenced while C may
1461
+ * call it; `release()` frees it.
1462
+ */
1463
+ (fn: (...args: any[]) => any): { readonly pointer: bigint; readonly _as_parameter_: bigint; release(): void };
1464
+ /**
1465
+ * Bind an exported function of a library, optionally with paramflags.
1466
+ * Python: `prototype((name, dll))` / `prototype((name, dll), paramflags)`.
1467
+ */
1468
+ (spec: readonly [name: string, library: CDLL], paramflags?: ReadonlyArray<ParamFlag | readonly [flag: number, name?: string, defaultValue?: any]>): (...args: any[]) => any;
1224
1469
 
1225
- restype: AnyType;
1226
- argtypes: AnyType[];
1470
+ restype: FFIType | null;
1471
+ argtypes: FFIType[];
1227
1472
  readonly _isFuncPtr: true;
1228
1473
 
1229
1474
  /**
@@ -1244,10 +1489,10 @@ export interface FuncPtrFactory {
1244
1489
  * const [ok2, pid2, tid2] = fn({ hWnd: hwnd }); // named
1245
1490
  * ```
1246
1491
  */
1247
- bind(library: CDLL, symbolName: string, paramflags: ParamFlag[]): (...args: any[]) => any;
1492
+ bind(library: CDLL, symbolName: string, paramflags: ReadonlyArray<ParamFlag | readonly [flag: number, name?: string, defaultValue?: any]>): (...args: any[]) => any;
1248
1493
  }
1249
1494
 
1250
- export function CFUNCTYPE(restype: AnyType, ...argtypes: AnyType[]): FuncPtrFactory;
1495
+ export function CFUNCTYPE(restype: FFIType | null, ...argtypes: FFIType[]): FuncPtrFactory;
1251
1496
 
1252
1497
  /**
1253
1498
  * Create a function pointer type with stdcall calling convention (Windows).
@@ -1262,7 +1507,7 @@ export function CFUNCTYPE(restype: AnyType, ...argtypes: AnyType[]): FuncPtrFact
1262
1507
  *
1263
1508
  * @category Callbacks
1264
1509
  */
1265
- export function WINFUNCTYPE(restype: AnyType, ...argtypes: AnyType[]): FuncPtrFactory;
1510
+ export function WINFUNCTYPE(restype: FFIType | null, ...argtypes: FFIType[]): FuncPtrFactory;
1266
1511
 
1267
1512
  /**
1268
1513
  * Create a C string buffer (null-terminated).
@@ -1282,7 +1527,13 @@ export function WINFUNCTYPE(restype: AnyType, ...argtypes: AnyType[]): FuncPtrFa
1282
1527
  *
1283
1528
  * @category Memory
1284
1529
  */
1285
- export function create_string_buffer(init: number | string | Buffer): Buffer;
1530
+ export function create_string_buffer(init: number | string | Uint8Array, size?: number): Buffer & CharBufferValue;
1531
+
1532
+ /**
1533
+ * Alias of {@link create_string_buffer}. Python equivalent: `ctypes.c_buffer`.
1534
+ * @category Memory
1535
+ */
1536
+ export function c_buffer(init: number | string | Uint8Array, size?: number): Buffer & CharBufferValue;
1286
1537
 
1287
1538
  /**
1288
1539
  * Create a wide string buffer (wchar_t, null-terminated).
@@ -1295,7 +1546,7 @@ export function create_string_buffer(init: number | string | Buffer): Buffer;
1295
1546
  *
1296
1547
  * @category Memory
1297
1548
  */
1298
- export function create_unicode_buffer(init: number | string): Buffer;
1549
+ export function create_unicode_buffer(init: number | string, size?: number): Buffer & WideBufferValue;
1299
1550
 
1300
1551
  /**
1301
1552
  * Read a C string from an address or buffer.
@@ -1337,7 +1588,10 @@ export function addressof(ptr: Buffer | bigint | number): bigint;
1337
1588
  *
1338
1589
  * @category Memory
1339
1590
  */
1340
- export function memmove(dst: Buffer, src: Buffer | bigint, count: number): void;
1591
+ /** Memory argument of {@link memmove} / {@link memset}: a buffer, a ctypes instance, a pointer or an address. */
1592
+ export type MemoryTarget = Uint8Array | { readonly _buffer: Buffer } | PointerInstance | bigint | number;
1593
+
1594
+ export function memmove(dst: MemoryTarget, src: MemoryTarget, count: number): void;
1341
1595
 
1342
1596
  /**
1343
1597
  * Fill memory with a byte value.
@@ -1346,7 +1600,7 @@ export function memmove(dst: Buffer, src: Buffer | bigint, count: number): void;
1346
1600
  *
1347
1601
  * @category Memory
1348
1602
  */
1349
- export function memset(dst: Buffer, value: number, count: number): void;
1603
+ export function memset(dst: MemoryTarget, value: number, count: number): void;
1350
1604
 
1351
1605
  /**
1352
1606
  * Read a typed value from a buffer at a given offset.
@@ -1364,8 +1618,8 @@ export function memset(dst: Buffer, value: number, count: number): void;
1364
1618
  *
1365
1619
  * @category Memory
1366
1620
  */
1367
- export function readValue<T extends AnyType>(ptr: Buffer | bigint | number, type: T, offset?: number): JsFromCType<T>;
1368
- export function readValue(ptr: Buffer | bigint | number, type: AnyType, offset?: number): any;
1621
+ export function readValue<T extends AnyType>(ptr: Buffer | bigint | number | PointerInstance, type: T, offset?: number): JsFromCType<T>;
1622
+ export function readValue(ptr: Buffer | bigint | number | PointerInstance, type: AnyType | StructureClass, offset?: number): any;
1369
1623
 
1370
1624
  /**
1371
1625
  * Write a typed value to a buffer at a given offset.
@@ -1377,8 +1631,8 @@ export function readValue(ptr: Buffer | bigint | number, type: AnyType, offset?:
1377
1631
  *
1378
1632
  * @category Memory
1379
1633
  */
1380
- export function writeValue<T extends AnyType>(ptr: Buffer | bigint | number, type: T, value: JsArgFromCType<T>, offset?: number): number | void;
1381
- export function writeValue(ptr: Buffer | bigint | number, type: AnyType, value: any, offset?: number): number | void;
1634
+ export function writeValue<T extends AnyType>(ptr: Buffer | bigint | number | PointerInstance, type: T, value: JsArgFromCType<T>, offset?: number): number | void;
1635
+ export function writeValue(ptr: Buffer | bigint | number | PointerInstance, type: AnyType | StructureClass, value: any, offset?: number): number | void;
1382
1636
 
1383
1637
  /**
1384
1638
  * Get the size of a type in bytes.
@@ -1394,7 +1648,7 @@ export function writeValue(ptr: Buffer | bigint | number, type: AnyType, value:
1394
1648
  *
1395
1649
  * @category Memory
1396
1650
  */
1397
- export function sizeof(type: AnyType | StructDef | ArrayTypeDef): number;
1651
+ export function sizeof(type: AnyType | StructDef | ArrayTypeDef | StructureClass | PointerTypeDef | FuncPtrFactory | SimpleCDataInstance | Structure<any> | Uint8Array): number;
1398
1652
 
1399
1653
  /**
1400
1654
  * Get the alignment requirement of a type in bytes.
@@ -1410,7 +1664,7 @@ export function sizeof(type: AnyType | StructDef | ArrayTypeDef): number;
1410
1664
  *
1411
1665
  * @category Memory
1412
1666
  */
1413
- export function alignment(type: AnyType | StructDef | ArrayTypeDef | typeof Structure | typeof Union): number;
1667
+ export function alignment(type: AnyType | StructDef | ArrayTypeDef | StructureClass | PointerTypeDef | FuncPtrFactory | SimpleCDataInstance | Structure<any>): number;
1414
1668
 
1415
1669
  /**
1416
1670
  * Create a Buffer view of native memory at a given address.
@@ -1441,7 +1695,7 @@ export function ptrToBuffer(address: bigint | number, size: number): Buffer;
1441
1695
  *
1442
1696
  * @category Structures
1443
1697
  */
1444
- export function struct(fields: Record<string, FieldSpec>, options?: StructOptions): StructDef;
1698
+ export function struct<F extends Record<string, FieldSpec>>(fields: F, options?: StructOptions): StructDef<F>;
1445
1699
 
1446
1700
  /**
1447
1701
  * Define a union using the functional API.
@@ -1452,7 +1706,7 @@ export function struct(fields: Record<string, FieldSpec>, options?: StructOption
1452
1706
  *
1453
1707
  * @category Structures
1454
1708
  */
1455
- export function union(fields: Record<string, FieldSpec>): UnionDef;
1709
+ export function union<F extends Record<string, FieldSpec>>(fields: F): UnionDef<F>;
1456
1710
 
1457
1711
  /**
1458
1712
  * Factory that returns a Structure subclass with typed fields.
@@ -1490,7 +1744,13 @@ export function defineUnion<F extends Record<string, FieldSpec>>(fields: F): new
1490
1744
  *
1491
1745
  * @category Structures
1492
1746
  */
1493
- export function array(elementType: AnyType | typeof Structure | typeof Union, count: number): ArrayTypeDef;
1747
+ export function array<E extends AnyType | StructureClass | ArrayTypeDef | PointerTypeDef | FuncPtrFactory>(elementType: E, count: number): ArrayTypeDef<E>;
1748
+
1749
+ /**
1750
+ * Alias of {@link array}. Python equivalent: `ctypes.ARRAY(type, length)`.
1751
+ * @category Structures
1752
+ */
1753
+ export function ARRAY<E extends AnyType | StructureClass | ArrayTypeDef | PointerTypeDef | FuncPtrFactory>(elementType: E, count: number): ArrayTypeDef<E>;
1494
1754
 
1495
1755
  /**
1496
1756
  * Define a bit field for use in struct `_fields_`.
@@ -1551,8 +1811,8 @@ export function byref(obj: Buffer | SimpleCDataInstance | { _buffer: Buffer }):
1551
1811
  *
1552
1812
  * @category Pointers
1553
1813
  */
1554
- export function cast(ptr: Buffer | bigint | number | SimpleCDataInstance, targetType: PointerTypeDef): PointerInstance;
1555
- export function cast(ptr: Buffer | bigint | number | SimpleCDataInstance, targetType: AnyType | StructDef): any;
1814
+ export function cast<T>(ptr: Buffer | bigint | number | SimpleCDataInstance, targetType: PointerTypeDef<T>): PointerInstance<T>;
1815
+ export function cast(ptr: Buffer | bigint | number | SimpleCDataInstance, targetType: AnyType | StructDef | StructureClass): any;
1556
1816
 
1557
1817
  /**
1558
1818
  * Create a pointer type for a given base type.
@@ -1569,7 +1829,7 @@ export function cast(ptr: Buffer | bigint | number | SimpleCDataInstance, target
1569
1829
  * buf.writeInt32LE(42, 0);
1570
1830
  *
1571
1831
  * const p = IntPtr.fromBuffer(buf);
1572
- * console.log(p.contents); // 42
1832
+ * console.log(p.contents.value); // 42
1573
1833
  * console.log(p[0]); // 42
1574
1834
  * ```
1575
1835
  *
@@ -1588,7 +1848,9 @@ export function cast(ptr: Buffer | bigint | number | SimpleCDataInstance, target
1588
1848
  *
1589
1849
  * @category Pointers
1590
1850
  */
1591
- export function POINTER(baseType: AnyType | StructDef): PointerTypeDef;
1851
+ export function POINTER<T extends AnyType | StructureClass | PointerTypeDef>(baseType: T): PointerTypeDef<T>;
1852
+ /** Lazy base type, for self-referential structs: `POINTER(() => Node)`. */
1853
+ export function POINTER<T extends AnyType | StructureClass>(baseType: () => T): PointerTypeDef<T>;
1592
1854
 
1593
1855
  /**
1594
1856
  * Create a pointer to an existing ctypes object.
@@ -1602,14 +1864,16 @@ export function POINTER(baseType: AnyType | StructDef): PointerTypeDef;
1602
1864
  * ```javascript
1603
1865
  * const x = new c_int32(42);
1604
1866
  * const p = pointer(x);
1605
- * console.log(p.contents); // 42
1867
+ * console.log(p.contents.value); // 42
1606
1868
  * p.contents = 100;
1607
1869
  * console.log(x.value); // 100
1608
1870
  * ```
1609
1871
  *
1610
1872
  * @category Pointers
1611
1873
  */
1612
- export function pointer(obj: SimpleCDataInstance | { _buffer: Buffer }): PointerInstance;
1874
+ export function pointer<T extends Structure<any>>(obj: T): PointerInstance<new (...args: any[]) => T>;
1875
+ export function pointer<V>(obj: SimpleCDataInstance<V>): PointerInstance;
1876
+ export function pointer(obj: Buffer | { _buffer: Buffer }): PointerInstance;
1613
1877
 
1614
1878
  /**
1615
1879
  * Get the C library errno value.
@@ -1643,7 +1907,35 @@ export function GetLastError(): number;
1643
1907
  *
1644
1908
  * @category Error Handling
1645
1909
  */
1646
- export function SetLastError(code: number): void;
1910
+ export function SetLastError(code: number): number;
1911
+
1912
+ /**
1913
+ * Python name of {@link GetLastError}: the error code captured by the last
1914
+ * call. Python equivalent: `ctypes.get_last_error()`
1915
+ *
1916
+ * @category Error Handling
1917
+ */
1918
+ export function get_last_error(): number;
1919
+
1920
+ /**
1921
+ * Python name of {@link SetLastError}; returns the previous value.
1922
+ * Python equivalent: `ctypes.set_last_error(value)`
1923
+ *
1924
+ * @category Error Handling
1925
+ */
1926
+ export function set_last_error(code: number): number;
1927
+
1928
+ /**
1929
+ * Raised when a function argument cannot be converted to its `argtypes` type,
1930
+ * with the message `"argument N: TypeError: ..."`. Subclass of `TypeError`.
1931
+ *
1932
+ * Python equivalent: `ctypes.ArgumentError`
1933
+ *
1934
+ * @category Error Handling
1935
+ */
1936
+ export class ArgumentError extends TypeError {
1937
+ constructor(message?: string);
1938
+ }
1647
1939
 
1648
1940
  /**
1649
1941
  * Format a Windows error code into a human-readable message (Windows only).
@@ -1712,19 +2004,21 @@ export interface SimpleCDataConstructor<Tag extends string = string> {
1712
2004
  */
1713
2005
  export type JsFromTag<Tag extends string> = Tag extends "void"
1714
2006
  ? void
1715
- : Tag extends "int8" | "uint8" | "int16" | "uint16" | "int32" | "uint32" | "float" | "double" | "char" | "wchar"
1716
- ? number
1717
- : Tag extends "int64" | "uint64" | "size_t" | "ssize_t" | "long" | "ulong"
1718
- ? bigint
1719
- : Tag extends "bool"
1720
- ? boolean
1721
- : Tag extends "string"
1722
- ? string | null
1723
- : Tag extends "wstring"
2007
+ : Tag extends "char" | "wchar"
2008
+ ? string
2009
+ : Tag extends "int8" | "uint8" | "int16" | "uint16" | "int32" | "uint32" | "float" | "double"
2010
+ ? number
2011
+ : Tag extends "int64" | "uint64" | "size_t" | "ssize_t" | "long" | "ulong"
2012
+ ? bigint
2013
+ : Tag extends "bool"
2014
+ ? boolean
2015
+ : Tag extends "string"
1724
2016
  ? string | null
1725
- : Tag extends "pointer"
1726
- ? bigint | Buffer | null
1727
- : any;
2017
+ : Tag extends "wstring"
2018
+ ? string | null
2019
+ : Tag extends "pointer"
2020
+ ? bigint | Buffer | null
2021
+ : any;
1728
2022
 
1729
2023
  /**
1730
2024
  * Maps a SimpleCData tag to accepted JavaScript **input** types (what writes/args accept).
@@ -1734,19 +2028,23 @@ export type JsFromTag<Tag extends string> = Tag extends "void"
1734
2028
  */
1735
2029
  export type JsArgFromTag<Tag extends string> = Tag extends "void"
1736
2030
  ? never
1737
- : Tag extends "int8" | "uint8" | "int16" | "uint16" | "int32" | "uint32" | "float" | "double" | "char" | "wchar"
1738
- ? number
1739
- : Tag extends "int64" | "uint64" | "size_t" | "ssize_t" | "long" | "ulong"
1740
- ? bigint | number
1741
- : Tag extends "bool"
1742
- ? boolean | number
1743
- : Tag extends "string"
1744
- ? string | Buffer | null
1745
- : Tag extends "wstring"
1746
- ? string | Buffer | null
1747
- : Tag extends "pointer"
1748
- ? bigint | Buffer | number | null
1749
- : any;
2031
+ : Tag extends "char"
2032
+ ? string | number | Uint8Array
2033
+ : Tag extends "wchar"
2034
+ ? string | number
2035
+ : Tag extends "int8" | "uint8" | "int16" | "uint16" | "int32" | "uint32" | "float" | "double"
2036
+ ? number
2037
+ : Tag extends "int64" | "uint64" | "size_t" | "ssize_t" | "long" | "ulong"
2038
+ ? bigint | number
2039
+ : Tag extends "bool"
2040
+ ? boolean | number
2041
+ : Tag extends "string"
2042
+ ? string | Buffer | null
2043
+ : Tag extends "wstring"
2044
+ ? string | Buffer | null
2045
+ : Tag extends "pointer"
2046
+ ? bigint | Buffer | number | null | { readonly _as_parameter_: unknown }
2047
+ : any;
1750
2048
 
1751
2049
  /**
1752
2050
  * Instance of a simple C data type.
@@ -1807,11 +2105,20 @@ export const c_uint64: SimpleCDataConstructor<"uint64">;
1807
2105
  export const c_float: SimpleCDataConstructor<"float">;
1808
2106
  /** 64-bit double. Python: `ctypes.c_double` @category Types */
1809
2107
  export const c_double: SimpleCDataConstructor<"double">;
1810
- /** 8-bit character. Python: `ctypes.c_char` @category Types */
2108
+ /**
2109
+ * 1-byte character. Python: `ctypes.c_char`. Values are 1-character strings
2110
+ * (Python `bytes` of length 1); writes also accept a byte number (0..255) or a
2111
+ * 1-byte Buffer.
2112
+ * @category Types
2113
+ */
1811
2114
  export const c_char: SimpleCDataConstructor<"char">;
1812
2115
  /** Pointer to null-terminated string. Python: `ctypes.c_char_p` @category Types */
1813
2116
  export const c_char_p: SimpleCDataConstructor<"string">;
1814
- /** Wide character. Python: `ctypes.c_wchar` @category Types */
2117
+ /**
2118
+ * Wide character (`wchar_t`). Python: `ctypes.c_wchar`. Values are 1-character
2119
+ * strings; writes also accept a code point number.
2120
+ * @category Types
2121
+ */
1815
2122
  export const c_wchar: SimpleCDataConstructor<"wchar">;
1816
2123
  /** Pointer to null-terminated wide string. Python: `ctypes.c_wchar_p` @category Types */
1817
2124
  export const c_wchar_p: SimpleCDataConstructor<"wstring">;
@@ -1840,6 +2147,213 @@ export const c_ushort: SimpleCDataConstructor<"uint16">;
1840
2147
  export const c_longlong: SimpleCDataConstructor<"int64">;
1841
2148
  /** Alias for `c_uint64`. Python: `ctypes.c_ulonglong` @category Types */
1842
2149
  export const c_ulonglong: SimpleCDataConstructor<"uint64">;
2150
+ /** Alias of {@link c_void_p}. Python: `ctypes.c_voidp` @category Types */
2151
+ export const c_voidp: SimpleCDataConstructor<"pointer">;
2152
+ /** `time_t` (64-bit). Python: `ctypes.c_time_t` @category Types */
2153
+ export const c_time_t: SimpleCDataConstructor<"int64">;
2154
+
2155
+ /**
2156
+ * A Structure class with known fields (used by {@link wintypes}).
2157
+ * @category Types
2158
+ */
2159
+ export type StructureOf<T> = (new (...args: any[]) => Structure<any> & T) & Omit<typeof Structure, "prototype">;
2160
+
2161
+ type W_BYTE = SimpleCDataConstructor<"uint8">;
2162
+ type W_WORD = SimpleCDataConstructor<"uint16">;
2163
+ type W_DWORD = SimpleCDataConstructor<"ulong">;
2164
+ type W_LONG = SimpleCDataConstructor<"long">;
2165
+ type W_SHORT = SimpleCDataConstructor<"int16">;
2166
+ type W_HANDLE = SimpleCDataConstructor<"pointer">;
2167
+ type W_RECT = StructureOf<{ left: bigint; top: bigint; right: bigint; bottom: bigint }>;
2168
+ type W_POINT = StructureOf<{ x: bigint; y: bigint }>;
2169
+ type W_SIZE = StructureOf<{ cx: bigint; cy: bigint }>;
2170
+ type W_SMALL_RECT = StructureOf<{ Left: number; Top: number; Right: number; Bottom: number }>;
2171
+ type W_FILETIME = StructureOf<{ dwLowDateTime: bigint; dwHighDateTime: bigint }>;
2172
+ type W_MSG = StructureOf<{ hWnd: bigint | null; message: number; wParam: bigint; lParam: bigint; time: bigint; pt: InstanceType<W_POINT> }>;
2173
+ type W_FIND_DATA = StructureOf<{
2174
+ dwFileAttributes: bigint;
2175
+ ftCreationTime: InstanceType<W_FILETIME>;
2176
+ ftLastAccessTime: InstanceType<W_FILETIME>;
2177
+ ftLastWriteTime: InstanceType<W_FILETIME>;
2178
+ nFileSizeHigh: bigint;
2179
+ nFileSizeLow: bigint;
2180
+ dwReserved0: bigint;
2181
+ dwReserved1: bigint;
2182
+ cFileName: string;
2183
+ cAlternateFileName: string;
2184
+ }>;
2185
+
2186
+ /**
2187
+ * Windows API types, as Python's `ctypes.wintypes`: the same names, aliases,
2188
+ * structures (`RECT`, `POINT`, `SIZE`, `MSG`, `FILETIME`, ...) and pointer
2189
+ * types (`LPDWORD = POINTER(DWORD)`, ...), plus common extras (`QWORD`,
2190
+ * `LRESULT`, `UINT_PTR`, `LSTATUS`, ...). Available on every platform.
2191
+ *
2192
+ * @example
2193
+ * ```javascript
2194
+ * import { wintypes } from "node-ctypes";
2195
+ * const { HWND, UINT, RECT, LPRECT } = wintypes;
2196
+ * ```
2197
+ *
2198
+ * @category Types
2199
+ */
2200
+ export const wintypes: {
2201
+ readonly BYTE: W_BYTE;
2202
+ readonly WORD: W_WORD;
2203
+ readonly DWORD: W_DWORD;
2204
+ readonly CHAR: SimpleCDataConstructor<"char">;
2205
+ readonly WCHAR: SimpleCDataConstructor<"wchar">;
2206
+ readonly UINT: SimpleCDataConstructor<"uint32">;
2207
+ readonly INT: SimpleCDataConstructor<"int32">;
2208
+ readonly DOUBLE: SimpleCDataConstructor<"double">;
2209
+ readonly FLOAT: SimpleCDataConstructor<"float">;
2210
+ readonly BOOLEAN: W_BYTE;
2211
+ readonly BOOL: W_LONG;
2212
+ readonly VARIANT_BOOL: SimpleCDataConstructor<"bool">;
2213
+ readonly ULONG: W_DWORD;
2214
+ readonly LONG: W_LONG;
2215
+ readonly USHORT: W_WORD;
2216
+ readonly SHORT: W_SHORT;
2217
+ readonly _LARGE_INTEGER: SimpleCDataConstructor<"int64">;
2218
+ readonly LARGE_INTEGER: SimpleCDataConstructor<"int64">;
2219
+ readonly _ULARGE_INTEGER: SimpleCDataConstructor<"uint64">;
2220
+ readonly ULARGE_INTEGER: SimpleCDataConstructor<"uint64">;
2221
+ readonly LPCOLESTR: SimpleCDataConstructor<"wstring">;
2222
+ readonly LPOLESTR: SimpleCDataConstructor<"wstring">;
2223
+ readonly OLESTR: SimpleCDataConstructor<"wstring">;
2224
+ readonly LPCWSTR: SimpleCDataConstructor<"wstring">;
2225
+ readonly LPWSTR: SimpleCDataConstructor<"wstring">;
2226
+ readonly LPCSTR: SimpleCDataConstructor<"string">;
2227
+ readonly LPSTR: SimpleCDataConstructor<"string">;
2228
+ readonly LPCVOID: W_HANDLE;
2229
+ readonly LPVOID: W_HANDLE;
2230
+ readonly WPARAM: SimpleCDataConstructor<"size_t">;
2231
+ readonly LPARAM: SimpleCDataConstructor<"ssize_t">;
2232
+ readonly ATOM: W_WORD;
2233
+ readonly LANGID: W_WORD;
2234
+ readonly COLORREF: W_DWORD;
2235
+ readonly LGRPID: W_DWORD;
2236
+ readonly LCTYPE: W_DWORD;
2237
+ readonly LCID: W_DWORD;
2238
+ readonly HANDLE: W_HANDLE;
2239
+ readonly HACCEL: W_HANDLE;
2240
+ readonly HBITMAP: W_HANDLE;
2241
+ readonly HBRUSH: W_HANDLE;
2242
+ readonly HCOLORSPACE: W_HANDLE;
2243
+ readonly HDC: W_HANDLE;
2244
+ readonly HDESK: W_HANDLE;
2245
+ readonly HDWP: W_HANDLE;
2246
+ readonly HENHMETAFILE: W_HANDLE;
2247
+ readonly HFONT: W_HANDLE;
2248
+ readonly HGDIOBJ: W_HANDLE;
2249
+ readonly HGLOBAL: W_HANDLE;
2250
+ readonly HHOOK: W_HANDLE;
2251
+ readonly HICON: W_HANDLE;
2252
+ readonly HINSTANCE: W_HANDLE;
2253
+ readonly HKEY: W_HANDLE;
2254
+ readonly HKL: W_HANDLE;
2255
+ readonly HLOCAL: W_HANDLE;
2256
+ readonly HMENU: W_HANDLE;
2257
+ readonly HMETAFILE: W_HANDLE;
2258
+ readonly HMODULE: W_HANDLE;
2259
+ readonly HMONITOR: W_HANDLE;
2260
+ readonly HPALETTE: W_HANDLE;
2261
+ readonly HPEN: W_HANDLE;
2262
+ readonly HRGN: W_HANDLE;
2263
+ readonly HRSRC: W_HANDLE;
2264
+ readonly HSTR: W_HANDLE;
2265
+ readonly HTASK: W_HANDLE;
2266
+ readonly HWINSTA: W_HANDLE;
2267
+ readonly HWND: W_HANDLE;
2268
+ readonly SC_HANDLE: W_HANDLE;
2269
+ readonly SERVICE_STATUS_HANDLE: W_HANDLE;
2270
+ readonly RECT: W_RECT;
2271
+ readonly tagRECT: W_RECT;
2272
+ readonly _RECTL: W_RECT;
2273
+ readonly RECTL: W_RECT;
2274
+ readonly _SMALL_RECT: W_SMALL_RECT;
2275
+ readonly SMALL_RECT: W_SMALL_RECT;
2276
+ readonly _COORD: StructureOf<{ X: number; Y: number }>;
2277
+ readonly POINT: W_POINT;
2278
+ readonly tagPOINT: W_POINT;
2279
+ readonly _POINTL: W_POINT;
2280
+ readonly POINTL: W_POINT;
2281
+ readonly SIZE: W_SIZE;
2282
+ readonly tagSIZE: W_SIZE;
2283
+ readonly SIZEL: W_SIZE;
2284
+ /** `red + (green << 8) + (blue << 16)` */
2285
+ RGB(red: number, green: number, blue: number): number;
2286
+ readonly FILETIME: W_FILETIME;
2287
+ readonly _FILETIME: W_FILETIME;
2288
+ readonly MSG: W_MSG;
2289
+ readonly tagMSG: W_MSG;
2290
+ readonly MAX_PATH: 260;
2291
+ readonly WIN32_FIND_DATAA: W_FIND_DATA;
2292
+ readonly WIN32_FIND_DATAW: W_FIND_DATA;
2293
+ readonly LPBOOL: PointerTypeDef<W_LONG>;
2294
+ readonly PBOOL: PointerTypeDef<W_LONG>;
2295
+ readonly PBOOLEAN: PointerTypeDef<W_BYTE>;
2296
+ readonly LPBYTE: PointerTypeDef<W_BYTE>;
2297
+ readonly PBYTE: PointerTypeDef<W_BYTE>;
2298
+ readonly PCHAR: PointerTypeDef<SimpleCDataConstructor<"char">>;
2299
+ readonly LPCOLORREF: PointerTypeDef<W_DWORD>;
2300
+ readonly LPDWORD: PointerTypeDef<W_DWORD>;
2301
+ readonly PDWORD: PointerTypeDef<W_DWORD>;
2302
+ readonly LPFILETIME: PointerTypeDef<W_FILETIME>;
2303
+ readonly PFILETIME: PointerTypeDef<W_FILETIME>;
2304
+ readonly PFLOAT: PointerTypeDef<SimpleCDataConstructor<"float">>;
2305
+ readonly LPHANDLE: PointerTypeDef<W_HANDLE>;
2306
+ readonly PHANDLE: PointerTypeDef<W_HANDLE>;
2307
+ readonly PHKEY: PointerTypeDef<W_HANDLE>;
2308
+ readonly LPHKL: PointerTypeDef<W_HANDLE>;
2309
+ readonly LPINT: PointerTypeDef<SimpleCDataConstructor<"int32">>;
2310
+ readonly PINT: PointerTypeDef<SimpleCDataConstructor<"int32">>;
2311
+ readonly PLARGE_INTEGER: PointerTypeDef<SimpleCDataConstructor<"int64">>;
2312
+ readonly PLCID: PointerTypeDef<W_DWORD>;
2313
+ readonly LPLONG: PointerTypeDef<W_LONG>;
2314
+ readonly PLONG: PointerTypeDef<W_LONG>;
2315
+ readonly LPMSG: PointerTypeDef<W_MSG>;
2316
+ readonly PMSG: PointerTypeDef<W_MSG>;
2317
+ readonly LPPOINT: PointerTypeDef<W_POINT>;
2318
+ readonly PPOINT: PointerTypeDef<W_POINT>;
2319
+ readonly PPOINTL: PointerTypeDef<W_POINT>;
2320
+ readonly LPRECT: PointerTypeDef<W_RECT>;
2321
+ readonly PRECT: PointerTypeDef<W_RECT>;
2322
+ readonly LPRECTL: PointerTypeDef<W_RECT>;
2323
+ readonly PRECTL: PointerTypeDef<W_RECT>;
2324
+ readonly LPSC_HANDLE: PointerTypeDef<W_HANDLE>;
2325
+ readonly PSHORT: PointerTypeDef<W_SHORT>;
2326
+ readonly LPSIZE: PointerTypeDef<W_SIZE>;
2327
+ readonly PSIZE: PointerTypeDef<W_SIZE>;
2328
+ readonly LPSIZEL: PointerTypeDef<W_SIZE>;
2329
+ readonly PSIZEL: PointerTypeDef<W_SIZE>;
2330
+ readonly PSMALL_RECT: PointerTypeDef<W_SMALL_RECT>;
2331
+ readonly LPUINT: PointerTypeDef<SimpleCDataConstructor<"uint32">>;
2332
+ readonly PUINT: PointerTypeDef<SimpleCDataConstructor<"uint32">>;
2333
+ readonly PULARGE_INTEGER: PointerTypeDef<SimpleCDataConstructor<"uint64">>;
2334
+ readonly PULONG: PointerTypeDef<W_DWORD>;
2335
+ readonly PUSHORT: PointerTypeDef<W_WORD>;
2336
+ readonly PWCHAR: PointerTypeDef<SimpleCDataConstructor<"wchar">>;
2337
+ readonly LPWIN32_FIND_DATAA: PointerTypeDef<W_FIND_DATA>;
2338
+ readonly PWIN32_FIND_DATAA: PointerTypeDef<W_FIND_DATA>;
2339
+ readonly LPWIN32_FIND_DATAW: PointerTypeDef<W_FIND_DATA>;
2340
+ readonly PWIN32_FIND_DATAW: PointerTypeDef<W_FIND_DATA>;
2341
+ readonly LPWORD: PointerTypeDef<W_WORD>;
2342
+ readonly PWORD: PointerTypeDef<W_WORD>;
2343
+ // Extras (not in Python's wintypes)
2344
+ readonly QWORD: SimpleCDataConstructor<"uint64">;
2345
+ readonly DWORDLONG: SimpleCDataConstructor<"uint64">;
2346
+ readonly LONGLONG: SimpleCDataConstructor<"int64">;
2347
+ readonly ULONGLONG: SimpleCDataConstructor<"uint64">;
2348
+ readonly PVOID: W_HANDLE;
2349
+ readonly HCURSOR: W_HANDLE;
2350
+ readonly LRESULT: SimpleCDataConstructor<"ssize_t">;
2351
+ readonly UINT_PTR: SimpleCDataConstructor<"size_t">;
2352
+ readonly LONG_PTR: SimpleCDataConstructor<"ssize_t">;
2353
+ readonly ULONG_PTR: SimpleCDataConstructor<"size_t">;
2354
+ readonly LSTATUS: W_LONG;
2355
+ readonly REGSAM: W_DWORD;
2356
+ };
1843
2357
 
1844
2358
  /**
1845
2359
  * Base class for creating custom simple C data types.
@@ -1869,6 +2383,32 @@ export const WCHAR_SIZE: number;
1869
2383
  */
1870
2384
  export const NULL: null;
1871
2385
 
2386
+ /**
2387
+ * Size of `time_t` in bytes. Python: `ctypes.SIZEOF_TIME_T`
2388
+ * @category Constants
2389
+ */
2390
+ export const SIZEOF_TIME_T: number;
2391
+
2392
+ /**
2393
+ * `dlopen` flag: symbols are available to subsequently loaded libraries
2394
+ * (0 on Windows). Python: `ctypes.RTLD_GLOBAL`
2395
+ * @category Constants
2396
+ */
2397
+ export const RTLD_GLOBAL: number;
2398
+
2399
+ /**
2400
+ * `dlopen` flag: symbols stay local to the library (0 on Windows).
2401
+ * Python: `ctypes.RTLD_LOCAL`
2402
+ * @category Constants
2403
+ */
2404
+ export const RTLD_LOCAL: number;
2405
+
2406
+ /**
2407
+ * Default `mode` of {@link CDLL} (`RTLD_LOCAL`). Python: `ctypes.DEFAULT_MODE`
2408
+ * @category Constants
2409
+ */
2410
+ export const DEFAULT_MODE: number;
2411
+
1872
2412
  /**
1873
2413
  * Resolve a library name to a platform-specific filename or path.
1874
2414
  *