quickwin 2.1.1 → 2.3.0

package/lib/windows/kernel32.js

@@ -101,6 +101,38 @@ export const TerminateProcess = /*@__PURE__*/ b('TerminateProcess', '<HPROCESS>p
 /** 取当前进程 PID（互证锚点）
  *  @returns 当前进程 PID */
 export const GetCurrentProcessId = /*@__PURE__*/ b('GetCurrentProcessId', ' -> u32');
+/** 当前进程伪句柄（-1，不需 CloseHandle——OpenProcess 真句柄的零成本替代，纯本进程
+ *  场景如 IsWow64Process 探位宽用） */
+export const GetCurrentProcess = /*@__PURE__*/ b('GetCurrentProcess', ' -> <HPROCESS>ptr');
+// ============ 远程内存（跨进程 SendMessage 的输出缓冲）============
+// 普通跨进程 SendMessage **不 marshal 指针**：出参 buffer 写在接收方线程执行，指针值
+// 原样透传——落在本进程地址空间会被 explorer 直接写穿。正解 = VirtualAllocEx 在目标
+// 进程分配 → 发消息 → ReadProcessMemory 读回（见 examples/execd/tray.ts /tray_list 用例）。
+/** 在目标进程地址空间分配内存；配对 VirtualFreeEx
+ *  @returns 成功 → 远程基址，失败 → 0（0 保真）
+ *  @param args_0 hProcess OpenProcess 句柄（本场景须 PROCESS_VM_OPERATION(0x8) |
+ *                PROCESS_VM_READ(0x10) | PROCESS_VM_WRITE(0x20) = 0x38）
+ *  @param args_1 lpAddress NULL = 系统选起点
+ *  @param args_2 dwSize 字节数（SIZE_T 随位宽 = <>ptr 的 ptr 宽，非指针语义）
+ *  @param args_3 flAllocationType MEM_COMMIT|MEM_RESERVE（0x1000|0x2000 = 0x3000）
+ *  @param args_4 flProtect PAGE_READWRITE（0x04） */
+export const VirtualAllocEx = /*@__PURE__*/ b('VirtualAllocEx', '<HPROCESS>ptr <>ptr <>ptr u32 u32 -> <>ptr');
+/** 释放 VirtualAllocEx 内存（须同一进程句柄）
+ *  @returns 成功 → 非 0
+ *  @param args_0 hProcess 同 VirtualAllocEx
+ *  @param args_1 lpAddress VirtualAllocEx 返回的远程基址
+ *  @param args_2 dwSize 0（MEM_RELEASE 时必须 0）
+ *  @param args_3 dwFreeType MEM_RELEASE（0x8000） */
+export const VirtualFreeEx = /*@__PURE__*/ b('VirtualFreeEx', '<HPROCESS>ptr <>ptr <>ptr u32 -> i32');
+/** 读目标进程内存（远程 SendMessage 写完 → 本调用读回本地；远程指针字段如托盘
+ *  dwData 内容的二次解引用同样走这里）
+ *  @returns 成功 → 非 0（目标地址不可读/句柄无 PROCESS_VM_READ）
+ *  @param args_0 hProcess OpenProcess 句柄（须 PROCESS_VM_READ(0x10)）
+ *  @param args_1 lpBaseAddress 远程地址（VirtualAllocEx 返回值等）
+ *  @param args_2 lpBuffer 本地接收缓冲，传 BYTE.alloc(n)（DataView/TypedArray 原地读回）
+ *  @param args_3 nSize 字节数（SIZE_T → <>ptr ptr 宽）
+ *  @param args_4 lpNumberOfBytesRead 实读字节数出参槽 PtrArrayBuffer(8) 可选，或 NULL */
+export const ReadProcessMemory = /*@__PURE__*/ b('ReadProcessMemory', '<HPROCESS>ptr <>ptr <BYTE>ptr <>ptr <>ptr -> i32');
 // ============ 文件 I/O ============
 /** 同步读文件 / 管道
  *  @returns 成功 → 非 0，管道写端全部关闭后读返回 0（EOF）
@@ -118,7 +150,7 @@ export const ReadFile = /*@__PURE__*/ b('ReadFile', '<HFILE>ptr! <BYTE>ptr u32 <
  *                组合（flags 位不标枚举）
  *  @param args_2 dwShareMode 共享掩码：FILE_SHARE_READ(0x1)|FILE_SHARE_WRITE(0x2)，独占传 0
  *  @param args_3 lpSecurityAttributes 安全属性，传 NULL
- *  @param args_4 dwCreationDisposition 创建处置 gui.FileCreation.*（互斥单选）
+ *  @param args_4 dwCreationDisposition 创建处置 FileCreation.*（互斥单选）
  *  @param args_5 dwFlagsAndAttributes 属性：FILE_ATTRIBUTE_NORMAL(0x80) 等（可组合不标）
  *  @param args_6 hTemplateFile 模板文件句柄，传 NULL */
 export const CreateFile = /*@__PURE__*/ b('CreateFileW', '<WCHAR>ptr! u32 u32 <>ptr u32@FileCreation u32 <>ptr -> <HFILE>ptr!');
@@ -157,7 +189,7 @@ export const MoveFileEx = /*@__PURE__*/ b('MoveFileExW', '<WCHAR>ptr! <WCHAR>ptr
  *  与合法的 0xFFFFFFFF 偏移）
  *  @param args_1 lDistanceToMove 偏移（LONG，可负）
  *  @param args_2 lpDistanceToMoveHigh 64 位偏移高半（出参双向），32 位够用传 NULL
- *  @param args_3 dwMoveMethod 起点 gui.FileSeekFrom.BEGIN / CURRENT / END */
+ *  @param args_3 dwMoveMethod 起点 FileSeekFrom.BEGIN / CURRENT / END */
 export const SetFilePointer = /*@__PURE__*/ b('SetFilePointer', '<HFILE>ptr! i32 <BYTE>ptr u32@FileSeekFrom -> u32');
 /** 读文件大小
  *  @returns 文件大小（低 32 位）；0xFFFFFFFF = 失败（INVALID_FILE_SIZE，须 GetLastError 区分）
@@ -238,6 +270,13 @@ export const GetModuleFileName = /*@__PURE__*/ b('GetModuleFileNameW', '<HMODULE
  *  @returns 命令行整串（返回位 `<WCHAR>ptr!`：内建 WCHAR codec 自动解码为 string，
  *    `!` 担保非 NULL 由返回位 0 检查兜底，无需接收缓冲） */
 export const GetCommandLineW = /*@__PURE__*/ b('GetCommandLineW', ' -> <WCHAR>ptr!');
+/** 本进程是否跑在 WOW64（32 位进程 on 64 位 OS）——判**远程进程/系统位宽**的廉价
+ *  探针：x64 进程恒 0（本就是 64 位 OS）；x86 进程 1 = OS 64 位（远程序构按 64 位解析，
+ *  如 x86 qwin 读 explorer 的 TBBUTTON）。32 位 OS 上恒写 0
+ *  @returns 成功 → 非 0
+ *  @param args_0 hProcess GetCurrentProcess() 伪句柄或真句柄
+ *  @param args_1 lpWow64Process 出参 BOOL 槽，PtrArrayBuffer(4)，Uint32Array 读回 */
+export const IsWow64Process = /*@__PURE__*/ b('IsWow64Process', '<HPROCESS>ptr <BYTE>ptr -> i32');
 // ============ 全局内存（剪贴板数据载体）============
 /** 分配全局内存块
  *  @returns 成功 → 句柄（0 失败）

package/lib/windows/kernel32.ts

@@ -117,6 +117,42 @@ export const TerminateProcess = /*@__PURE__*/ b('TerminateProcess', '<HPROCESS>p
 /** 取当前进程 PID（互证锚点）
  *  @returns 当前进程 PID */
 export const GetCurrentProcessId = /*@__PURE__*/ b('GetCurrentProcessId', ' -> u32')
+/** 当前进程伪句柄（-1，不需 CloseHandle——OpenProcess 真句柄的零成本替代，纯本进程
+ *  场景如 IsWow64Process 探位宽用） */
+export const GetCurrentProcess = /*@__PURE__*/ b('GetCurrentProcess', ' -> <HPROCESS>ptr')
+
+// ============ 远程内存（跨进程 SendMessage 的输出缓冲）============
+// 普通跨进程 SendMessage **不 marshal 指针**：出参 buffer 写在接收方线程执行，指针值
+// 原样透传——落在本进程地址空间会被 explorer 直接写穿。正解 = VirtualAllocEx 在目标
+// 进程分配 → 发消息 → ReadProcessMemory 读回（见 examples/execd/tray.ts /tray_list 用例）。
+
+/** 在目标进程地址空间分配内存；配对 VirtualFreeEx
+ *  @returns 成功 → 远程基址，失败 → 0（0 保真）
+ *  @param args_0 hProcess OpenProcess 句柄（本场景须 PROCESS_VM_OPERATION(0x8) |
+ *                PROCESS_VM_READ(0x10) | PROCESS_VM_WRITE(0x20) = 0x38）
+ *  @param args_1 lpAddress NULL = 系统选起点
+ *  @param args_2 dwSize 字节数（SIZE_T 随位宽 = <>ptr 的 ptr 宽，非指针语义）
+ *  @param args_3 flAllocationType MEM_COMMIT|MEM_RESERVE（0x1000|0x2000 = 0x3000）
+ *  @param args_4 flProtect PAGE_READWRITE（0x04） */
+export const VirtualAllocEx = /*@__PURE__*/ b('VirtualAllocEx',
+    '<HPROCESS>ptr <>ptr <>ptr u32 u32 -> <>ptr')
+/** 释放 VirtualAllocEx 内存（须同一进程句柄）
+ *  @returns 成功 → 非 0
+ *  @param args_0 hProcess 同 VirtualAllocEx
+ *  @param args_1 lpAddress VirtualAllocEx 返回的远程基址
+ *  @param args_2 dwSize 0（MEM_RELEASE 时必须 0）
+ *  @param args_3 dwFreeType MEM_RELEASE（0x8000） */
+export const VirtualFreeEx = /*@__PURE__*/ b('VirtualFreeEx', '<HPROCESS>ptr <>ptr <>ptr u32 -> i32')
+/** 读目标进程内存（远程 SendMessage 写完 → 本调用读回本地；远程指针字段如托盘
+ *  dwData 内容的二次解引用同样走这里）
+ *  @returns 成功 → 非 0（目标地址不可读/句柄无 PROCESS_VM_READ）
+ *  @param args_0 hProcess OpenProcess 句柄（须 PROCESS_VM_READ(0x10)）
+ *  @param args_1 lpBaseAddress 远程地址（VirtualAllocEx 返回值等）
+ *  @param args_2 lpBuffer 本地接收缓冲，传 BYTE.alloc(n)（DataView/TypedArray 原地读回）
+ *  @param args_3 nSize 字节数（SIZE_T → <>ptr ptr 宽）
+ *  @param args_4 lpNumberOfBytesRead 实读字节数出参槽 PtrArrayBuffer(8) 可选，或 NULL */
+export const ReadProcessMemory = /*@__PURE__*/ b('ReadProcessMemory',
+    '<HPROCESS>ptr <>ptr <BYTE>ptr <>ptr <>ptr -> i32')
 
 // ============ 文件 I/O ============
 
@@ -137,7 +173,7 @@ export const ReadFile = /*@__PURE__*/ b('ReadFile', '<HFILE>ptr! <BYTE>ptr u32 <
  *                组合（flags 位不标枚举）
  *  @param args_2 dwShareMode 共享掩码：FILE_SHARE_READ(0x1)|FILE_SHARE_WRITE(0x2)，独占传 0
  *  @param args_3 lpSecurityAttributes 安全属性，传 NULL
- *  @param args_4 dwCreationDisposition 创建处置 gui.FileCreation.*（互斥单选）
+ *  @param args_4 dwCreationDisposition 创建处置 FileCreation.*（互斥单选）
  *  @param args_5 dwFlagsAndAttributes 属性：FILE_ATTRIBUTE_NORMAL(0x80) 等（可组合不标）
  *  @param args_6 hTemplateFile 模板文件句柄，传 NULL */
 export const CreateFile = /*@__PURE__*/ b('CreateFileW',
@@ -177,7 +213,7 @@ export const MoveFileEx = /*@__PURE__*/ b('MoveFileExW', '<WCHAR>ptr! <WCHAR>ptr
  *  与合法的 0xFFFFFFFF 偏移）
  *  @param args_1 lDistanceToMove 偏移（LONG，可负）
  *  @param args_2 lpDistanceToMoveHigh 64 位偏移高半（出参双向），32 位够用传 NULL
- *  @param args_3 dwMoveMethod 起点 gui.FileSeekFrom.BEGIN / CURRENT / END */
+ *  @param args_3 dwMoveMethod 起点 FileSeekFrom.BEGIN / CURRENT / END */
 export const SetFilePointer = /*@__PURE__*/ b('SetFilePointer', '<HFILE>ptr! i32 <BYTE>ptr u32@FileSeekFrom -> u32')
 /** 读文件大小
  *  @returns 文件大小（低 32 位）；0xFFFFFFFF = 失败（INVALID_FILE_SIZE，须 GetLastError 区分）
@@ -265,6 +301,13 @@ export const GetModuleFileName = /*@__PURE__*/ b('GetModuleFileNameW', '<HMODULE
  *  @returns 命令行整串（返回位 `<WCHAR>ptr!`：内建 WCHAR codec 自动解码为 string，
  *    `!` 担保非 NULL 由返回位 0 检查兜底，无需接收缓冲） */
 export const GetCommandLineW = /*@__PURE__*/ b('GetCommandLineW', ' -> <WCHAR>ptr!')
+/** 本进程是否跑在 WOW64（32 位进程 on 64 位 OS）——判**远程进程/系统位宽**的廉价
+ *  探针：x64 进程恒 0（本就是 64 位 OS）；x86 进程 1 = OS 64 位（远程序构按 64 位解析，
+ *  如 x86 qwin 读 explorer 的 TBBUTTON）。32 位 OS 上恒写 0
+ *  @returns 成功 → 非 0
+ *  @param args_0 hProcess GetCurrentProcess() 伪句柄或真句柄
+ *  @param args_1 lpWow64Process 出参 BOOL 槽，PtrArrayBuffer(4)，Uint32Array 读回 */
+export const IsWow64Process = /*@__PURE__*/ b('IsWow64Process', '<HPROCESS>ptr <BYTE>ptr -> i32')
 
 // ============ 全局内存（剪贴板数据载体）============
 

package/lib/windows/shell32.js

@@ -1,7 +1,9 @@
-// shell32 绑定（shell 对话框 / PIDL→路径）
+// shell32 绑定（shell 对话框 / PIDL→路径 / 托盘图标定位）
 import { bind } from '../ffi/bind.js';
-// dll 名部分应用（工厂转调保泛型 infer，见 lib/windows/user32.ts 头注释）
-const b = (name, sig) => bind('shell32.dll', name, sig);
+import { NOTIFYICONIDENTIFIER } from './structs.js';
+// dll 名部分应用（工厂转调保泛型 infer，见 lib/windows/user32.ts 头注释）；第三参透传
+// encoders（结构入参位注册，方向约定见 lib/windows/user32.ts 头注释）
+const b = (name, sig, encoders) => bind('shell32.dll', name, sig, encoders);
 /** 文件夹浏览对话框；PIDL 用 ole32.CoTaskMemFree 释放
  *  @returns PIDL，取消 → 0
  *  @param args_0 pbi BROWSEINFOW.encode(...).ptr（见 structs.ts） */
@@ -11,3 +13,22 @@ export const SHBrowseForFolder = /*@__PURE__*/ b('SHBrowseForFolderW', '<BROWSEI
  *  @param args_0 pidl SHBrowseForFolder 等返回的 PIDL
  *  @param args_1 pszPath 出参缓冲，WCHAR.alloc(260)（MAX_PATH=260）、WCHAR.decode 读回 */
 export const SHGetPathFromIDList = /*@__PURE__*/ b('SHGetPathFromIDListW', '<>ptr <BYTE>ptr -> u32');
+/** 取托盘通知图标的屏幕矩形（Shell_NotifyIconGetRect；**Win7+**——XP 无此导出，
+ *  故为**可选绑定**：老系统上本常量为 null（bind() 是模块顶层立即解析，缺符号 throw
+ *  会拖垮整个脚本启动），调用方必须判空）
+ *  @returns HRESULT，实测语义：0 = 图标在通知区内，iconLocation = 其容器（可见区 /
+ *    溢出面板）内位置——**溢出面板未展开时该 rect 不是屏幕可点位**；1 = 按文档为
+ *    不可见态（隐藏/溢出；本机未复现——实测 Win7 溢出图标亦返 0）；0x80004005 E_FAIL
+ *    = 图标不存在，或该图标未按 {hWnd,uID} 注册（系统 GUID 图标实测 not_found）
+ *  @param args_0 identifier NOTIFYICONIDENTIFIER 对象直传（encoder 已注册；cbSize 填
+ *    NOTIFYICONIDENTIFIER.size，guidItem 缺省 = GUID_NULL 走 hWnd+uID）
+ *  @param args_1 iconLocation 出参槽，RECT.alloc().ptr（出参位不注册，方向约定同
+ *    user32），RECT.decode 读回 */
+export const Shell_NotifyIconGetRect = (() => {
+    try {
+        return b('Shell_NotifyIconGetRect', '<NOTIFYICONIDENTIFIER>ptr <RECT>ptr -> i32', { NOTIFYICONIDENTIFIER });
+    }
+    catch {
+        return null; // XP 等老系统无此导出（可选 API）；探测走 examples/execd/tray.ts
+    }
+})();

package/lib/windows/shell32.ts

@@ -1,8 +1,11 @@
-// shell32 绑定（shell 对话框 / PIDL→路径）
-import { bind } from '../ffi/bind.js'
+// shell32 绑定（shell 对话框 / PIDL→路径 / 托盘图标定位）
+import { bind, type CodecMap } from '../ffi/bind.js'
+import { NOTIFYICONIDENTIFIER } from './structs.js'
 
-// dll 名部分应用（工厂转调保泛型 infer，见 lib/windows/user32.ts 头注释）
-const b = <const S extends string>(name: string, sig: S) => bind('shell32.dll', name, sig)
+// dll 名部分应用（工厂转调保泛型 infer，见 lib/windows/user32.ts 头注释）；第三参透传
+// encoders（结构入参位注册，方向约定见 lib/windows/user32.ts 头注释）
+const b = <const S extends string, const LE extends CodecMap = {}>(name: string, sig: S, encoders?: LE) =>
+    bind('shell32.dll', name, sig, encoders)
 
 /** 文件夹浏览对话框；PIDL 用 ole32.CoTaskMemFree 释放
  *  @returns PIDL，取消 → 0
@@ -14,3 +17,23 @@ export const SHBrowseForFolder = /*@__PURE__*/ b('SHBrowseForFolderW', '<BROWSEI
  *  @param args_0 pidl SHBrowseForFolder 等返回的 PIDL
  *  @param args_1 pszPath 出参缓冲，WCHAR.alloc(260)（MAX_PATH=260）、WCHAR.decode 读回 */
 export const SHGetPathFromIDList = /*@__PURE__*/ b('SHGetPathFromIDListW', '<>ptr <BYTE>ptr -> u32')
+
+/** 取托盘通知图标的屏幕矩形（Shell_NotifyIconGetRect；**Win7+**——XP 无此导出，
+ *  故为**可选绑定**：老系统上本常量为 null（bind() 是模块顶层立即解析，缺符号 throw
+ *  会拖垮整个脚本启动），调用方必须判空）
+ *  @returns HRESULT，实测语义：0 = 图标在通知区内，iconLocation = 其容器（可见区 /
+ *    溢出面板）内位置——**溢出面板未展开时该 rect 不是屏幕可点位**；1 = 按文档为
+ *    不可见态（隐藏/溢出；本机未复现——实测 Win7 溢出图标亦返 0）；0x80004005 E_FAIL
+ *    = 图标不存在，或该图标未按 {hWnd,uID} 注册（系统 GUID 图标实测 not_found）
+ *  @param args_0 identifier NOTIFYICONIDENTIFIER 对象直传（encoder 已注册；cbSize 填
+ *    NOTIFYICONIDENTIFIER.size，guidItem 缺省 = GUID_NULL 走 hWnd+uID）
+ *  @param args_1 iconLocation 出参槽，RECT.alloc().ptr（出参位不注册，方向约定同
+ *    user32），RECT.decode 读回 */
+export const Shell_NotifyIconGetRect = (() => {
+    try {
+        return b('Shell_NotifyIconGetRect',
+            '<NOTIFYICONIDENTIFIER>ptr <RECT>ptr -> i32', { NOTIFYICONIDENTIFIER })
+    } catch {
+        return null    // XP 等老系统无此导出（可选 API）；探测走 examples/execd/tray.ts
+    }
+})()