win32-api

The repository is organized into two main packages:

1. win32-api: The primary package containing FFI definitions and utility wrappers for calling Windows native functions from user32.dll, kernel32.dll, and comctl32.dll via [koffi].
2. win32-def: Provides the underlying definitions used by the API.

When defining a library's method definitions, you can use string templates to reference structures or unions (e.g., S.LPPOINT for POINT*). If these structures are referenced in the method definition, they will be automatically created when the library is loaded via load().

import * as D from '##/index.def.js'
import * as S from '##/index.struct.js'
import * as T from '##/index.types.js' 

class DefWin {
  // S.LPPOINT == 'POINT*'
  static ClientToScreen = [D.BOOL, [D.HWND, `_Inout_ ${S.LPPOINT}`]] 
  // S.LPDISPLAY_DEVICEW == 'DISPLAY_DEVICEW*'
  static EnumDisplayDevicesW = [D.BOOL, [D.LPCWSTR, D.DWORD, `_Inout_ ${S.LPDISPLAY_DEVICEW}`, D.DWORD]] 
  static GetCursorPos = [D.BOOL, [`_Out_ ${S.LPPOINT}`]]
}

The project provides high-level wrappers for common Windows DLLs, such as User32 and Winspool, located in the win32-api/util entry point. These wrappers allow you to call native Windows functions directly in Node.js without manually managing FFI logic for every call.

Commonly used wrappers include:

• User32 (e.g., for window management)
• Winspool (e.g., for printer operations)

import { 
  FindWindowEx, 
  GetDefaultPrinter,
} from 'win32-api/util'
import { spawn } from 'child_process'; 

// Retrieves the printer name of the default printer for the current user on the local computer
const printerName = await GetDefaultPrinter()

const child = spawn('notepad.exe')
// Finds the window handle for Notepad
const hWnd = await FindWindowEx(0, 0, 'Notepad', null)

v13 introduces a promised version of the Win32 APIs. Instead of using the standard callback or synchronous patterns, you can import the API namespaces directly from win32-api/promise to use them with async/await.

import { Comctl32 } from 'win32-api/promise';
import { Kernel32 } from 'win32-api/promise';
import { Ntdll } from 'win32-api/promise';
import { User32 } from 'win32-api/promise';

To use the Windows win32 API FFI definitions in your Node.js project, install the win32-api package using npm.

npm install win32-api

To provide type safety when working with Win32 DLLs, you can define a DllFuncsType interface. This interface maps function names to their expected signatures. This pattern is used to bridge the gap between raw FFI calls and TypeScript's type system.

When defining these interfaces, ensure you are mapping the function name to its return type and parameter types as expected by the Win32 API.

import * as T from 'win32-def';

export interface MyDllFunctions extends T.DllFuncsType {
  // Example: FunctionName(param: Type): ReturnType
  SomeWin32Function(param: T.UINT): T.BOOL;
  AnotherFunction(): T.INT;
}

The KoffiFunctionLike interface describes the shape of a function generated by the library. It is not just a standard function; it includes metadata about its definition and supports both synchronous and asynchronous execution.

It provides:

• A standard callable signature: (...args: any[]): any
• An async property: async: (...args: any[]) => any
• An info object containing metadata:
  • name: The function name.
  • fnDefRetType: The return type definition.
  • fnDefCallParams: The parameter call definitions.

// Example of how a KoffiFunctionLike object might be accessed
const myFunc: KoffiFunctionLike = getFunctionFromLib();

// Synchronous call
myFunc(arg1, arg2);

// Asynchronous call
await myFunc.async(arg1, arg2);

// Accessing metadata
console.log(myFunc.info.name);

When working with complex Win32 structures, StructFactory is used to generate new instances of a struct.

A StructFactory is a function that returns a StructFactoryResult. The StructFactoryResult contains:

• payload: The actual struct data (used for _Out_ or _Inout_ parameters).
• name: The name of the struct.
• pointer: The pointer string representation.
• CType: The underlying koffi C type.
• size: The size of the struct in bytes.
• sizeColumns: Optional property keys representing the columns/fields.