Struct zbus::Message

pub struct Message { /* private fields */ }

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

impl Message

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> where
    S: TryInto<UniqueName<'s>>,
    D: TryInto<BusName<'d>>,
    P: TryInto<ObjectPath<'p>>,
    I: TryInto<InterfaceName<'i>>,
    M: TryInto<MemberName<'m>>,
    S::Error: Into<Error>,
    D::Error: Into<Error>,
    P::Error: Into<Error>,
    I::Error: Into<Error>,
    M::Error: Into<Error>,
    B: Serialize + DynamicType, 

Create a message of type MessageType::MethodCall.

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> where
    S: TryInto<UniqueName<'s>>,
    D: TryInto<BusName<'d>>,
    P: TryInto<ObjectPath<'p>>,
    I: TryInto<InterfaceName<'i>>,
    M: TryInto<MemberName<'m>>,
    S::Error: Into<Error>,
    D::Error: Into<Error>,
    P::Error: Into<Error>,
    I::Error: Into<Error>,
    M::Error: Into<Error>,
    B: Serialize + DynamicType, 

Create a message of type MessageType::Signal.

pub fn method_reply<'s, S, B>(
    sender: Option<S>,
    call: &Self,
    body: &B
) -> Result<Self> where
    S: TryInto<UniqueName<'s>>,
    S::Error: Into<Error>,
    B: Serialize + DynamicType, 

Create a message of type MessageType::MethodReturn.

pub fn method_error<'s, 'e, S, E, B>(
    sender: Option<S>,
    call: &Self,
    name: E,
    body: &B
) -> Result<Self> where
    S: TryInto<UniqueName<'s>>,
    S::Error: Into<Error>,
    E: TryInto<ErrorName<'e>>,
    E::Error: Into<Error>,
    B: Serialize + DynamicType, 

Create a message of type MessageType::MethodError.

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.

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

pub fn header(&self) -> Result<MessageHeader<'_>>

Deserialize the header.

Note: prefer using the direct access methods if possible; they are more efficient.

pub fn fields(&self) -> Result<MessageFields<'_>>

Deserialize the fields.

Note: prefer using the direct access methods if possible; they are more efficient.

pub fn message_type(&self) -> MessageType

The message type.

pub fn path(&self) -> Option<ObjectPath<'_>>

The object to send a call to, or the object a signal is emitted from.

pub fn interface(&self) -> Option<InterfaceName<'_>>

The interface to invoke a method call on, or that a signal is emitted from.

pub fn member(&self) -> Option<MemberName<'_>>

The member, either the method name or signal name.

pub fn reply_serial(&self) -> Option<u32>

The serial number of the message this message is a reply to.

pub fn body_unchecked<'d, 'm: 'd, B>(&'m self) -> Result<B> where
    B: Deserialize<'d> + Type, 

Deserialize the body (without checking signature matching).

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 : 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);

pub fn as_bytes(&self) -> &[u8]

Get a reference to the byte encoding of the message.

pub fn body_as_bytes(&self) -> Result<&[u8]>

Get a reference to the byte encoding of the body of the message.

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

impl AsRef<Message> for PropertiesChanged

fn as_ref(&self) -> &Message

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<Message> for InterfacesAdded

fn as_ref(&self) -> &Message

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<Message> for NameLost

fn as_ref(&self) -> &Message

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<Message> for NameAcquired

fn as_ref(&self) -> &Message

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<Message> for InterfacesRemoved

fn as_ref(&self) -> &Message

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<Message> for NameOwnerChanged

fn as_ref(&self) -> &Message

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<Message> for NameLost

fn as_ref(&self) -> &Message

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<Message> for NameAcquired

fn as_ref(&self) -> &Message

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<Message> for PropertiesChanged

fn as_ref(&self) -> &Message

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<Message> for InterfacesAdded

fn as_ref(&self) -> &Message

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<Message> for InterfacesRemoved

fn as_ref(&self) -> &Message

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<Message> for NameOwnerChanged

fn as_ref(&self) -> &Message

Converts this type into a shared reference of the (usually inferred) input type.

impl Clone for Message

fn clone(&self) -> Message

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Message

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for Message

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl From<Message> for Error

fn from(message: Message) -> Error

Converts to this type from the input type.

impl Sink<Message> for Connection

type Error = Error

The type of value produced by the sink when an error occurs.

fn poll_ready(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<()>>

Attempts to prepare the Sink to receive a value.

fn start_send(self: Pin<&mut Self>, msg: Message) -> Result<()>

Begin the process of sending a value to the sink. Each call to this function must be preceded by a successful call to poll_ready which returned Poll::Ready(Ok(())).

fn poll_flush(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<()>>

Flush any remaining output from this sink.

fn poll_close(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<()>>

Flush any remaining output and close this sink, if necessary.

impl<'a> Sink<Message> for &'a Connection

type Error = Error

The type of value produced by the sink when an error occurs.

fn poll_ready(self: Pin<&mut Self>, _cx: &mut Context<'_>) -> Poll<Result<()>>

Attempts to prepare the Sink to receive a value.

fn start_send(self: Pin<&mut Self>, msg: Message) -> Result<()>

Begin the process of sending a value to the sink. Each call to this function must be preceded by a successful call to poll_ready which returned Poll::Ready(Ok(())).

fn poll_flush(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<()>>

Flush any remaining output from this sink.

fn poll_close(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<()>>

Flush any remaining output and close this sink, if necessary.