@nativescript/windows-napi 1.0.0-beta.22 → 1.0.0-beta.24

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/README.md CHANGED
@@ -42,6 +42,87 @@ The host executable's manifest must declare `<maxversiontested Id="10.0.18362.0"
42
42
  `electron.exe` does and `node.exe` doesn't, so `XamlWindow` throws in plain Node. XAML events run
43
43
  from the host's message loop, so a host with its own UI loop needs no `pumpMessages`.
44
44
 
45
+ ## Win32
46
+
47
+ `win32` calls exported functions of any DLL:
48
+
49
+ ```js
50
+ const { win32 } = require('@nativescript/windows-napi');
51
+
52
+ win32.call('user32.dll', 'MessageBeep', 'bool', { type: 'u32', value: 0 });
53
+
54
+ const { lstrlenW } = win32.bind('kernel32.dll'); // arguments typed from their JS values
55
+ lstrlenW('hello'); // 5
56
+
57
+ const user32 = win32.define('user32.dll', {
58
+ GetSystemMetrics: ['i32'], // argument types; returns the default (i32)
59
+ IsWindow: { args: ['pointer'], ret: 'bool' },
60
+ });
61
+ ```
62
+
63
+ - Types: `void`, `bool`, `i8`–`i64`, `u8`–`u64`, `f32`, `f64`, `pointer`, `wstr` (UTF-16 string),
64
+ `str` (UTF-8 string). 64-bit values beyond 2^53 come back as `BigInt`; arguments take numbers or
65
+ `BigInt`s.
66
+ - A `pointer` argument also takes an `ArrayBuffer`, a typed array or `DataView` (its memory, for
67
+ structs and out-parameters) or a pointer object. `null` is a null pointer, also for strings.
68
+ - `win32.import(dll)` installs every export of the DLL as a global function.
69
+
70
+ ### Callbacks and window messages
71
+
72
+ `win32.callback(retType, argTypes, fn)` returns `{ pointer, release() }`: a native function
73
+ pointer that calls `fn` synchronously, for APIs that take one (`EnumWindows`, a `WNDPROC`). Keep it
74
+ until native code no longer uses it, then `release()` it.
75
+
76
+ `win32.messageWindow(listener)` returns `{ hwnd, close() }`, a hidden window whose messages are
77
+ delivered to `listener(msg, wParam, lParam)`. Use it as the window of a tray icon (its callback
78
+ message), `RegisterHotKey` (`WM_HOTKEY`) or a popup menu (`WM_COMMAND`). It is a top-level window,
79
+ so it also receives broadcasts such as `TaskbarCreated`.
80
+
81
+ ```js
82
+ const shell32 = win32.define('shell32.dll', { Shell_NotifyIconW: { args: ['u32', 'pointer'], ret: 'bool' } });
83
+ const user32 = win32.define('user32.dll', {
84
+ LoadIconW: { args: ['pointer', 'pointer'], ret: 'pointer' },
85
+ RegisterHotKey: { args: ['pointer', 'i32', 'u32', 'u32'], ret: 'bool' },
86
+ });
87
+
88
+ const WM_TRAY = 0x8001; // WM_APP + 1
89
+ const WM_HOTKEY = 0x0312, WM_LBUTTONUP = 0x0202;
90
+
91
+ const window = win32.messageWindow((msg, wParam, lParam) => {
92
+ if (msg === WM_TRAY && lParam === WM_LBUTTONUP) console.log('tray icon clicked');
93
+ if (msg === WM_HOTKEY && wParam === 1) console.log('Ctrl+Alt+S');
94
+ });
95
+
96
+ // NOTIFYICONDATAW, 64-bit layout
97
+ const nid = new DataView(new ArrayBuffer(976));
98
+ nid.setUint32(0, 976, true); // cbSize
99
+ nid.setBigUint64(8, BigInt(window.hwnd), true); // hWnd
100
+ nid.setUint32(16, 1, true); // uID
101
+ nid.setUint32(20, 0x1 | 0x2 | 0x4, true); // NIF_MESSAGE | NIF_ICON | NIF_TIP
102
+ nid.setUint32(24, WM_TRAY, true); // uCallbackMessage
103
+ nid.setBigUint64(32, BigInt(user32.LoadIconW(null, 32512)), true); // hIcon: IDI_APPLICATION
104
+ [...'My app'].forEach((c, i) => nid.setUint16(40 + i * 2, c.charCodeAt(0), true)); // szTip
105
+ shell32.Shell_NotifyIconW(0, nid); // NIM_ADD
106
+
107
+ user32.RegisterHotKey(window.hwnd, 1, 0x2 | 0x1 | 0x4000, 0x53); // Ctrl+Alt+S, MOD_NOREPEAT
108
+ ```
109
+
110
+ Messages arrive while the thread pumps them: Electron's main process does; in plain Node call
111
+ `enableAutoPump()`. In the standalone runtimes an open message window keeps the event loop running.
112
+
113
+ ## Embedding outside Node
114
+
115
+ Any host that provides Node-API can load the addon: load the `.node` file as a DLL and call its
116
+ `napi_register_module_v1(env, exports)`. The addon takes its `napi_*` functions from the host
117
+ executable, as in Node. A host whose executable doesn't export them sets `NAPI_HOST_MODULES`
118
+ before loading the addon: the modules that do, separated by `;`, in priority order. Each function
119
+ comes from the first module that exports it.
120
+
121
+ React Native for Windows is one: `@nativescript/react-native` runs the addon in a Hermes runtime,
122
+ where `hermes.dll` has the engine half of Node-API (`js_native_api.h`) and the module itself
123
+ implements Node's half (`node_api.h`: threadsafe functions, cleanup hooks, buffers). It sets
124
+ `NAPI_HOST_MODULES=<its DLL>;<hermes.dll>`.
125
+
45
126
  ## Development
46
127
 
47
128
  ```sh
package/index.d.ts CHANGED
@@ -154,3 +154,5 @@ export declare function installInterop(): void
154
154
  * `dotnet-bridge/publish/DotNetBridge.dll` exists next to the app.
155
155
  */
156
156
  export declare function installDotnet(): void
157
+ /** Installs `NSWinRT.win32`. Idempotent. */
158
+ export declare function installWin32(): void
package/index.js CHANGED
@@ -310,7 +310,7 @@ if (!nativeBinding) {
310
310
  throw new Error(`Failed to load native binding`)
311
311
  }
312
312
 
313
- const { formatValue, tableFor, makeDelegate, invokeDelegate, releaseDelegate, callStaticMethod, callInstanceMethod, makeNativeProxy, ffiRoundtrip, pointerValue, makeExternal, bufferInfo, structPtr, writeReadPtr, outParamValue, setOutParam, structFieldBytes, boxTyped, pumpMessages, lastError, installGlobals, getNamespace, nsUuid, createWindow, attachCompositorToWindow, pollWindowEvents, getWindowSize, setWindowTitle, xamlHostCreate, xamlHostSetListener, xamlHostPlace, xamlHostShow, xamlHostHide, xamlHostIsVisible, xamlHostDestroy, foregroundWindow, activateWindow, enableWindow, windowProcessId, classIsSealed, registerWinmd, scanWinmdDir, arrayBufferFromBuffer, installInterop, installDotnet } = nativeBinding
313
+ const { formatValue, tableFor, makeDelegate, invokeDelegate, releaseDelegate, callStaticMethod, callInstanceMethod, makeNativeProxy, ffiRoundtrip, pointerValue, makeExternal, bufferInfo, structPtr, writeReadPtr, outParamValue, setOutParam, structFieldBytes, boxTyped, pumpMessages, lastError, installGlobals, getNamespace, nsUuid, createWindow, attachCompositorToWindow, pollWindowEvents, getWindowSize, setWindowTitle, xamlHostCreate, xamlHostSetListener, xamlHostPlace, xamlHostShow, xamlHostHide, xamlHostIsVisible, xamlHostDestroy, foregroundWindow, activateWindow, enableWindow, windowProcessId, classIsSealed, registerWinmd, scanWinmdDir, arrayBufferFromBuffer, installInterop, installDotnet, installWin32 } = nativeBinding
314
314
 
315
315
  module.exports.formatValue = formatValue
316
316
  module.exports.tableFor = tableFor
@@ -357,3 +357,4 @@ module.exports.scanWinmdDir = scanWinmdDir
357
357
  module.exports.arrayBufferFromBuffer = arrayBufferFromBuffer
358
358
  module.exports.installInterop = installInterop
359
359
  module.exports.installDotnet = installDotnet
360
+ module.exports.installWin32 = installWin32
package/nswinrt.js CHANGED
@@ -113,6 +113,9 @@ const interop = globalThis.NSWinRT.interop;
113
113
  native.installDotnet();
114
114
  const dotnet = globalThis.NSWinRT.dotnet;
115
115
 
116
+ native.installWin32();
117
+ const win32 = globalThis.NSWinRT.win32;
118
+
116
119
  // Windows.UI.Xaml content in a Win32 window (XAML Islands). Needs a thread that pumps messages.
117
120
  let xamlManager = null;
118
121
 
@@ -213,5 +216,6 @@ module.exports = {
213
216
  disableAutoPump,
214
217
  interop,
215
218
  dotnet,
219
+ win32,
216
220
  XamlWindow,
217
221
  };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@nativescript/windows-napi",
3
- "version": "1.0.0-beta.22",
3
+ "version": "1.0.0-beta.24",
4
4
  "description": "Node-API WinRT interop for Windows.",
5
5
  "main": "nswinrt.js",
6
6
  "types": "index.d.ts",
Binary file
Binary file