{"_id":"@bun-win32/wimgapi","_rev":"3-cb5b8a197fd2dfe1467d166d271e051e","name":"@bun-win32/wimgapi","dist-tags":{"latest":"2.0.1"},"versions":{"1.0.0":{"name":"@bun-win32/wimgapi","version":"1.0.0","keywords":["bun","ffi","win32","windows","wimgapi","bindings","typescript","dll"],"author":"Stev Peifer <stev@bell.net>","license":"MIT","_id":"@bun-win32/wimgapi@1.0.0","maintainers":[{"name":"obscuritysrl","email":"stev@bell.net"}],"homepage":"https://github.com/ObscuritySRL/bun-win32#readme","bugs":{"url":"https://github.com/ObscuritySRL/bun-win32/issues"},"dist":{"shasum":"11b98900bf2928041d70879f6f6a1d4f6de4b7e9","tarball":"https://registry.npmjs.org/@bun-win32/wimgapi/-/wimgapi-1.0.0.tgz","fileCount":6,"integrity":"sha512-ugqJdV60npfbgN9DAhifWFayDzZgDwZhHzAa/hWazP7HHTRQTGjjAjbA0kq5jM48Z/kOvyupuMnCUxW+/oxdrw==","signatures":[{"sig":"MEQCIBL9UCL7Cg3jBOW7PJ6lhDsIQ32BiqwlAlbpp1ntmRjnAiAa3//caXx2QcHp3Ef3a/FRB+mKDn2dLVOk2WgNwN2zJQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":27255},"main":"./index.ts","type":"module","module":"index.ts","shasum":"11b98900bf2928041d70879f6f6a1d4f6de4b7e9","engines":{"bun":">=1.1.0"},"exports":{".":"./index.ts"},"private":false,"scripts":{"example:wim-xray":"bun ./example/wim-xray.ts","example:wim-inspector":"bun ./example/wim-inspector.ts"},"_npmUser":{"name":"obscuritysrl","email":"stev@bell.net"},"_integrity":"sha512-ugqJdV60npfbgN9DAhifWFayDzZgDwZhHzAa/hWazP7HHTRQTGjjAjbA0kq5jM48Z/kOvyupuMnCUxW+/oxdrw==","repository":{"url":"git://github.com/ObscuritySRL/bun-win32.git","type":"git","directory":"packages/wimgapi"},"_npmVersion":"10.8.3","description":"Zero-dependency, zero-overhead Win32 WIMGAPI bindings for Bun (FFI) on Windows.","directories":{},"sideEffects":false,"_nodeVersion":"24.3.0","dependencies":{"@bun-win32/core":"1.1.2"},"_hasShrinkwrap":false,"devDependencies":{"@types/bun":"latest"},"peerDependencies":{"typescript":"^5"},"_npmOperationalInternal":{"tmp":"tmp/wimgapi_1.0.0_1780539760059_0.9871907099355459","host":"s3://npm-registry-packages-npm-production"}},"2.0.0":{"name":"@bun-win32/wimgapi","version":"2.0.0","keywords":["bun","ffi","win32","windows","wimgapi","bindings","typescript","dll"],"author":"Stev Peifer <stev.p@outlook.com>","license":"MIT","_id":"@bun-win32/wimgapi@2.0.0","maintainers":[{"name":"obscuritysrl","email":"stev.p@outlook.com"}],"homepage":"https://github.com/ObscuritySRL/bun-win32#readme","bugs":{"url":"https://github.com/ObscuritySRL/bun-win32/issues"},"dist":{"shasum":"a78503711a7e9a897600c3afaa653b6fb687b82e","tarball":"https://registry.npmjs.org/@bun-win32/wimgapi/-/wimgapi-2.0.0.tgz","fileCount":6,"integrity":"sha512-NP0iquWSqbwdwtt5oapXwgaUASTebK/rWOmhZVVJxgL6RwBOSBOAEKlllIR+ZkSKHzJGIHp7v8VcopyN290I9g==","signatures":[{"sig":"MEYCIQCxXaj/vttdAt6uNW8QOIpSM6g49rJ4PswVj6yDV2PkQAIhALVPWaEGuq8a+hRllCggOoRGYNmBna35IW5uGETAF5Hd","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":28723},"main":"./index.ts","type":"module","module":"index.ts","shasum":"a78503711a7e9a897600c3afaa653b6fb687b82e","engines":{"bun":">=1.1.0"},"exports":{".":"./index.ts"},"private":false,"scripts":{"example:wim-xray":"bun ./example/wim-xray.ts","example:wim-inspector":"bun ./example/wim-inspector.ts"},"_npmUser":{"name":"obscuritysrl","email":"stev.p@outlook.com"},"_integrity":"sha512-NP0iquWSqbwdwtt5oapXwgaUASTebK/rWOmhZVVJxgL6RwBOSBOAEKlllIR+ZkSKHzJGIHp7v8VcopyN290I9g==","repository":{"url":"git://github.com/ObscuritySRL/bun-win32.git","type":"git","directory":"packages/wimgapi"},"_npmVersion":"10.8.3","description":"Zero-dependency, zero-overhead Win32 WIMGAPI bindings for Bun (FFI) on Windows.","directories":{},"sideEffects":false,"_nodeVersion":"26.3.0","dependencies":{"@bun-win32/core":"2.0.0"},"_hasShrinkwrap":false,"devDependencies":{"@types/bun":"latest"},"peerDependencies":{"typescript":"^5"},"_npmOperationalInternal":{"tmp":"tmp/wimgapi_2.0.0_1782435987028_0.016178194032674176","host":"s3://npm-registry-packages-npm-production"}},"2.0.1":{"author":"Stev Peifer <stev.p@outlook.com>","bugs":{"url":"https://github.com/ObscuritySRL/bun-win32/issues"},"dependencies":{"@bun-win32/core":"2.0.1"},"description":"Zero-dependency, zero-overhead Win32 WIMGAPI bindings for Bun (FFI) on Windows.","devDependencies":{"@types/bun":"latest"},"exports":{".":"./index.ts"},"license":"MIT","module":"index.ts","name":"@bun-win32/wimgapi","peerDependencies":{"typescript":"^5"},"private":false,"homepage":"https://github.com/ObscuritySRL/bun-win32#readme","repository":{"type":"git","url":"git://github.com/ObscuritySRL/bun-win32.git","directory":"packages/wimgapi"},"type":"module","version":"2.0.1","main":"./index.ts","keywords":["bun","ffi","win32","windows","wimgapi","bindings","typescript","dll"],"sideEffects":false,"engines":{"bun":">=1.1.0"},"scripts":{"example:wim-inspector":"bun ./example/wim-inspector.ts","example:wim-xray":"bun ./example/wim-xray.ts"},"_id":"@bun-win32/wimgapi@2.0.1","_integrity":"sha512-W3/b/jod5M5oZmEQrh8pmo3DdI4WiZYewrUIsVmMK6BfS5hA7/rDAeVh95Lyuujm/1VfPSKyzh5nUlZS7g4K7A==","_nodeVersion":"26.3.0","_npmVersion":"10.8.3","shasum":"823bf3b620bad49d9e222f1e46ce0a4b035532a8","dist":{"integrity":"sha512-W3/b/jod5M5oZmEQrh8pmo3DdI4WiZYewrUIsVmMK6BfS5hA7/rDAeVh95Lyuujm/1VfPSKyzh5nUlZS7g4K7A==","shasum":"823bf3b620bad49d9e222f1e46ce0a4b035532a8","tarball":"https://registry.npmjs.org/@bun-win32/wimgapi/-/wimgapi-2.0.1.tgz","fileCount":6,"unpackedSize":28723,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCd2JgOebYCenBF4T5y64l7IsM6qRdj7XtogVt5sI6WSwIhALkWh0lq6hKdyI1ZkrmQnsP97qNFpBRGbz1Bu4G0GnMO"}]},"_npmUser":{"name":"obscuritysrl","email":"stev.p@outlook.com"},"directories":{},"maintainers":[{"name":"obscuritysrl","email":"stev.p@outlook.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/wimgapi_2.0.1_1782438213120_0.11991879097056146"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-04T02:22:39.951Z","modified":"2026-06-26T01:43:33.387Z","1.0.0":"2026-06-04T02:22:40.194Z","2.0.0":"2026-06-26T01:06:27.180Z","2.0.1":"2026-06-26T01:43:33.253Z"},"bugs":{"url":"https://github.com/ObscuritySRL/bun-win32/issues"},"author":"Stev Peifer <stev.p@outlook.com>","license":"MIT","homepage":"https://github.com/ObscuritySRL/bun-win32#readme","keywords":["bun","ffi","win32","windows","wimgapi","bindings","typescript","dll"],"repository":{"type":"git","url":"git://github.com/ObscuritySRL/bun-win32.git","directory":"packages/wimgapi"},"description":"Zero-dependency, zero-overhead Win32 WIMGAPI bindings for Bun (FFI) on Windows.","maintainers":[{"name":"obscuritysrl","email":"stev.p@outlook.com"}],"readme":"# @bun-win32/wimgapi\n\nZero-dependency, zero-overhead Win32 WIMGAPI bindings for [Bun](https://bun.sh) on Windows.\n\n## Overview\n\n`@bun-win32/wimgapi` exposes the `wimgapi.dll` exports using [Bun](https://bun.sh)'s FFI. It provides a single class, `Wimgapi`, which lazily binds native symbols on first use. You can optionally preload a subset or all symbols up-front via `Preload()`.\n\nThe Windows Imaging Interface (WIMGAPI) is the supported, in-process API for Windows image (`.wim`) files — create/open archives, capture a directory tree, apply or enumerate an image, mount/unmount, split, export, set references, and stream live progress through a message callback. It is the same engine `DISM.exe` and `ImageX` drive, with no process spawn. It complements [`@bun-win32/dismapi`](../dismapi) (image servicing).\n\nThe bindings are strongly typed for a smooth DX in TypeScript.\n\n## Features\n\n- [Bun](https://bun.sh)-first ergonomics on Windows 10/11.\n- Direct FFI to `wimgapi.dll` (image capture/apply/mount/split/export, message callbacks).\n- In-source docs in `structs/Wimgapi.ts` with links to Microsoft Docs.\n- Lazy binding on first call; optional eager preload (`Wimgapi.Preload()`).\n- No wrapper overhead; calls map 1:1 to native APIs.\n- Strongly-typed Win32 aliases and the full WIM flag/message enums (see `types/Wimgapi.ts`).\n\n## Requirements\n\n- [Bun](https://bun.sh) runtime\n- Windows 10 or later\n- An **elevated** process for capture/apply/mount (`WIMCaptureImage`/`WIMApplyImage`/`WIMMountImage` need `SeBackupPrivilege`/`SeRestorePrivilege`). Opening a `.wim` read-only and enumerating it (`WIMApplyImage` with `WIM_FLAG_NO_APPLY`) needs no privilege.\n\n## Installation\n\n```sh\nbun add @bun-win32/wimgapi\n```\n\n## Quick Start\n\n```ts\nimport Wimgapi, { WIMCreationDisposition, WIMDesiredAccess } from '@bun-win32/wimgapi';\n\nconst wide = (s: string) => Buffer.from(s + '\\0', 'utf16le');\n\n// Open an existing .wim read-only and read its header + image count.\nconst result = Buffer.alloc(4);\nconst hWim = Wimgapi.WIMCreateFile(wide('C:\\\\images\\\\install.wim').ptr!, WIMDesiredAccess.WIM_GENERIC_READ, WIMCreationDisposition.WIM_OPEN_EXISTING, 0, 0, result.ptr!);\n\nif (hWim !== 0n) {\n  console.log('images in archive:', Wimgapi.WIMGetImageCount(hWim));\n\n  const wimInfo = Buffer.alloc(560); // WIM_INFO\n  if (Wimgapi.WIMGetAttributes(hWim, wimInfo.ptr!, 560)) {\n    console.log('compression type:', wimInfo.readUInt32LE(540));\n  }\n\n  Wimgapi.WIMCloseHandle(hWim); // always pair create/open with close\n}\n```\n\n> [!NOTE]\n> AI agents: see `AI.md` for the package binding contract and source-navigation guidance. It explains how to use the package without scanning the entire implementation.\n\n## Examples\n\nRun the included examples (run elevated, or pass an existing `.wim` path, for full output):\n\n```sh\nbun run example/wim-inspector.ts [path\\to\\image.wim]\nbun run example/wim-xray.ts      [path\\to\\image.wim]\n```\n\n- **wim-inspector** — a thorough diagnostic: decoded `WIM_INFO` header (GUID, compression, parts, attributes), per-image XML manifest, and the live system-wide mounted-image table.\n- **wim-xray** — a live truecolor X-ray of an image's file tree, driven by the real imaging engine calling back into a `bun:ffi` JSCallback (registered via `WIMRegisterMessageCallback`, enumerated with `WIMApplyImage(hImage, NULL, WIM_FLAG_NO_APPLY)`).\n\n## Notes\n\n- Either rely on lazy binding or call `Wimgapi.Preload()`.\n- All WIM functions are wide-only (no `A`/`W` split); strings are UTF-16LE NUL-terminated buffers.\n- Handles (`WIMCreateFile`/`WIMLoadImage`/`WIMCaptureImage` returns) are `bigint`; failure is `0n`. Always release them with `WIMCloseHandle`.\n- `WIMGetImageInformation` returns a **WIM-allocated** UTF-16 buffer via a `PVOID*` out-pointer plus a `DWORD` byte count; read the count from your own buffer, then free the buffer with `Kernel32.LocalFree`.\n- Sizing pattern: `WIMGetMountedImages(NULL, &cb)` / `WIMGetMountedImageInfo(level, &count, NULL, 0, &cb)` return the required buffer size; allocate, then call again.\n- Register a `WIMMessageCallback` (a `bun:ffi` JSCallback passed as `FARPROC`) for live progress; return `WIM_MSG_SUCCESS` to continue or `WIM_MSG_ABORT_IMAGE` to cancel. Keep the JSCallback alive for the duration of the operation.\n- Seven exported file-IO/enumeration functions (`WIMReadImageFile`, `WIMCreateImageFile`, `WIMFindFirstImageFile`, `WIMFindNextImageFile`, `WIMEnumImageFiles`, `WIMInitFileIOCallbacks`, `WIMSetFileIOCallbackTemporaryPath`) and the `Dll*` server entries are undocumented internals and intentionally not bound.\n- Windows only. Bun runtime required.\n- **SAL types & naming:** nullability is in the **type** — `Optional<T>` (formally optional, SAL `_*opt_`) and `Nullable<T>` (plain `[in]`/`[out]` the docs say can be NULL), the null sentinel derived from `T` (`null` for pointers `LP*`/`P*`, `0n` for handles/by-value addresses); direction is in the **parameter name** — `_out` (`_Out_`), `_in_out` (`_Inout_`), `_In_` bare. See `AI.md` and the repo `AGENTS.md`.\n","readmeFilename":"README.md"}