1use std::{
2 io::{Cursor, Write},
3 sync::Arc,
4};
5#[cfg(unix)]
6use zvariant::OwnedFd;
7
8use enumflags2::BitFlags;
9use zbus_names::{BusName, ErrorName, InterfaceName, MemberName, UniqueName};
10use zvariant::{serialized, Endian};
11
12use crate::{
13 message::{Field, FieldCode, Fields, Flags, Header, Message, PrimaryHeader, Sequence, Type},
14 utils::padding_for_8_bytes,
15 zvariant::{serialized::Context, DynamicType, ObjectPath, Signature},
16 EndianSig, Error, Result,
17};
18
19use crate::message::{fields::QuickFields, header::MAX_MESSAGE_SIZE};
20
21#[cfg(unix)]
22type BuildGenericResult = Vec<OwnedFd>;
23
24#[cfg(not(unix))]
25type BuildGenericResult = ();
26
27macro_rules! dbus_context {
28 ($self:ident, $n_bytes_before: expr) => {
29 Context::new_dbus($self.header.primary().endian_sig().into(), $n_bytes_before)
30 };
31}
32
33/// A builder for [`Message`]
34#[derive(Debug, Clone)]
35pub struct Builder<'a> {
36 header: Header<'a>,
37}
38
39impl<'a> Builder<'a> {
40 fn new(msg_type: Type) -> Self {
41 let primary = PrimaryHeader::new(msg_type, 0);
42 let fields = Fields::new();
43 let header = Header::new(primary, fields);
44 Self { header }
45 }
46
47 /// Create a message of type [`Type::MethodCall`].
48 #[deprecated(since = "4.0.0", note = "Please use `Message::method` instead")]
49 pub fn method_call<'p: 'a, 'm: 'a, P, M>(path: P, method_name: M) -> Result<Self>
50 where
51 P: TryInto<ObjectPath<'p>>,
52 M: TryInto<MemberName<'m>>,
53 P::Error: Into<Error>,
54 M::Error: Into<Error>,
55 {
56 Self::new(Type::MethodCall).path(path)?.member(method_name)
57 }
58
59 /// Create a message of type [`Type::Signal`].
60 #[deprecated(since = "4.0.0", note = "Please use `Message::signal` instead")]
61 pub fn signal<'p: 'a, 'i: 'a, 'm: 'a, P, I, M>(path: P, interface: I, name: M) -> Result<Self>
62 where
63 P: TryInto<ObjectPath<'p>>,
64 I: TryInto<InterfaceName<'i>>,
65 M: TryInto<MemberName<'m>>,
66 P::Error: Into<Error>,
67 I::Error: Into<Error>,
68 M::Error: Into<Error>,
69 {
70 Self::new(Type::Signal)
71 .path(path)?
72 .interface(interface)?
73 .member(name)
74 }
75
76 /// Create a message of type [`Type::MethodReturn`].
77 #[deprecated(since = "4.0.0", note = "Please use `Message::method_reply` instead")]
78 pub fn method_return(reply_to: &Header<'_>) -> Result<Self> {
79 Self::new(Type::MethodReturn).reply_to(reply_to)
80 }
81
82 /// Create a message of type [`Type::Error`].
83 #[deprecated(since = "4.0.0", note = "Please use `Message::method_error` instead")]
84 pub fn error<'e: 'a, E>(reply_to: &Header<'_>, name: E) -> Result<Self>
85 where
86 E: TryInto<ErrorName<'e>>,
87 E::Error: Into<Error>,
88 {
89 Self::new(Type::Error).error_name(name)?.reply_to(reply_to)
90 }
91
92 /// Add flags to the message.
93 ///
94 /// See [`Flags`] documentation for the meaning of the flags.
95 ///
96 /// The function will return an error if invalid flags are given for the message type.
97 pub fn with_flags(mut self, flag: Flags) -> Result<Self> {
98 if self.header.message_type() != Type::MethodCall
99 && BitFlags::from_flag(flag).contains(Flags::NoReplyExpected)
100 {
101 return Err(Error::InvalidField);
102 }
103 let flags = self.header.primary().flags() | flag;
104 self.header.primary_mut().set_flags(flags);
105 Ok(self)
106 }
107
108 /// Set the unique name of the sending connection.
109 pub fn sender<'s: 'a, S>(mut self, sender: S) -> Result<Self>
110 where
111 S: TryInto<UniqueName<'s>>,
112 S::Error: Into<Error>,
113 {
114 self.header
115 .fields_mut()
116 .replace(Field::Sender(sender.try_into().map_err(Into::into)?));
117 Ok(self)
118 }
119
120 /// Set the object to send a call to, or the object a signal is emitted from.
121 pub fn path<'p: 'a, P>(mut self, path: P) -> Result<Self>
122 where
123 P: TryInto<ObjectPath<'p>>,
124 P::Error: Into<Error>,
125 {
126 self.header
127 .fields_mut()
128 .replace(Field::Path(path.try_into().map_err(Into::into)?));
129 Ok(self)
130 }
131
132 /// Set the interface to invoke a method call on, or that a signal is emitted from.
133 pub fn interface<'i: 'a, I>(mut self, interface: I) -> Result<Self>
134 where
135 I: TryInto<InterfaceName<'i>>,
136 I::Error: Into<Error>,
137 {
138 self.header
139 .fields_mut()
140 .replace(Field::Interface(interface.try_into().map_err(Into::into)?));
141 Ok(self)
142 }
143
144 /// Set the member, either the method name or signal name.
145 pub fn member<'m: 'a, M>(mut self, member: M) -> Result<Self>
146 where
147 M: TryInto<MemberName<'m>>,
148 M::Error: Into<Error>,
149 {
150 self.header
151 .fields_mut()
152 .replace(Field::Member(member.try_into().map_err(Into::into)?));
153 Ok(self)
154 }
155
156 fn error_name<'e: 'a, E>(mut self, error: E) -> Result<Self>
157 where
158 E: TryInto<ErrorName<'e>>,
159 E::Error: Into<Error>,
160 {
161 self.header
162 .fields_mut()
163 .replace(Field::ErrorName(error.try_into().map_err(Into::into)?));
164 Ok(self)
165 }
166
167 /// Set the name of the connection this message is intended for.
168 pub fn destination<'d: 'a, D>(mut self, destination: D) -> Result<Self>
169 where
170 D: TryInto<BusName<'d>>,
171 D::Error: Into<Error>,
172 {
173 self.header.fields_mut().replace(Field::Destination(
174 destination.try_into().map_err(Into::into)?,
175 ));
176 Ok(self)
177 }
178
179 fn reply_to(mut self, reply_to: &Header<'_>) -> Result<Self> {
180 let serial = reply_to.primary().serial_num();
181 self.header.fields_mut().replace(Field::ReplySerial(serial));
182 self = self.endian(reply_to.primary().endian_sig().into());
183
184 if let Some(sender) = reply_to.sender() {
185 self.destination(sender.to_owned())
186 } else {
187 Ok(self)
188 }
189 }
190
191 /// Set the endianness of the message.
192 ///
193 /// The default endianness is native.
194 pub fn endian(mut self, endian: Endian) -> Self {
195 let sig = EndianSig::from(endian);
196 self.header.primary_mut().set_endian_sig(sig);
197
198 self
199 }
200
201 /// Build the [`Message`] with the given body.
202 ///
203 /// You may pass `()` as the body if the message has no body.
204 ///
205 /// The caller is currently required to ensure that the resulting message contains the headers
206 /// as compliant with the [specification]. Additional checks may be added to this builder over
207 /// time as needed.
208 ///
209 /// [specification]:
210 /// https://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-header-fields
211 pub fn build<B>(self, body: &B) -> Result<Message>
212 where
213 B: serde::ser::Serialize + DynamicType,
214 {
215 let ctxt = dbus_context!(self, 0);
216
217 // Note: this iterates the body twice, but we prefer efficient handling of large messages
218 // to efficient handling of ones that are complex to serialize.
219 let body_size = zvariant::serialized_size(ctxt, body)?;
220
221 let signature = body.dynamic_signature();
222
223 self.build_generic(signature, body_size, move |cursor| {
224 // SAFETY: build_generic puts FDs and the body in the same Message.
225 unsafe { zvariant::to_writer(cursor, ctxt, body) }
226 .map(|s| {
227 #[cfg(unix)]
228 {
229 s.into_fds()
230 }
231 #[cfg(not(unix))]
232 {
233 let _ = s;
234 }
235 })
236 .map_err(Into::into)
237 })
238 }
239
240 /// Create a new message from a raw slice of bytes to populate the body with, rather than by
241 /// serializing a value. The message body will be the exact bytes.
242 ///
243 /// # Safety
244 ///
245 /// This method is unsafe because it can be used to build an invalid message.
246 pub unsafe fn build_raw_body<'b, S>(
247 self,
248 body_bytes: &[u8],
249 signature: S,
250 #[cfg(unix)] fds: Vec<OwnedFd>,
251 ) -> Result<Message>
252 where
253 S: TryInto<Signature<'b>>,
254 S::Error: Into<Error>,
255 {
256 let signature: Signature<'b> = signature.try_into().map_err(Into::into)?;
257 let body_size = serialized::Size::new(body_bytes.len(), dbus_context!(self, 0));
258 #[cfg(unix)]
259 let body_size = {
260 let num_fds = fds.len().try_into().map_err(|_| Error::ExcessData)?;
261 body_size.set_num_fds(num_fds)
262 };
263
264 self.build_generic(
265 signature,
266 body_size,
267 move |cursor: &mut Cursor<&mut Vec<u8>>| {
268 cursor.write_all(body_bytes)?;
269
270 #[cfg(unix)]
271 return Ok::<Vec<OwnedFd>, Error>(fds);
272
273 #[cfg(not(unix))]
274 return Ok::<(), Error>(());
275 },
276 )
277 }
278
279 fn build_generic<WriteFunc>(
280 self,
281 mut signature: Signature<'_>,
282 body_size: serialized::Size,
283 write_body: WriteFunc,
284 ) -> Result<Message>
285 where
286 WriteFunc: FnOnce(&mut Cursor<&mut Vec<u8>>) -> Result<BuildGenericResult>,
287 {
288 let ctxt = dbus_context!(self, 0);
289 let mut header = self.header;
290
291 if !signature.is_empty() {
292 if signature.starts_with(zvariant::STRUCT_SIG_START_STR) {
293 // Remove leading and trailing STRUCT delimiters
294 signature = signature.slice(1..signature.len() - 1);
295 }
296 header.fields_mut().add(Field::Signature(signature));
297 }
298
299 let body_len_u32 = body_size.size().try_into().map_err(|_| Error::ExcessData)?;
300 header.primary_mut().set_body_len(body_len_u32);
301
302 #[cfg(unix)]
303 {
304 let fds_len = body_size.num_fds();
305 if fds_len != 0 {
306 header.fields_mut().add(Field::UnixFDs(fds_len));
307 }
308 }
309
310 let hdr_len = *zvariant::serialized_size(ctxt, &header)?;
311 // We need to align the body to 8-byte boundary.
312 let body_padding = padding_for_8_bytes(hdr_len);
313 let body_offset = hdr_len + body_padding;
314 let total_len = body_offset + body_size.size();
315 if total_len > MAX_MESSAGE_SIZE {
316 return Err(Error::ExcessData);
317 }
318 let mut bytes: Vec<u8> = Vec::with_capacity(total_len);
319 let mut cursor = Cursor::new(&mut bytes);
320
321 // SAFETY: There are no FDs involved.
322 unsafe { zvariant::to_writer(&mut cursor, ctxt, &header) }?;
323 for _ in 0..body_padding {
324 cursor.write_all(&[0u8])?;
325 }
326 #[cfg(unix)]
327 let fds: Vec<_> = write_body(&mut cursor)?.into_iter().collect();
328 #[cfg(not(unix))]
329 write_body(&mut cursor)?;
330
331 let primary_header = header.into_primary();
332 #[cfg(unix)]
333 let bytes = serialized::Data::new_fds(bytes, ctxt, fds);
334 #[cfg(not(unix))]
335 let bytes = serialized::Data::new(bytes, ctxt);
336 let (header, actual_hdr_len): (Header<'_>, _) = bytes.deserialize()?;
337 assert_eq!(hdr_len, actual_hdr_len);
338 let quick_fields = QuickFields::new(&bytes, &header)?;
339
340 Ok(Message {
341 inner: Arc::new(super::Inner {
342 primary_header,
343 quick_fields,
344 bytes,
345 body_offset,
346 recv_seq: Sequence::default(),
347 }),
348 })
349 }
350}
351
352impl<'m> From<Header<'m>> for Builder<'m> {
353 fn from(mut header: Header<'m>) -> Self {
354 // Signature and Fds are added by body* methods.
355 let fields: &mut Fields<'_> = header.fields_mut();
356 fields.remove(code:FieldCode::Signature);
357 fields.remove(code:FieldCode::UnixFDs);
358
359 Self { header }
360 }
361}
362
363#[cfg(test)]
364mod tests {
365 use super::Message;
366 use crate::Error;
367 use test_log::test;
368
369 #[test]
370 fn test_raw() -> Result<(), Error> {
371 let raw_body: &[u8] = &[16, 0, 0, 0, 1, 0, 0, 0, 2, 0, 0, 0, 3, 0, 0, 0, 4, 0, 0, 0];
372 let message_builder = Message::signal("/", "test.test", "test")?;
373 let message = unsafe {
374 message_builder.build_raw_body(
375 raw_body,
376 "ai",
377 #[cfg(unix)]
378 vec![],
379 )?
380 };
381
382 let output: Vec<i32> = message.body().deserialize()?;
383 assert_eq!(output, vec![1, 2, 3, 4]);
384
385 Ok(())
386 }
387}
388