1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
//! Implements the `DeviceFriendlyName` feature (ID `0x0007`) that provides
//! functionality to set and retrieve a custom device name.
use openlogi_hidpp_derive::Feature;
use crate::{feature::FeatureEndpoint, protocol::v20::Hidpp20Error};
/// Implements the `DeviceFriendlyName` / `0x0007` feature.
#[derive(Clone, Feature)]
#[creatable(id = 0x0007, version = 0)]
pub struct DeviceFriendlyNameFeature {
/// The endpoint this feature talks to.
endpoint: FeatureEndpoint,
}
impl DeviceFriendlyNameFeature {
/// Retrieves the length data of the friendly device name feature.
pub async fn get_friendly_name_length(&self) -> Result<DeviceFriendlyNameLength, Hidpp20Error> {
let payload = self.endpoint.call(0, [0; 3]).await?.extend_payload();
Ok(DeviceFriendlyNameLength {
name_length: payload[0],
name_max_length: payload[1],
default_name_length: payload[2],
})
}
/// Retrieves a chunk of characters of the friendly name of the device,
/// starting at a specific index (inclusive).
///
/// This function will always retrieve 15 bytes, filling up the rest with
/// zeroes if the chunk is shorter than that.
///
/// Use this function in conjunction with [`Self::get_friendly_name_length`]
/// to retrieve the whole friendly name of the device.\
/// A convenience wrapper implementing this functionality is provided as
/// [`Self::get_whole_friendly_name`].
pub async fn get_friendly_name(&self, index: u8) -> Result<[u8; 15], Hidpp20Error> {
let payload = self
.endpoint
.call(1, [index, 0x00, 0x00])
.await?
.extend_payload();
Ok([
payload[1],
payload[2],
payload[3],
payload[4],
payload[5],
payload[6],
payload[7],
payload[8],
payload[9],
payload[10],
payload[11],
payload[12],
payload[13],
payload[14],
payload[15],
])
}
/// Retrieves the whole friendly name of the device by first calling
/// [`Self::get_friendly_name_length`] once and then repeatedly calling
/// [`Self::get_friendly_name`] until all characters were received.
pub async fn get_whole_friendly_name(&self) -> Result<String, Hidpp20Error> {
let count = self.get_friendly_name_length().await?.name_length;
let mut string = String::with_capacity(count as usize);
let mut len = 0;
while len < count as usize {
#[expect(
clippy::cast_possible_truncation,
reason = "len < count as usize and count is a u8, so len always fits in u8"
)]
let index = len as u8;
let part = self.get_friendly_name(index).await?;
string.push_str(str::from_utf8(&part).map_err(|_| Hidpp20Error::UnsupportedResponse)?);
len = string.len();
}
Ok(string.trim_end_matches(char::from(0)).to_string())
}
/// Retrieves a chunk of characters of the default friendly name of the
/// device, starting at a specific index (inclusive).
///
/// This function will always retrieve 15 bytes, filling up the rest with
/// zeroes if the chunk is shorter than that.
///
/// Use this function in conjunction with [`Self::get_friendly_name_length`]
/// to retrieve the whole default friendly name of the device.\
/// A convenience wrapper implementing this functionality is provided as
/// [`Self::get_whole_default_friendly_name`].
pub async fn get_default_friendly_name(&self, index: u8) -> Result<[u8; 15], Hidpp20Error> {
let payload = self
.endpoint
.call(2, [index, 0x00, 0x00])
.await?
.extend_payload();
Ok([
payload[1],
payload[2],
payload[3],
payload[4],
payload[5],
payload[6],
payload[7],
payload[8],
payload[9],
payload[10],
payload[11],
payload[12],
payload[13],
payload[14],
payload[15],
])
}
/// Retrieves the whole default friendly name of the device by first calling
/// [`Self::get_friendly_name_length`] once and then repeatedly calling
/// [`Self::get_default_friendly_name`] until all characters were received.
pub async fn get_whole_default_friendly_name(&self) -> Result<String, Hidpp20Error> {
let count = self.get_friendly_name_length().await?.default_name_length;
let mut string = String::with_capacity(count as usize);
let mut len = 0;
while len < count as usize {
#[expect(
clippy::cast_possible_truncation,
reason = "len < count as usize and count is a u8, so len always fits in u8"
)]
let index = len as u8;
let part = self.get_default_friendly_name(index).await?;
string.push_str(str::from_utf8(&part).map_err(|_| Hidpp20Error::UnsupportedResponse)?);
len = string.len();
}
Ok(string.trim_end_matches(char::from(0)).to_string())
}
/// Sets a chunk of the friendly device name, starting at a specific index
/// (inclusive).
///
/// If the index and chunk combination would exceed the
/// [`DeviceFriendlyNameLength::name_max_length`], the name is automatically
/// truncated by the device.
///
/// Returns the new total length of the friendly device name.
///
/// A convenience wrapper setting the whole friendly device name at once is
/// provided as [`Self::set_whole_device_name`].
pub async fn set_friendly_name(&self, index: u8, chunk: [u8; 15]) -> Result<u8, Hidpp20Error> {
let mut data = [0u8; 16];
data[0] = index;
data[1..].copy_from_slice(&chunk);
let payload = self.endpoint.call_long(3, data).await?.extend_payload();
Ok(payload[0])
}
/// Sets the whole friendly device name, truncating the value to a maximum
/// of [`DeviceFriendlyNameLength::name_max_length`] bytes.
///
/// This method calls [`Self::get_friendly_name_length`] first to retrieve
/// the maximum length and then repeatedly calls [`Self::set_friendly_name`]
/// until the whole name is set.
///
/// Returns the total length of the name after setting it,
pub async fn set_whole_device_name(&self, name: String) -> Result<u8, Hidpp20Error> {
let max_len = self.get_friendly_name_length().await?.name_max_length;
let mut bytes = name.into_bytes();
bytes.truncate(max_len as usize);
let chunks = bytes.chunks_exact(15);
let remainder = chunks.remainder();
let mut index = 0;
for chunk in chunks {
// `chunks_exact(15)` guarantees every yielded chunk is exactly 15
// bytes long.
let chunk: [u8; 15] = std::array::from_fn(|i| chunk[i]);
index += self.set_friendly_name(index, chunk).await?;
}
if !remainder.is_empty() {
let mut chunk = [0u8; 15];
chunk[..remainder.len()].copy_from_slice(remainder);
index += self.set_friendly_name(index, chunk).await?;
}
Ok(index)
}
/// Resets the friendly device name to the default one.
///
/// Returns the total length of the name after resetting it,
pub async fn reset_friendly_name(&self) -> Result<u8, Hidpp20Error> {
Ok(self.endpoint.call(4, [0; 3]).await?.extend_payload()[0])
}
}
/// Represents the length data as returned by
/// [`DeviceFriendlyNameFeature::get_friendly_name_length`].
#[derive(Clone, Copy, PartialEq, Eq, Hash, Debug)]
#[cfg_attr(feature = "serde", derive(serde::Serialize))]
#[non_exhaustive]
pub struct DeviceFriendlyNameLength {
/// The current length of the friendly device name.
pub name_length: u8,
/// The maximum length of the friendly device name.
pub name_max_length: u8,
/// The length of the default friendly device name.
pub default_name_length: u8,
}