0x0007 · deviceFriendlyName
通过 15-byte 名称分块读取或修改设备专属友好名称。
deviceFriendlyName 保存用户指定的标签。它与 0x0005 deviceTypeAndName 中固定的市场名称不同。该功能以 15-byte 分块读取当前名称和默认名称,并可写入或重置当前名称。
**规格:**没有公开的 Logitech 规格。布局由 Logi Options+ 2.8 静态分析逆向得出。**用于:**OpenLogi 未使用。
函数参考
已注册的 DeviceFriendlyNameFeature 封装实现功能版本 0。
方法
| 函数 | HID++ fn | 签名 | 返回值 |
|---|---|---|---|
get_friendly_name_length | 0 | () | DeviceFriendlyNameLength |
get_friendly_name | 1 | (index: u8) | [u8; 15] |
get_whole_friendly_name | 便捷方法 | () | String |
get_default_friendly_name | 2 | (index: u8) | [u8; 15] |
get_whole_default_friendly_name | 便捷方法 | () | String |
set_friendly_name | 3 | (index: u8, chunk: [u8; 15]) | u8 |
set_whole_device_name | 便捷方法 | (name: String) | u8 |
reset_friendly_name | 4 | () | u8 |
所有方法都是异步方法,并返回 Result<…, Hidpp20Error>。便捷方法会执行多个 HID++ 调用,因此没有单一函数索引。
set_friendly_name 返回响应中的回显 charIndex。它不返回名称长度。set_whole_device_name 返回截断后实际发送的输入名称字节数。
类型
DeviceFriendlyNameLength
| 字段 | 类型 | 说明 |
|---|---|---|
name_length | u8 | 设备报告的当前名称长度。 |
name_max_length | u8 | 设备报告的最大可写名称长度。 |
default_name_length | u8 | 设备报告的默认名称长度。 |
事件
可用证据没有记录事件布局。OpenLogi 没有为此功能注册事件处理程序。
线格式
函数 0、1、2 和 4 使用 3-byte short request。函数 3 使用 16-byte long request。下列字节偏移从 HID++ 功能 header 后开始计算。
get_friendly_name_length(fn 0)
请求:[0x00, 0x00, 0x00]
| 字节 | 字段 | 说明 |
|---|---|---|
| 0 | name_length | 当前友好名称长度。 |
| 1 | name_max_length | 最大可写友好名称长度。 |
| 2 | default_name_length | 默认友好名称长度。 |
| 3–15 | 尾部 payload | 在 extend_payload() 后,OpenLogi 忽略这些字节。 |
get_friendly_name(fn 1)
请求:[char_index, 0x00, 0x00]
| 字节 | 字段 | 说明 |
|---|---|---|
| 0 | char_index | 请求分块开始处的名称偏移。 |
| 1–2 | 保留 | OpenLogi 写入 0x00。 |
| 字节 | 字段 | 说明 |
|---|---|---|
| 0 | 回显的 char_index | 与请求不同时,OpenLogi 会记录 warning。它会保留分块,与 Options+ 2.8 一致。 |
| 1–15 | 名称分块 | 15 个名称字节。OpenLogi 将这些字节复制到 [u8; 15]。 |
get_default_friendly_name(fn 2)
请求:[char_index, 0x00, 0x00]
| 字节 | 字段 | 说明 |
|---|---|---|
| 0 | char_index | 请求分块开始处的默认名称偏移。 |
| 1–2 | 保留 | OpenLogi 写入 0x00。 |
| 字节 | 字段 | 说明 |
|---|---|---|
| 0 | 回显的 char_index | 与请求不同时,OpenLogi 会记录 warning。它会保留分块。Options+ 2.8。 |
| 1–15 | 默认名称分块 | 15 个默认名称字节。OpenLogi 将这些字节复制到 [u8; 15]。 |
OpenLogi 对两个读取函数都使用 extend_payload()。short 响应会在封装复制字节 1–15 前补零。封装不会拒绝 short 响应。
set_friendly_name(fn 3)
请求:[char_index, chunk[0], …, chunk[14]]
| 字节 | 字段 | 说明 |
|---|---|---|
| 0 | char_index | 写入该分块的名称偏移。 |
| 1–15 | chunk | 恰好 15 个名称字节。整名帮助方法会为最后一个不完整分块补 0x00。 |
| 字节 | 字段 | 说明 |
|---|---|---|
| 0 | 回显的 char_index | set_friendly_name 返回这个原始字节。它不是长度。Options+ 2.8。 |
| 1–15 | 尾部 payload | OpenLogi 忽略这些字节。 |
reset_friendly_name(fn 4)
请求:[0x00, 0x00, 0x00]
| 字节 | 字段 | 说明 |
|---|---|---|
| 0 | 报告的长度 | reset_friendly_name 返回此字节。 |
| 1–15 | 尾部 payload | 在 extend_payload() 后,OpenLogi 忽略这些字节。 |
OpenLogi 的用法
设备功能表公布 0x0007 时,此功能会注册。OpenLogi v0.8.15 没有设备层、agent、IPC、CLI 或 UI 调用此封装。它不在库存或缓存身份中使用友好名称。
公开的整名读取方法先获得长度,再按自己的偏移读取分块,并删除尾部 NUL 字符。读取回显不匹配时会产生 warning,但读取不会失败。
公开的整名写入方法读取 name_max_length,按 UTF-8 字符边界截断输入,并在偏移 0、15、30 等位置发送补零分块。它使用本地偏移,而不使用响应字节。写入回显不匹配会产生 warning,但不会停止后续分块。写入方法不会读回存储的名称。
未确认的细节
没有公开的 Logitech 规格涵盖此功能。已知函数号和回显字段来自 Options+ 2.8 的静态分析。硬件抓包尚未验证所有布局。
可用证据没有确定功能版本门控或改名通知事件。它也没有确定空名称或恰好 15-byte 名称的设备行为。空输入时,OpenLogi 不写入分块,并建议用 reset_friendly_name 恢复默认值。
Rust 用法
use hidpp::{
device::Device,
feature::device_friendly_name::DeviceFriendlyNameFeature,
protocol::v20::Hidpp20Error,
};
async fn inspect_or_rename(device: &mut Device) -> Result<(), Hidpp20Error> {
device.enumerate_features().await?;
let Some(feature) = device.get_feature::<DeviceFriendlyNameFeature>() else {
return Ok(());
};
println!("current name: {}", feature.get_whole_friendly_name().await?);
let bytes_written = feature.set_whole_device_name("Desk mouse".to_owned()).await?;
println!("sent {bytes_written} name bytes");
Ok(())
}