OpenLogi0x4521 · disableKeys
读取键盘固定禁用键掩码，并替换受支持锁定键和系统键的完整掩码。
DisableKeys 控制一组固定的锁定键和系统键。它读取受支持掩码和当前掩码，然后替换完整的当前掩码。
**规格：**Logitech HID++ 2.0——disableKeys。**交叉核对：**Logi Options+ 2.8（静态分析）、Solaar。用于：#1940 已添加设备枚举变化提示。#993 添加了代理、配置与 GUI 控件。
函数参考
DisableKeysFeature 可为功能版本 0 创建。
方法
| 函数 | HID++ fn | 签名 | 返回值 |
|---|---|---|---|
get_capabilities | 0 | () | DisableableKeys |
get_disabled_keys | 1 | () | DisableableKeys |
set_disabled_keys | 2 | (keys: DisableableKeys) | DisableableKeys |
每个方法都是 async 方法，并返回 Result<…, Hidpp20Error>。
类型
DisableableKeys
DisableableKeys 是保留未知位的 u8 位字段。OpenLogi 用它表示受支持按键和当前禁用按键。
| 字段 | 位 | 说明 |
|---|---|---|
CAPS_LOCK | 1 << 0 | Caps Lock。 |
NUM_LOCK | 1 << 1 | Num Lock。 |
SCROLL_LOCK | 1 << 2 | Scroll Lock。 |
INSERT | 1 << 3 | Insert。 |
WINDOWS | 1 << 4 | Windows 或 Start 键。 |
事件
OpenLogi 不为 0x4521 提供事件类型或 listen() 方法。
| 事件 | 载荷 | 说明 |
|---|---|---|
| 禁用键变化 | DisableableKeys | Logi Options+ 2.8 将字节 0 视为新掩码。Options+ 2.8 |
线格式
这三个函数使用 3 字节短请求。OpenLogi 将每个响应规范化为 16 字节，并只读取字节 0。
get_capabilities（fn 0）
请求：0x00, 0x00, 0x00。
| 字节 | 字段 | 说明 |
|---|---|---|
| 0 | keys | DisableableKeys 位图，表示软件可禁用的按键。 |
| 1–15 | — | OpenLogi 忽略这些字节。 |
get_disabled_keys（fn 1）
请求：0x00, 0x00, 0x00。
| 字节 | 字段 | 说明 |
|---|---|---|
| 0 | keys | 当前禁用键位图。 |
| 1–15 | — | OpenLogi 忽略这些字节。 |
set_disabled_keys（fn 2）
请求：
| 字节 | 字段 | 说明 |
|---|---|---|
| 0 | keys | 完整替换位图。0x00 会重新启用全部受支持按键。 |
| 1–2 | — | 填充。OpenLogi 发送 0x00。 |
响应：
| 字节 | 字段 | 说明 |
|---|---|---|
| 0 | keys | 设备回显，解析为 DisableableKeys。 |
| 1–15 | — | OpenLogi 忽略这些字节。 |
禁用键变化报告（fn 2）
Logi Options+ 2.8 会处理函数 2 的非空异步报告。它将字节 0 解释为新的禁用键位图。
| 字节 | 字段 | 说明 |
|---|---|---|
| 0 | keys | 新的 DisableableKeys 位图。Options+ 2.8 |
| 1–15 | — | 字节 0 之外的布局尚未确定。 |
OpenLogi 的用法
OpenLogi v0.8.15 只提供类型化封装。PR #1940 已订阅函数 2 的非请求报告。报告会递增 settings_revision，并请求权威枚举。OpenLogi 只把报告当作变化提示，不解析其掩码。
set_disabled_keys 是全量替换，不是单键补丁。调用者要更改一个键时，应先读取当前掩码，修改目标位，写入完整掩码，再检查返回掩码。
PR #993 让代理负责读写，并添加了能力门控的 GUI 卡片。设备写入器拒绝未知请求位和不受支持的已知位。写入器保留固件支持的未知禁用位。写入后，写入器重新读取并比较完整受支持掩码。
应用只保存已确认的已知按键。未确认写入会使显示快照失效，直到新读取成功。代理调度最近确认的策略，不抢占更新的请求。代理在发现、重连和唤醒后重新应用配置。确认重试有次数上限。用户行为见禁用按键配置。
未确认的细节
Logi Options+ 2.8 会处理函数 2 的异步报告。公开规格和硬件抓包没有确认完整报告布局。因此 OpenLogi 重新读取设置，不信任报告载荷。#993 在 10 月 23 日修改恢复逻辑后，没有重新在实机上验证。
Rust 用法
use hidpp::{
device::Device,
feature::disable_keys::{DisableKeysFeature, DisableableKeys},
};
// `device` is a discovered HID++ device.
device.enumerate_features().await?;
if let Some(feature) = device.get_feature::<DisableKeysFeature>() {
let current = feature.get_disabled_keys().await?;
let wanted = current | DisableableKeys::CAPS_LOCK;
let accepted = feature.set_disabled_keys(wanted).await?;
println!("accepted disabled-key mask: {accepted:?}");
}