pub struct Message { /* private fields */ }
Expand description
A D-Bus Message.
The content of the message are stored in serialized format. To deserialize the body of the
message, use the body
method. You may also access the header and other details with the
various other getters.
Also provided are constructors for messages of different types. These will mainly be useful for
very advanced use cases as typically you will want to create a message for immediate dispatch
and hence use the API provided by Connection
, even when using the low-level API.
Note: The message owns the received FDs and will close them when dropped. You can call
take_fds
after deserializing to RawFD
using body
if you want to take the ownership.
Implementations§
source§impl Message
impl Message
sourcepub fn method<'s, 'd, 'p, 'i, 'm, S, D, P, I, M, B>(
sender: Option<S>,
destination: Option<D>,
path: P,
iface: Option<I>,
method_name: M,
body: &B,
) -> Result<Self>
pub fn method<'s, 'd, 'p, 'i, 'm, S, D, P, I, M, B>( sender: Option<S>, destination: Option<D>, path: P, iface: Option<I>, method_name: M, body: &B, ) -> Result<Self>
Create a message of type MessageType::MethodCall
.
sourcepub fn signal<'s, 'd, 'p, 'i, 'm, S, D, P, I, M, B>(
sender: Option<S>,
destination: Option<D>,
path: P,
iface: I,
signal_name: M,
body: &B,
) -> Result<Self>
pub fn signal<'s, 'd, 'p, 'i, 'm, S, D, P, I, M, B>( sender: Option<S>, destination: Option<D>, path: P, iface: I, signal_name: M, body: &B, ) -> Result<Self>
Create a message of type MessageType::Signal
.
sourcepub fn method_reply<'s, S, B>(
sender: Option<S>,
call: &Self,
body: &B,
) -> Result<Self>
pub fn method_reply<'s, S, B>( sender: Option<S>, call: &Self, body: &B, ) -> Result<Self>
Create a message of type MessageType::MethodReturn
.
sourcepub fn method_error<'s, 'e, S, E, B>(
sender: Option<S>,
call: &Self,
name: E,
body: &B,
) -> Result<Self>
pub fn method_error<'s, 'e, S, E, B>( sender: Option<S>, call: &Self, name: E, body: &B, ) -> Result<Self>
Create a message of type MessageType::MethodError
.
sourcepub unsafe fn from_bytes(bytes: Vec<u8>, fds: Vec<OwnedFd>) -> Result<Self>
pub unsafe fn from_bytes(bytes: Vec<u8>, fds: Vec<OwnedFd>) -> Result<Self>
Create a message from bytes.
The fds
parameter is only available on unix. It specifies the file descriptors that
accompany the message. On the wire, values of the UNIX_FD types store the index of the
corresponding file descriptor in this vector. Passing an empty vector on a message that
has UNIX_FD will result in an error.
Note: Since the constructed message is not construct by zbus, the receive sequence,
which can be acquired from Message::recv_position
, is not applicable and hence set
to 0
.
§Safety
This method is unsafe as bytes may have an invalid encoding.
sourcepub fn take_fds(&self) -> Vec<OwnedFd>
pub fn take_fds(&self) -> Vec<OwnedFd>
Take ownership of the associated file descriptors in the message.
When a message is received over a AF_UNIX socket, it may contain associated FDs. To prevent the message from closing those FDs on drop, call this method that returns all the received FDs with their ownership.
This function is Unix-specific.
Note: the message will continue to reference the files, so you must keep them open for as long as the message itself.
sourcepub fn body_signature(&self) -> Result<Signature<'_>>
pub fn body_signature(&self) -> Result<Signature<'_>>
The signature of the body.
Note: While zbus treats multiple arguments as a struct (to allow you to use the tuple syntax), D-Bus does not. Since this method gives you the signature expected on the wire by D-Bus, the trailing and leading STRUCT signature parenthesis will not be present in case of multiple arguments.
pub fn primary_header(&self) -> &MessagePrimaryHeader
sourcepub fn header(&self) -> Result<MessageHeader<'_>>
pub fn header(&self) -> Result<MessageHeader<'_>>
Deserialize the header.
Note: prefer using the direct access methods if possible; they are more efficient.
sourcepub fn fields(&self) -> Result<MessageFields<'_>>
pub fn fields(&self) -> Result<MessageFields<'_>>
Deserialize the fields.
Note: prefer using the direct access methods if possible; they are more efficient.
sourcepub fn message_type(&self) -> MessageType
pub fn message_type(&self) -> MessageType
The message type.
sourcepub fn path(&self) -> Option<ObjectPath<'_>>
pub fn path(&self) -> Option<ObjectPath<'_>>
The object to send a call to, or the object a signal is emitted from.
sourcepub fn interface(&self) -> Option<InterfaceName<'_>>
pub fn interface(&self) -> Option<InterfaceName<'_>>
The interface to invoke a method call on, or that a signal is emitted from.
sourcepub fn member(&self) -> Option<MemberName<'_>>
pub fn member(&self) -> Option<MemberName<'_>>
The member, either the method name or signal name.
sourcepub fn reply_serial(&self) -> Option<u32>
pub fn reply_serial(&self) -> Option<u32>
The serial number of the message this message is a reply to.
sourcepub fn body_unchecked<'d, 'm: 'd, B>(&'m self) -> Result<B>where
B: Deserialize<'d> + Type,
pub fn body_unchecked<'d, 'm: 'd, B>(&'m self) -> Result<B>where
B: Deserialize<'d> + Type,
Deserialize the body (without checking signature matching).
sourcepub fn body<'d, 'm: 'd, B>(&'m self) -> Result<B>where
B: DynamicDeserialize<'d>,
pub fn body<'d, 'm: 'd, B>(&'m self) -> Result<B>where
B: DynamicDeserialize<'d>,
Deserialize the body using the contained signature.
§Example
let send_body = (7i32, (2i32, "foo"), vec!["bar"]);
let message = Message::method(None::<&str>, Some("zbus.test"), "/", Some("zbus.test"), "ping", &send_body)?;
let body : zbus::zvariant::Structure = message.body()?;
let fields = body.fields();
assert!(matches!(fields[0], zvariant::Value::I32(7)));
assert!(matches!(fields[1], zvariant::Value::Structure(_)));
assert!(matches!(fields[2], zvariant::Value::Array(_)));
let reply_msg = Message::method_reply(None::<&str>, &message, &body)?;
let reply_value : (i32, (i32, &str), Vec<String>) = reply_msg.body()?;
assert_eq!(reply_value.0, 7);
assert_eq!(reply_value.2.len(), 1);
sourcepub fn body_as_bytes(&self) -> Result<&[u8]>
pub fn body_as_bytes(&self) -> Result<&[u8]>
Get a reference to the byte encoding of the body of the message.
sourcepub fn recv_position(&self) -> MessageSequence
pub fn recv_position(&self) -> MessageSequence
Get the receive ordering of a message.
This may be used to identify how two events were ordered on the bus. It only produces a
useful ordering for messages that were produced by the same zbus::Connection
.
This is completely unrelated to the serial number on the message, which is set by the peer and might not be ordered at all.
Trait Implementations§
source§impl AsRef<Message> for InterfacesAdded
impl AsRef<Message> for InterfacesAdded
source§impl AsRef<Message> for InterfacesAdded
impl AsRef<Message> for InterfacesAdded
source§impl AsRef<Message> for InterfacesRemoved
impl AsRef<Message> for InterfacesRemoved
source§impl AsRef<Message> for InterfacesRemoved
impl AsRef<Message> for InterfacesRemoved
source§impl AsRef<Message> for NameAcquired
impl AsRef<Message> for NameAcquired
source§impl AsRef<Message> for NameAcquired
impl AsRef<Message> for NameAcquired
source§impl AsRef<Message> for NameOwnerChanged
impl AsRef<Message> for NameOwnerChanged
source§impl AsRef<Message> for NameOwnerChanged
impl AsRef<Message> for NameOwnerChanged
source§impl AsRef<Message> for PropertiesChanged
impl AsRef<Message> for PropertiesChanged
source§impl AsRef<Message> for PropertiesChanged
impl AsRef<Message> for PropertiesChanged
source§impl<'s> TryFrom<&'s Message> for InterfacesAddedArgs<'s>
impl<'s> TryFrom<&'s Message> for InterfacesAddedArgs<'s>
source§impl<'s> TryFrom<&'s Message> for InterfacesAddedArgs<'s>
impl<'s> TryFrom<&'s Message> for InterfacesAddedArgs<'s>
source§impl<'s> TryFrom<&'s Message> for InterfacesRemovedArgs<'s>
impl<'s> TryFrom<&'s Message> for InterfacesRemovedArgs<'s>
source§impl<'s> TryFrom<&'s Message> for InterfacesRemovedArgs<'s>
impl<'s> TryFrom<&'s Message> for InterfacesRemovedArgs<'s>
source§impl<'s> TryFrom<&'s Message> for NameAcquiredArgs<'s>
impl<'s> TryFrom<&'s Message> for NameAcquiredArgs<'s>
source§impl<'s> TryFrom<&'s Message> for NameAcquiredArgs<'s>
impl<'s> TryFrom<&'s Message> for NameAcquiredArgs<'s>
source§impl<'s> TryFrom<&'s Message> for NameLostArgs<'s>
impl<'s> TryFrom<&'s Message> for NameLostArgs<'s>
source§impl<'s> TryFrom<&'s Message> for NameLostArgs<'s>
impl<'s> TryFrom<&'s Message> for NameLostArgs<'s>
source§impl<'s> TryFrom<&'s Message> for NameOwnerChangedArgs<'s>
impl<'s> TryFrom<&'s Message> for NameOwnerChangedArgs<'s>
source§impl<'s> TryFrom<&'s Message> for NameOwnerChangedArgs<'s>
impl<'s> TryFrom<&'s Message> for NameOwnerChangedArgs<'s>
source§impl<'s> TryFrom<&'s Message> for PropertiesChangedArgs<'s>
impl<'s> TryFrom<&'s Message> for PropertiesChangedArgs<'s>
Auto Trait Implementations§
impl !Freeze for Message
impl RefUnwindSafe for Message
impl Send for Message
impl Sync for Message
impl Unpin for Message
impl UnwindSafe for Message
Blanket Implementations§
source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
source§impl<T> CloneToUninit for Twhere
T: Clone,
impl<T> CloneToUninit for Twhere
T: Clone,
source§unsafe fn clone_to_uninit(&self, dst: *mut T)
unsafe fn clone_to_uninit(&self, dst: *mut T)
clone_to_uninit
)