1use std::{
2 num::NonZeroU32,
3 sync::atomic::{AtomicU32, Ordering::SeqCst},
4};
5
6use enumflags2::{bitflags, BitFlags};
7use serde::{Deserialize, Serialize};
8use serde_repr::{Deserialize_repr, Serialize_repr};
9
10use static_assertions::assert_impl_all;
11use zbus_names::{BusName, ErrorName, InterfaceName, MemberName, UniqueName};
12use zvariant::{
13 serialized::{self, Context},
14 Endian, ObjectPath, Signature, Type as VariantType,
15};
16
17use crate::{
18 message::{Field, FieldCode, Fields},
19 Error,
20};
21
22pub(crate) const PRIMARY_HEADER_SIZE: usize = 12;
23pub(crate) const MIN_MESSAGE_SIZE: usize = PRIMARY_HEADER_SIZE + 4;
24pub(crate) const MAX_MESSAGE_SIZE: usize = 128 * 1024 * 1024; // 128 MiB
25
26/// D-Bus code for endianness.
27#[repr(u8)]
28#[derive(Debug, Copy, Clone, Deserialize_repr, PartialEq, Eq, Serialize_repr, VariantType)]
29pub enum EndianSig {
30 /// The D-Bus message is in big-endian (network) byte order.
31 Big = b'B',
32
33 /// The D-Bus message is in little-endian byte order.
34 Little = b'l',
35}
36
37assert_impl_all!(EndianSig: Send, Sync, Unpin);
38
39// Such a shame I've to do this manually
40impl TryFrom<u8> for EndianSig {
41 type Error = Error;
42
43 fn try_from(val: u8) -> Result<EndianSig, Error> {
44 match val {
45 b'B' => Ok(EndianSig::Big),
46 b'l' => Ok(EndianSig::Little),
47 _ => Err(Error::IncorrectEndian),
48 }
49 }
50}
51
52#[cfg(target_endian = "big")]
53/// Signature of the target's native endian.
54pub const NATIVE_ENDIAN_SIG: EndianSig = EndianSig::Big;
55#[cfg(target_endian = "little")]
56/// Signature of the target's native endian.
57pub const NATIVE_ENDIAN_SIG: EndianSig = EndianSig::Little;
58
59impl From<Endian> for EndianSig {
60 fn from(endian: Endian) -> Self {
61 match endian {
62 Endian::Little => EndianSig::Little,
63 Endian::Big => EndianSig::Big,
64 }
65 }
66}
67
68impl From<EndianSig> for Endian {
69 fn from(endian_sig: EndianSig) -> Self {
70 match endian_sig {
71 EndianSig::Little => Endian::Little,
72 EndianSig::Big => Endian::Big,
73 }
74 }
75}
76
77/// Message header representing the D-Bus type of the message.
78#[repr(u8)]
79#[derive(
80 Debug, Copy, Clone, Deserialize_repr, PartialEq, Eq, Hash, Serialize_repr, VariantType,
81)]
82pub enum Type {
83 /// Method call. This message type may prompt a reply (and typically does).
84 MethodCall = 1,
85 /// A reply to a method call.
86 MethodReturn = 2,
87 /// An error in response to a method call.
88 Error = 3,
89 /// Signal emission.
90 Signal = 4,
91}
92
93assert_impl_all!(Type: Send, Sync, Unpin);
94
95/// Pre-defined flags that can be passed in Message header.
96#[bitflags]
97#[repr(u8)]
98#[derive(Debug, Copy, Clone, PartialEq, Eq, VariantType)]
99pub enum Flags {
100 /// This message does not expect method return replies or error replies, even if it is of a
101 /// type that can have a reply; the reply should be omitted.
102 ///
103 /// Note that `Type::MethodCall` is the only message type currently defined in the
104 /// specification that can expect a reply, so the presence or absence of this flag in the other
105 /// three message types that are currently documented is meaningless: replies to those message
106 /// types should not be sent, whether this flag is present or not.
107 NoReplyExpected = 0x1,
108 /// The bus must not launch an owner for the destination name in response to this message.
109 NoAutoStart = 0x2,
110 /// This flag may be set on a method call message to inform the receiving side that the caller
111 /// is prepared to wait for interactive authorization, which might take a considerable time to
112 /// complete. For instance, if this flag is set, it would be appropriate to query the user for
113 /// passwords or confirmation via Polkit or a similar framework.
114 AllowInteractiveAuth = 0x4,
115}
116
117assert_impl_all!(Flags: Send, Sync, Unpin);
118
119/// The primary message header, which is present in all D-Bus messages.
120///
121/// This header contains all the essential information about a message, regardless of its type.
122#[derive(Clone, Debug, Serialize, Deserialize, VariantType)]
123pub struct PrimaryHeader {
124 endian_sig: EndianSig,
125 msg_type: Type,
126 flags: BitFlags<Flags>,
127 protocol_version: u8,
128 body_len: u32,
129 serial_num: NonZeroU32,
130}
131
132assert_impl_all!(PrimaryHeader: Send, Sync, Unpin);
133
134impl PrimaryHeader {
135 /// Create a new `PrimaryHeader` instance.
136 pub fn new(msg_type: Type, body_len: u32) -> Self {
137 Self {
138 endian_sig: NATIVE_ENDIAN_SIG,
139 msg_type,
140 flags: BitFlags::empty(),
141 protocol_version: 1,
142 body_len,
143 serial_num: SERIAL_NUM.fetch_add(1, SeqCst).try_into().unwrap(),
144 }
145 }
146
147 pub(crate) fn read(buf: &[u8]) -> Result<(PrimaryHeader, u32), Error> {
148 let endian = Endian::from(EndianSig::try_from(buf[0])?);
149 let ctx = Context::new_dbus(endian, 0);
150 let data = serialized::Data::new(buf, ctx);
151
152 Self::read_from_data(&data)
153 }
154
155 pub(crate) fn read_from_data(
156 data: &serialized::Data<'_, '_>,
157 ) -> Result<(PrimaryHeader, u32), Error> {
158 let (primary_header, size) = data.deserialize()?;
159 assert_eq!(size, PRIMARY_HEADER_SIZE);
160 let (fields_len, _) = data.slice(PRIMARY_HEADER_SIZE..).deserialize()?;
161 Ok((primary_header, fields_len))
162 }
163
164 /// D-Bus code for endian encoding of the message.
165 pub fn endian_sig(&self) -> EndianSig {
166 self.endian_sig
167 }
168
169 /// Set the D-Bus code for endian encoding of the message.
170 pub fn set_endian_sig(&mut self, sig: EndianSig) {
171 self.endian_sig = sig;
172 }
173
174 /// The message type.
175 pub fn msg_type(&self) -> Type {
176 self.msg_type
177 }
178
179 /// Set the message type.
180 pub fn set_msg_type(&mut self, msg_type: Type) {
181 self.msg_type = msg_type;
182 }
183
184 /// The message flags.
185 pub fn flags(&self) -> BitFlags<Flags> {
186 self.flags
187 }
188
189 /// Set the message flags.
190 pub fn set_flags(&mut self, flags: BitFlags<Flags>) {
191 self.flags = flags;
192 }
193
194 /// The major version of the protocol the message is compliant to.
195 ///
196 /// Currently only `1` is valid.
197 pub fn protocol_version(&self) -> u8 {
198 self.protocol_version
199 }
200
201 /// Set the major version of the protocol the message is compliant to.
202 ///
203 /// Currently only `1` is valid.
204 pub fn set_protocol_version(&mut self, version: u8) {
205 self.protocol_version = version;
206 }
207
208 /// The byte length of the message body.
209 pub fn body_len(&self) -> u32 {
210 self.body_len
211 }
212
213 /// Set the byte length of the message body.
214 pub fn set_body_len(&mut self, len: u32) {
215 self.body_len = len;
216 }
217
218 /// The serial number of the message.
219 ///
220 /// This is used to match a reply to a method call.
221 pub fn serial_num(&self) -> NonZeroU32 {
222 self.serial_num
223 }
224
225 /// Set the serial number of the message.
226 ///
227 /// This is used to match a reply to a method call.
228 pub fn set_serial_num(&mut self, serial_num: NonZeroU32) {
229 self.serial_num = serial_num;
230 }
231}
232
233/// The message header, containing all the metadata about the message.
234///
235/// This includes both the [`PrimaryHeader`] and [`Fields`].
236///
237/// [`PrimaryHeader`]: struct.PrimaryHeader.html
238/// [`Fields`]: struct.Fields.html
239#[derive(Debug, Clone, Serialize, Deserialize, VariantType)]
240pub struct Header<'m> {
241 primary: PrimaryHeader,
242 #[serde(borrow)]
243 fields: Fields<'m>,
244}
245
246assert_impl_all!(Header<'_>: Send, Sync, Unpin);
247
248macro_rules! get_field {
249 ($self:ident, $kind:ident) => {
250 get_field!($self, $kind, (|v| v))
251 };
252 ($self:ident, $kind:ident, $closure:tt) => {
253 #[allow(clippy::redundant_closure_call)]
254 match $self.fields().get_field(FieldCode::$kind) {
255 Some(Field::$kind(value)) => Some($closure(value)),
256 // SAFETY: `Deserialize` impl for `Field` ensures that the code and field match.
257 Some(_) => unreachable!("FieldCode and Field mismatch"),
258 None => None,
259 }
260 };
261}
262
263macro_rules! get_field_u32 {
264 ($self:ident, $kind:ident) => {
265 get_field!($self, $kind, (|v: &u32| *v))
266 };
267}
268
269impl<'m> Header<'m> {
270 /// Create a new `Header` instance.
271 pub(super) fn new(primary: PrimaryHeader, fields: Fields<'m>) -> Self {
272 Self { primary, fields }
273 }
274
275 /// Get a reference to the primary header.
276 pub fn primary(&self) -> &PrimaryHeader {
277 &self.primary
278 }
279
280 /// Get a mutable reference to the primary header.
281 pub fn primary_mut(&mut self) -> &mut PrimaryHeader {
282 &mut self.primary
283 }
284
285 /// Get the primary header, consuming `self`.
286 pub fn into_primary(self) -> PrimaryHeader {
287 self.primary
288 }
289
290 /// Get a reference to the message fields.
291 fn fields(&self) -> &Fields<'m> {
292 &self.fields
293 }
294
295 /// Get a mutable reference to the message fields.
296 pub(super) fn fields_mut(&mut self) -> &mut Fields<'m> {
297 &mut self.fields
298 }
299
300 /// The message type
301 pub fn message_type(&self) -> Type {
302 self.primary().msg_type()
303 }
304
305 /// The object to send a call to, or the object a signal is emitted from.
306 pub fn path(&self) -> Option<&ObjectPath<'m>> {
307 get_field!(self, Path)
308 }
309
310 /// The interface to invoke a method call on, or that a signal is emitted from.
311 pub fn interface(&self) -> Option<&InterfaceName<'m>> {
312 get_field!(self, Interface)
313 }
314
315 /// The member, either the method name or signal name.
316 pub fn member(&self) -> Option<&MemberName<'m>> {
317 get_field!(self, Member)
318 }
319
320 /// The name of the error that occurred, for errors.
321 pub fn error_name(&self) -> Option<&ErrorName<'m>> {
322 get_field!(self, ErrorName)
323 }
324
325 /// The serial number of the message this message is a reply to.
326 pub fn reply_serial(&self) -> Option<NonZeroU32> {
327 match self.fields().get_field(FieldCode::ReplySerial) {
328 Some(Field::ReplySerial(value)) => Some(*value),
329 // SAFETY: `Deserialize` impl for `Field` ensures that the code and field match.
330 Some(_) => unreachable!("FieldCode and Field mismatch"),
331 None => None,
332 }
333 }
334
335 /// The name of the connection this message is intended for.
336 pub fn destination(&self) -> Option<&BusName<'m>> {
337 get_field!(self, Destination)
338 }
339
340 /// Unique name of the sending connection.
341 pub fn sender(&self) -> Option<&UniqueName<'m>> {
342 get_field!(self, Sender)
343 }
344
345 /// The signature of the message body.
346 pub fn signature(&self) -> Option<&Signature<'m>> {
347 get_field!(self, Signature)
348 }
349
350 /// The number of Unix file descriptors that accompany the message.
351 pub fn unix_fds(&self) -> Option<u32> {
352 get_field_u32!(self, UnixFDs)
353 }
354}
355
356static SERIAL_NUM: AtomicU32 = AtomicU32::new(1);
357
358#[cfg(test)]
359mod tests {
360 use crate::message::{Field, Fields, Header, PrimaryHeader, Type};
361
362 use std::error::Error;
363 use test_log::test;
364 use zbus_names::{InterfaceName, MemberName};
365 use zvariant::{ObjectPath, Signature};
366
367 #[test]
368 fn header() -> Result<(), Box<dyn Error>> {
369 let path = ObjectPath::try_from("/some/path")?;
370 let iface = InterfaceName::try_from("some.interface")?;
371 let member = MemberName::try_from("Member")?;
372 let mut f = Fields::new();
373 f.add(Field::Path(path.clone()));
374 f.add(Field::Interface(iface.clone()));
375 f.add(Field::Member(member.clone()));
376 f.add(Field::Sender(":1.84".try_into()?));
377 let h = Header::new(PrimaryHeader::new(Type::Signal, 77), f);
378
379 assert_eq!(h.message_type(), Type::Signal);
380 assert_eq!(h.path(), Some(&path));
381 assert_eq!(h.interface(), Some(&iface));
382 assert_eq!(h.member(), Some(&member));
383 assert_eq!(h.error_name(), None);
384 assert_eq!(h.destination(), None);
385 assert_eq!(h.reply_serial(), None);
386 assert_eq!(h.sender().unwrap(), ":1.84");
387 assert_eq!(h.signature(), None);
388 assert_eq!(h.unix_fds(), None);
389
390 let mut f = Fields::new();
391 f.add(Field::ErrorName("org.zbus.Error".try_into()?));
392 f.add(Field::Destination(":1.11".try_into()?));
393 f.add(Field::ReplySerial(88.try_into()?));
394 f.add(Field::Signature(Signature::from_str_unchecked("say")));
395 f.add(Field::UnixFDs(12));
396 let h = Header::new(PrimaryHeader::new(Type::MethodReturn, 77), f);
397
398 assert_eq!(h.message_type(), Type::MethodReturn);
399 assert_eq!(h.path(), None);
400 assert_eq!(h.interface(), None);
401 assert_eq!(h.member(), None);
402 assert_eq!(h.error_name().unwrap(), "org.zbus.Error");
403 assert_eq!(h.destination().unwrap(), ":1.11");
404 assert_eq!(h.reply_serial().map(Into::into), Some(88));
405 assert_eq!(h.sender(), None);
406 assert_eq!(h.signature(), Some(&Signature::from_str_unchecked("say")));
407 assert_eq!(h.unix_fds(), Some(12));
408
409 Ok(())
410 }
411}
412