win32-def/dist/index.types.d.cts

win32 definitions for node-ffi

import { BigIntStr, MethodTypeUnknown, ToAsyncFunction } from '@waiting/shared-types';
import { IKoffiCType, TypeSpecWithAlignment, IKoffiRegisteredCallback } from 'koffi';
export { IKoffiLib, IKoffiRegisteredCallback, KoffiFunction } from 'koffi';
import * as T from '##/lib/common.types.js';
import { PRINTER_STATUS } from '##/lib/consts/index.consts.js';

type _WIN64 = boolean;
type _UNICODE = boolean;
type StructTypeConstructor<T = object> = new () => Record<keyof T, string | number | BigIntStr | Buffer>;
/**
 * @link https://koffi.dev/functions#calling-conventions
 */
declare enum CallingConvention {
    Cdecl = "",
    Stdcall = "__stdcall",
    Fastcall = "__fastcall",
    Thiscall = "__thiscall"
}
type PID = number;
type PPID = number;
type FnDefName = string;
type FnDefParam = string;
type FnDefRetType = FnDefParam;
type FnDefMultipleChoiceParam = FnDefParam[];
/** Runtime input arguments of typeDef */
type FnDefArgs = FnDefParam[];
type FnDefCallParam = FnDefParam | FnDefMultipleChoiceParam;
/** Input parameters array of typeDef */
type FnDefCallParams = readonly FnDefCallParam[] | never[];
/** Full parameters include input/output of typeDef */
type FnDefFullParams = [FnDefRetType, FnDefCallParams];
type FuncDefListInner<T = DllFuncsType> = Map<(keyof T) & string, FnDefFullParams>;
type FuncDefList<T = DllFuncsType> = {
    [K in keyof T as K extends `${string}_Async` ? never : K & string]: any[] | readonly any[];
};
type FnDefListMap = Map<string, FnDefFullParams>;
/**
 * usage:
 * ```ts
 * import * as T from 'win32-def'
 * export interface Foo extends FM.DllFuncsModel {
 *   SDT_OpenPort(port: T.UINT): T.INT
 *   SDT_ClosePort(): T.INT
 * }
 * ```
 */
type DllFuncsType = Record<string, MethodTypeUnknown>;

interface LoadOptions<T = unknown> {
    dll: string;
    dllFuncs: FuncDefList<T>;
    usedFuncNames?: FnDefName[] | undefined;
    _WIN64?: boolean;
    /**
   * Calling convention
   * @default 'Cdecl'
   * @link https://koffi.dev/functions#calling-conventions
   */
    convention?: CallingConvention;
    /**
     * Create struct automatically from parameters of function definition list
     * @description param like 'POINT*' or 'POINT *', POINT_Factory() will be called
     * @default true
     */
    autoCreateStruct?: boolean;
    /**
     * Multiple choice mapper for function parameters
     */
    multipleChoiceMapperList?: MultipleChoiceMapperList;
    /**
     * Force re-register the library, overwriting the existing one
     * @default false
     */
    forceRegister?: boolean;
}
type LibDefBase = Record<string, FnDefFullParams>;
type LibDef2Type<T> = Record<Exclude<keyof T, 'prototype'>, (...args: any) => unknown>;
/**
 * FFI library containing functions
 */
type FLib<T extends object = DllFuncsType> = T & FLibExtMethods & {
    [K in keyof T as K extends `${string}_Async` ? K : `${K & string}_Async`]: T[K] extends (...args: any) => unknown ? ToAsyncFunction<T[K]> : never;
};
interface FLibExtMethods {
    /**
     * @note Unload the library
     * - On windows, it may cause later calls to functions in the library to fail!
     * - On some platforms (such as with the musl C library on Linux), shared libraries cannot be unloaded,
     *  so the library will remain loaded and memory mapped after the call to lib.unload().
     */
    unload: () => void;
    updateMultipleChoiceMapper: (options: UpdateMultipleChoiceMapperOptions) => void;
}
interface UpdateMultipleChoiceMapperOptions {
    /** update using name+Set */
    fnName?: string;
    mapperSet?: MultipleChoiceMapperSet;
    /** update using Map (contains name+Set) */
    mapperList?: MultipleChoiceMapperList;
}
/**
 * Multiple choice parameter mapper
 * return the matched function definition arguments if matched,
 * otherwise return undefined (will then match the next mapper)
 */
type _MultipleChoiceMapper<TRuntimeArgs extends any[] = any, TFnDefArgs extends string[] | readonly string[] = any> = (fnName: string, runtimeArgs: TRuntimeArgs, fnDefCallParamsExpanded: (Readonly<TFnDefArgs> | TFnDefArgs)[]) => TFnDefArgs | string[] | readonly string[] | undefined;
type MultipleChoiceMapper<TRuntimeArgs extends any[] = any, TFnDefArgs extends string[] | readonly string[] = any> = _MultipleChoiceMapper<TRuntimeArgs, TFnDefArgs> & {
    name: string;
};
type MultipleChoiceMapperList = Map<string, MultipleChoiceMapperSet>;
type MultipleChoiceMapperSet = Set<MultipleChoiceMapper>;
/**
 * The return value of payload always be new one after each call of the struct factory function or access payload
 */
interface StructFactoryResult<T extends object = object> extends StructDetail {
    /**
     * Struct payload for _Out_ or _Inout_ parameter
     */
    readonly payload: T;
    readonly sizeColumns?: PropertyKey[];
}
interface StructDetail {
    readonly name: string;
    readonly pointer: string;
    readonly CType: IKoffiCType;
    readonly size: number;
}
type StructFactory = () => StructFactoryResult;
interface StructInitType {
    [key: string]: string | IKoffiCType | StructFactory | StructInitType;
}
type StructInitPlainType = Record<string, TypeSpecWithAlignment>;

type _POINTER = Buffer;
type WNDPROC = IKoffiRegisteredCallback;
/** number: 32bit, bigint: 64bit  */
type PTR_Addr = number | BigIntStr;
/**
 * @link https://docs.microsoft.com/en-us/windows/win32/secauthz/access-mask-format
 */
type ACCESS_MASK = number;
type ATOM = number;
type DWORD = number;
type PVOID = Buffer;
/**
 * `uint32` or `uint64` used as value usage (memory address) instead of PVOID (Buffer),
 * Use `HANDLE` (number) for params definition of the api,
 * @see https://stackoverflow.com/questions/18266626/what-is-the-range-of-a-windows-handle-on-a-64-bits-application/29526711#29526711
 */
type HANDLE = number | BigIntStr;
/**
 * `HANDLE_PVOID` (Buffer) can be used for definition of Struct,
 */
type HANDLE_PVOID = PVOID;
type LONG_PTR = PTR_Addr;
type ULONG_PTR = PTR_Addr;
type VOID = any;
type WCHAR = UINT16;
type WCHAR_String = string;
type PWCHAR_String = _POINTER;
type BOOL = number;
type BOOLEAN = boolean;
type BYTE = number;
/** https://msdn.microsoft.com/en-us/library/windows/desktop/ms633573(v=vs.85).aspx */
type CALLBACK = WNDPROC;
type CCHAR = UINT8;
type CHAR = UINT8;
type COLORREF = number;
type DLGPROC = CALLBACK;
type DWORDLONG = number;
type DWORD_PTR = ULONG_PTR;
type DWORD32 = number;
type DWORD64 = BigIntStr;
type FLOAT = number;
type HACCEL = HANDLE;
type HALF_PTR = number;
type HBITMAP = HANDLE;
type HBRUSH = HANDLE;
type HCOLORSPACE = HANDLE;
type HCONV = HANDLE;
type HCONVLIST = HANDLE;
type HCURSOR = HANDLE;
type HDC = HANDLE;
type HDDEDATA = HANDLE;
type HDESK = HANDLE;
type HDROP = HANDLE;
type HDWP = HANDLE;
type HENHMETAFILE = HANDLE;
type HFILE = HANDLE;
type HFONT = HANDLE;
type HGDIOBJ = HANDLE;
type HGLOBAL = HANDLE;
type HHOOK = HANDLE;
type HICON = HANDLE;
type HINSTANCE = HANDLE;
type HKEY = HANDLE;
type HKL = HANDLE;
type HLOCAL = HANDLE;
type HMENU = HANDLE;
type HMETAFILE = HANDLE;
type HMODULE = HINSTANCE;
type HMONITOR = HANDLE;
type HPALETTE = HANDLE;
type HPEN = HANDLE;
type HRESULT = LONG;
type HRGN = HANDLE;
type HRSRC = HANDLE;
type HSZ = HANDLE;
type HWINEVENTHOOK = HANDLE;
type HWINSTA = HANDLE;
type HWND = HANDLE;
/** A 32-bit signed integer */
type INT = number;
type INT_PTR = PTR_Addr;
type INT8 = number;
type INT16 = number;
type INT32 = number;
type INT64 = BigIntStr;
type LANGID = WORD;
type LCID = DWORD;
type LCTYPE = DWORD;
type LGRPID = DWORD;
type LONG = number;
type LONGLONG = BigIntStr;
type LONG32 = number;
type LONG64 = BigIntStr;
type LPARAM = LONG_PTR;
type LPBOOL = _POINTER;
type LPBYTE = _POINTER;
type LPCOLORREF = _POINTER;
type LPCSTR = _POINTER;
type LPCWSTR = PUINT16 | string;
type LPCTSTR = PUINT16 | string;
type LPVOID = HANDLE;
type LPCVOID = LPVOID;
type LPDWORD = PUINT16 | string;
type LPHANDLE = _POINTER;
type LPINT = PINT;
type LPLONG = PINT32;
type LPSTR = _POINTER | string;
type LPWSTR = PUINT16 | string;
type LPTSTR = _POINTER | string;
type LPWORD = PUINT16;
type LRESULT = number;
type NTSTATUS = UINT32;
type PBOOL = _POINTER;
type PBOOLEAN = _POINTER;
type PBYTE = _POINTER;
type PCHAR = _POINTER;
type PCSTR = PUINT8;
type PCTSTR = _POINTER;
type PCWSTR = PUINT16 | string;
type PDWORD = PUINT32;
type PDWORDLONG = PUINT64;
type PDWORD_PTR = DWORD_PTR;
type PDWORD32 = _POINTER;
type PDWORD64 = _POINTER;
type PFLOAT = _POINTER;
type PHALF_PTR = _POINTER;
type PHANDLE = _POINTER;
type PHKEY = _POINTER;
type PINT = _POINTER;
type PINT_PTR = _POINTER;
type PINT8 = _POINTER;
type PINT16 = _POINTER;
type PINT32 = _POINTER;
type PINT64 = _POINTER;
type PLCID = _POINTER;
type PLONG = _POINTER;
type PLONGLONG = _POINTER;
type PLONG_PTR = _POINTER;
type PLONG32 = _POINTER;
type PLONG64 = _POINTER;
type POINTER_32 = _POINTER;
type POINTER_64 = _POINTER;
type POINTER_SIGNED = _POINTER;
type POINTER_UNSIGNED = _POINTER;
type PSHORT = _POINTER;
type PSIZE_T = _POINTER;
type PSSIZE_T = _POINTER;
type PSTR = _POINTER;
type PTBYTE = _POINTER;
type PTCHAR = _POINTER;
type PTSTR = _POINTER;
type PUCHAR = _POINTER;
type PUHALF_PTR = _POINTER;
type PUINT = _POINTER;
type PUINT_PTR = _POINTER;
type PUINT8 = _POINTER;
type PUINT16 = _POINTER;
type PUINT32 = _POINTER;
type PUINT64 = _POINTER;
type PULONG = _POINTER;
type PULONGLONG = _POINTER;
type PULONG_PTR = _POINTER;
type PULONG32 = _POINTER;
type PULONG64 = _POINTER;
type PUSHORT = _POINTER;
type PWCHAR = _POINTER;
type PWORD = _POINTER;
type PWSTR = _POINTER;
type QWORD = BigIntStr;
type SC_HANDLE = HANDLE;
type SC_LOCK = LPVOID;
type SERVICE_STATUS_HANDLE = HANDLE;
type SHORT = number;
type SIZE_T = number;
type SSIZE_T = number;
type TBYTE = number;
type TCHAR = string;
type UCHAR = string;
type UHALF_PTR = number;
type UINT = number;
type UINT_PTR = number | BigIntStr;
type UINT8 = number;
type UINT16 = number;
type UINT32 = number;
type UINT64 = BigIntStr;
type ULONG = number;
type ULONGLONG = BigIntStr;
type ULONG32 = number;
type ULONG64 = BigIntStr;
type USHORT = number;
type USN = LONGLONG;
type WINEVENTPROC = WNDPROC;
type WNDENUMPROC = WNDPROC;
type WORD = INT16;
type WPARAM = UINT_PTR;
type va_list = _POINTER;
/**
 * Convert Struct property to WCHAR_String if Buffer
 */
type StructPropToWCHAR<T> = {
    [P in keyof T]: T[P] extends Buffer ? WCHAR_String : T[P];
};
/**
 * Convert Struct property to Buffer if WCHAR_String
 */
type StructPropToBuffer<T> = {
    [P in keyof T]: T[P] extends WCHAR_String ? Buffer : T[P];
};
/**
 * Generate a fixed-length array of int16_t,
 * via genFixedInt16Array()
 */
interface WCHAR_Array {
    buffer: object;
    byteLength: number;
    byteOffset: number;
    length: number;
}
/**
 * For 'str16' and 'str' from https://koffi.dev/input
 */
type WString = string;
type String = string;

/**
 * PRINTER_INFO_1 structure,
 * Specifies general printer information
 * @link https://learn.microsoft.com/en-us/windows/win32/printdocs/PRINTER-INFO-1
 */
interface PRINTER_INFO_1_Type {
    Flags: T.DWORD;
    pDescription: T.WString;
    pName: T.WString;
    pComment: T.WString;
}

/**
 * PRINTER_INFO_4 structure,
 * Specifies general printer information
 * @link https://learn.microsoft.com/en-us/windows/win32/printdocs/PRINTER-INFO-4
 * @description The structure can be used to retrieve minimal printer information on a call to EnumPrinters.
 *  Such a call is a fast and easy way to retrieve the names and attributes of all locally installed printers
 *  on a system and all remote printer connections that a user has established.
 */
interface PRINTER_INFO_4_Type {
    pPrinterName: T.WString;
    pServerName: T.WString | null;
    Attributes: T.DWORD;
}

/**
 * PRINTER_INFO_5 structure,
 * structure specifies detailed printer information.
 * @link https://learn.microsoft.com/en-us/windows/win32/printdocs/PRINTER-INFO-5
 */
interface PRINTER_INFO_5_Type {
    pPrinterName: T.WString;
    pPortName: T.WString;
    Attributes: T.DWORD;
    DeviceNotSelectedTimeout: T.DWORD;
    TransmissionRetryTimeout: T.DWORD;
}

/**
 * PRINTER_INFO_6 structure,
 * structure specifies detailed printer information.
 * @link https://learn.microsoft.com/en-us/windows/win32/printdocs/PRINTER-INFO-6
 */
interface PRINTER_INFO_6_Type {
    dwStatus: PRINTER_STATUS;
}

/**
 * POINT structure
 * @link https://learn.microsoft.com/en-us/windows/win32/api/windef/ns-windef-point
 */
interface POINT_Type {
    x: T.LONG;
    y: T.LONG;
}

/**
 * DEVMODEW structure
 * @link https://learn.microsoft.com/en-us/windows/win32/api/wingdi/ns-wingdi-devmodew
 */
interface DEVMODEW_Type {
    dmDeviceName: T.WCHAR;
    dmSpecVersion: T.WORD;
    dmDriverVersion: T.WORD;
    dmSize: T.WORD;
    dmDriverExtra: T.WORD;
    dmFields: T.DWORD;
    u1: {
        s1: {
            dmOrientation: T.SHORT;
            dmPaperSize: T.SHORT;
            dmPaperLength: T.SHORT;
            dmPaperWidth: T.SHORT;
            dmScale: T.SHORT;
            dmCopies: T.SHORT;
            dmDefaultSource: T.SHORT;
            dmPrintQuality: T.SHORT;
        };
        dmPosition: POINT_Type;
        s2: {
            dmPosition: POINT_Type;
            dmDisplayOrientation: T.DWORD;
            dmDisplayFixedOutput: T.DWORD;
        };
    };
    dmColor: T.SHORT;
    dmDuplex: T.SHORT;
    dmYResolution: T.SHORT;
    dmTTOption: T.SHORT;
    dmCollate: T.SHORT;
    dmFormName: T.WCHAR;
    dmLogPixels: T.WORD;
    dmBitsPerPel: T.DWORD;
    dmPelsWidth: T.DWORD;
    dmPelsHeight: T.DWORD;
    u2: {
        dmDisplayFlags: T.DWORD;
        dmNup: T.DWORD;
    };
    dmDisplayFrequency: T.DWORD;
    dmICMMethod: T.DWORD;
    dmICMIntent: T.DWORD;
    dmMediaType: T.DWORD;
    dmDitherType: T.DWORD;
    dmReserved1: T.DWORD;
    dmReserved2: T.DWORD;
    dmPanningWidth: T.DWORD;
    dmPanningHeight: T.DWORD;
}

/**
 * PRINTER_INFO_8 structure,
 * specifies the global default printer settings.
 * @link https://learn.microsoft.com/en-us/windows/win32/printdocs/PRINTER-INFO-8
 */
interface PRINTER_INFO_8_Type {
    pDevMode: DEVMODEW_Type;
}

/**
 * PRINTER_INFO_9 structure,
 * structure specifies the per-user default printer settings.
 * @link https://learn.microsoft.com/en-us/windows/win32/printdocs/PRINTER-INFO-9
 */
interface PRINTER_INFO_9_Type {
    pDevMode: DEVMODEW_Type;
}

/**
 * For GetPrinter()
 * @link https://learn.microsoft.com/en-us/windows/win32/printdocs/getprinter#parameters
 * @todo 2, 3, 6, 7
 */
type PRINTER_INFO_LEVEL = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9;
/**
 * For GetPrinter()
 * @link https://learn.microsoft.com/en-us/windows/win32/printdocs/getprinter#parameters
 * @todo 2, 3, 6, 7
 */
type PRINTER_INFO_Type = PRINTER_INFO_1_Type | PRINTER_INFO_4_Type | PRINTER_INFO_5_Type | PRINTER_INFO_8_Type | PRINTER_INFO_9_Type;
/**
 * For GetPrinter()
 * @link https://learn.microsoft.com/en-us/windows/win32/printdocs/getprinter#parameters
 * @todo 2, 3, 7
 */
type PRINTER_INFO_X_Type<X extends PRINTER_INFO_LEVEL = PRINTER_INFO_LEVEL> = X extends 1 ? PRINTER_INFO_1_Type : X extends 4 ? PRINTER_INFO_4_Type : X extends 5 ? PRINTER_INFO_5_Type : X extends 6 ? PRINTER_INFO_6_Type : X extends 8 ? PRINTER_INFO_8_Type : X extends 9 ? PRINTER_INFO_9_Type : never;
/**
 * For EnumPrinters()
 * @link https://learn.microsoft.com/zh-cn/windows/win32/printdocs/enumprinters
 * @todo 2
 */
type EnumPrinters_Level = 1 | 4 | 5;
/**
 * For EnumPrinters()
 * @link https://learn.microsoft.com/zh-cn/windows/win32/printdocs/enumprinters
 * @todo 2
 */
type EnumPrinters_Level_Type = PRINTER_INFO_1_Type | PRINTER_INFO_4_Type | PRINTER_INFO_5_Type;
/**
 * For EnumPrinters()
 * @link https://learn.microsoft.com/zh-cn/windows/win32/printdocs/enumprinters
 * @todo 2
 */
type EnumPrinters_Level_X_Type<X extends EnumPrinters_Level = EnumPrinters_Level> = X extends 1 ? PRINTER_INFO_1_Type : X extends 4 ? PRINTER_INFO_4_Type : X extends 5 ? PRINTER_INFO_5_Type : never;

export { type ACCESS_MASK, type ATOM, type BOOL, type BOOLEAN, type BYTE, type CALLBACK, type CCHAR, type CHAR, type COLORREF, CallingConvention, type DLGPROC, type DWORD, type DWORD32, type DWORD64, type DWORDLONG, type DWORD_PTR, type DllFuncsType, type EnumPrinters_Level, type EnumPrinters_Level_Type, type EnumPrinters_Level_X_Type, type FLOAT, type FLib, type FLibExtMethods, type FnDefArgs, type FnDefCallParam, type FnDefCallParams, type FnDefFullParams, type FnDefListMap, type FnDefMultipleChoiceParam, type FnDefName, type FnDefParam, type FnDefRetType, type FuncDefList, type FuncDefListInner, type HACCEL, type HALF_PTR, type HANDLE, type HANDLE_PVOID, type HBITMAP, type HBRUSH, type HCOLORSPACE, type HCONV, type HCONVLIST, type HCURSOR, type HDC, type HDDEDATA, type HDESK, type HDROP, type HDWP, type HENHMETAFILE, type HFILE, type HFONT, type HGDIOBJ, type HGLOBAL, type HHOOK, type HICON, type HINSTANCE, type HKEY, type HKL, type HLOCAL, type HMENU, type HMETAFILE, type HMODULE, type HMONITOR, type HPALETTE, type HPEN, type HRESULT, type HRGN, type HRSRC, type HSZ, type HWINEVENTHOOK, type HWINSTA, type HWND, type INT, type INT16, type INT32, type INT64, type INT8, type INT_PTR, type LANGID, type LCID, type LCTYPE, type LGRPID, type LONG, type LONG32, type LONG64, type LONGLONG, type LONG_PTR, type LPARAM, type LPBOOL, type LPBYTE, type LPCOLORREF, type LPCSTR, type LPCTSTR, type LPCVOID, type LPCWSTR, type LPDWORD, type LPHANDLE, type LPINT, type LPLONG, type LPSTR, type LPTSTR, type LPVOID, type LPWORD, type LPWSTR, type LRESULT, type LibDef2Type, type LibDefBase, type LoadOptions, type MultipleChoiceMapper, type MultipleChoiceMapperList, type MultipleChoiceMapperSet, type NTSTATUS, type PBOOL, type PBOOLEAN, type PBYTE, type PCHAR, type PCSTR, type PCTSTR, type PCWSTR, type PDWORD, type PDWORD32, type PDWORD64, type PDWORDLONG, type PDWORD_PTR, type PFLOAT, type PHALF_PTR, type PHANDLE, type PHKEY, type PID, type PINT, type PINT16, type PINT32, type PINT64, type PINT8, type PINT_PTR, type PLCID, type PLONG, type PLONG32, type PLONG64, type PLONGLONG, type PLONG_PTR, type POINTER_32, type POINTER_64, type POINTER_SIGNED, type POINTER_UNSIGNED, type PPID, type PRINTER_INFO_LEVEL, type PRINTER_INFO_Type, type PRINTER_INFO_X_Type, type PSHORT, type PSIZE_T, type PSSIZE_T, type PSTR, type PTBYTE, type PTCHAR, type PTR_Addr, type PTSTR, type PUCHAR, type PUHALF_PTR, type PUINT, type PUINT16, type PUINT32, type PUINT64, type PUINT8, type PUINT_PTR, type PULONG, type PULONG32, type PULONG64, type PULONGLONG, type PULONG_PTR, type PUSHORT, type PVOID, type PWCHAR, type PWCHAR_String, type PWORD, type PWSTR, type QWORD, type SC_HANDLE, type SC_LOCK, type SERVICE_STATUS_HANDLE, type SHORT, type SIZE_T, type SSIZE_T, type String, type StructDetail, type StructFactory, type StructFactoryResult, type StructInitPlainType, type StructInitType, type StructPropToBuffer, type StructPropToWCHAR, type StructTypeConstructor, type TBYTE, type TCHAR, type UCHAR, type UHALF_PTR, type UINT, type UINT16, type UINT32, type UINT64, type UINT8, type UINT_PTR, type ULONG, type ULONG32, type ULONG64, type ULONGLONG, type ULONG_PTR, type USHORT, type USN, type UpdateMultipleChoiceMapperOptions, type VOID, type WCHAR, type WCHAR_Array, type WCHAR_String, type WINEVENTPROC, type WNDENUMPROC, type WNDPROC, type WORD, type WPARAM, type WString, type _MultipleChoiceMapper, type _POINTER, type _UNICODE, type _WIN64, type va_list };