libwin32 (work in progress)

Node bindings to native Win32 DLLs through Koffi.

import { MessageBox } from 'libwin32'
import { MB_ } from 'libwin32/consts'

const result = MessageBox(
    null,
    "Hello, world!",
    "libwin32",
    MB_.ICONINFORMATION | MB_.YESNO
)

In a nutshell:

• Very simple and intuitive API (see demos), with TypeScript definitions included.
• Bundler friendly, designed with tree-shakeability in mind.
• Opinionated:
  • Only targets 64-bit platforms (Intel/AMD for now, ARM may be added later, no warranty though).
  • Only exposes Unicode functions and data structures (those whose name ends in W in the Win32 API).
• Very easy to extend with additional functions, data structures and constants. I will add some myself time permitting; any help would be mucho appreciated. If you can't or won't submit a PR yourself, just head to #8 and kindly ask :).

How to...

> Use the lib in your code

1. Install the lib in your project: npm install libwin32
2. Import the functions and types you need. You may either import from libwin32 or from libwin32/<dllname> (without the .dll extension) if you know which dll a function belongs to. For example, import { MessageBox } from 'libwin32' and import { MessageBox } from 'libwin32/user32' would both work.
3. (optional) Import some complementary constants. They greatly simplify calls to the Win32 API.
   • All constants are available via the libwin32/consts import.
   • Logically grouped constants are exported as enums, where the prefix is the name of the enum. For instance, WM_DESTROY and WM_KEYDOWN are members of the WM_ enum and can be accessed as WM_.DESTROY and WM_.KEYDOWN, respectively.
4. Call the functions as instructed by the Win32 API documentation.
   • All functions, constants and types are named accordingly and the lib is fully typed so you may rely on code hints from your editor.
     • There are a few cases though where it made sense to adapt the C prototype to something more JS-friendly. For instance, in C, GetWindowText() fills in a buffer whose address is passed as the second parameter to the function; in JS/TS, the function takes only one parameter and returns a string.
   • Many Win32 C structures have a size member (often named cbSize) that must be set before they are used as a parameter. For these, the lib provide a JS class that automatically sets that field when instantiated. See WNDCLASSEX for an example.

> Bundle the lib with your code

The Win32 API has thousands of functions, structures and constants. While providing bindings for all of them is not a goal, the lib may eventually grow to something very, very big.

To accommodate this, libwin32 is "tree-shakeable by design": when bundled, only the functions, constants and structures you use end up in the bundle. This feature relies on Rollup's awesome tree-shaking capabilities.

See rollup.demos.js to see how it's done, and build the demos (see below) to see the resulting code in the /demos directory.

> Build the lib

$ git clone https://github.com/Septh/libwin32.git
$ cd libwin32
$ npm install
$ npm run build

The output goes to /lib.

> Run the demos

Build the lib, then:

• Without bundling:

$ node lib/demos/<demoname>.js

• With bundling:

$ npm run build:demos
$ node demos/<demoname>.js

Changelog

See releases on Github.

Bindings so far

All functions come with their associated types and constants.

Function name	Win32 DLL	Added in
AdjustWindowRect	user32	0.3.0
AdjustWindowRectEx	user32	0.3.0
AdjustWindowRectExForDpi	user32	0.7.0
AllocateAndInitializeSid	advapi32	0.7.0
AnimateWindow	user32	0.3.0
AppendMenu	user32	0.4.0
Beep	kernel32	0.6.0
BringWindowToTop	user32	0.3.0
BroadcastSystemMessage	user32	0.3.0
BroadcastSystemMessageEx	user32	0.3.0
CallWindowProc	user32	0.3.0
CheckMenuItem	user32	0.4.0
CloseHandle	kernel32	0.5.0
CreatePopupMenu	user32	0.4.0
CreateWindow	user32	0.1.0
CreateWindowEx	user32	0.1.0
DefWindowProc	user32	0.1.0
DestroyCursor	user32	0.1.0
DestroyIcon	user32	0.1.0
DestroyMenu	user32	0.4.0
DispatchMessage	user32	0.1.0
EnumWindows	user32	0.3.0
EqualSid	advapi32	0.7.0
FindWindow	user32	0.3.0
FindWindowEx	user32	0.3.0
FormatMessage	kernel32	0.5.0
FreeSid	advapi32	0.7.0
GetAncestor	user32	0.3.0
GetClassInfo	user32	0.3.0
GetClassInfoEx	user32	0.3.0
GetClassName	user32	0.3.0
GetComputerName	kernel32	0.6.0
GetCurrentProcess	kernel32	0.5.0
GetCursorPos	user32	0.4.0
GetDesktopWindow	user32	0.7.0
GetLastError	kernel32	0.1.0
GetMessage	user32	0.1.0
GetModuleFileName	kernel32	0.6.0
GetModuleHandle	kernel32	0.1.0
GetModuleHandleEx	kernel32	0.5.0
GetTokenInformation	advapi32	0.6.0
GetUserName	advapi32	0.6.0
GetUserNameEx	secur32	0.6.0
GetWindowText	user32	0.3.0
GetWindowThreadProcessId	kernel32	0.5.0
LoadCursor	user32	0.1.0
LoadIcon	user32	0.1.0
LoadImage	user32	0.1.0
LookupAccountSid	advapi32	0.6.0
LsaClose	advapi32	0.6.0
LsaNtStatusToWinError	advapi32	0.6.0
LsaOpenPolicy	advapi32	0.6.0
MessageBox	user32	0.1.0
MessageBoxEx	user32	0.7.0
OpenProcess	kernel32	0.5.0
OpenProcessToken	advapi32	0.6.0
PostQuitMessage	user32	0.1.0
QueryFullProcessImageName	kernel32	0.5.0
RegisterClass	user32	0.1.0
RegisterClassEx	user32	0.1.0
SendMessage	user32	0.4.0
SetForegroundWindow	user32	0.4.0
SetLastError	kernel32	0.5.0
Shell_NotifyIcon	shell32	0.4.0
ShowWindow	user32	0.1.0
ShowWindowAsync	user32	0.1.0
TrackPopupMenu	user32	0.4.0
TranslateMessageEx	user32	0.1.0
UnregisterClass	user32	0.1.0
UpdateWindow	user32	0.1.0

Many thanks to @MomoRazor for the impressive work on 53e99ef!

Many thanks to @shrirajh for the impressive work on b2bf65b!

Repository structure

• ./source/win32:
  • The main bindings source files.
• ./source/demos:
  • Some usage examples.
• ./source/rollup:
  • Rollup plugins to ease the process of bundling this library with your own code and to boost its tree-shakeability. See rollup.demos.js to see how to use.

Related

• koffi-cream, a lighter repackaging of Koffi.

Licence

MIT.