Struct zbus::Message

source ·
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

source

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.

source

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.

source

pub fn method_reply<'s, S, B>( sender: Option<S>, call: &Self, body: &B, ) -> Result<Self>

Create a message of type MessageType::MethodReturn.

source

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.

source

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.

source

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.

source

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.

source

pub fn primary_header(&self) -> &MessagePrimaryHeader

source

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

Deserialize the header.

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

source

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

Deserialize the fields.

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

source

pub fn message_type(&self) -> MessageType

The message type.

source

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

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

source

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

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

source

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

The member, either the method name or signal name.

source

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

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

source

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

Deserialize the body (without checking signature matching).

source

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

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

Get a reference to the byte encoding of the message.

source

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

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

source

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

source§

fn as_ref(&self) -> &Message

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

impl AsRef<Message> for InterfacesAdded

source§

fn as_ref(&self) -> &Message

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

impl AsRef<Message> for InterfacesRemoved

source§

fn as_ref(&self) -> &Message

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

impl AsRef<Message> for InterfacesRemoved

source§

fn as_ref(&self) -> &Message

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

impl AsRef<Message> for NameAcquired

source§

fn as_ref(&self) -> &Message

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

impl AsRef<Message> for NameAcquired

source§

fn as_ref(&self) -> &Message

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

impl AsRef<Message> for NameLost

source§

fn as_ref(&self) -> &Message

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

impl AsRef<Message> for NameLost

source§

fn as_ref(&self) -> &Message

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

impl AsRef<Message> for NameOwnerChanged

source§

fn as_ref(&self) -> &Message

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

impl AsRef<Message> for NameOwnerChanged

source§

fn as_ref(&self) -> &Message

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

impl AsRef<Message> for PropertiesChanged

source§

fn as_ref(&self) -> &Message

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

impl AsRef<Message> for PropertiesChanged

source§

fn as_ref(&self) -> &Message

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

impl Clone for Message

source§

fn clone(&self) -> Message

Returns a copy of the value. Read more
1.0.0 · source§

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

Performs copy-assignment from source. Read more
source§

impl Debug for Message

source§

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

Formats the value using the given formatter. Read more
source§

impl Display for Message

source§

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

Formats the value using the given formatter. Read more
source§

impl From<Message> for Error

source§

fn from(message: Message) -> Error

Converts to this type from the input type.
source§

impl<'s> TryFrom<&'s Message> for InterfacesAddedArgs<'s>

source§

type Error = Error

The type returned in the event of a conversion error.
source§

fn try_from(message: &'s Message) -> Result<Self>

Performs the conversion.
source§

impl<'s> TryFrom<&'s Message> for InterfacesAddedArgs<'s>

source§

type Error = Error

The type returned in the event of a conversion error.
source§

fn try_from(message: &'s Message) -> Result<Self>

Performs the conversion.
source§

impl<'s> TryFrom<&'s Message> for InterfacesRemovedArgs<'s>

source§

type Error = Error

The type returned in the event of a conversion error.
source§

fn try_from(message: &'s Message) -> Result<Self>

Performs the conversion.
source§

impl<'s> TryFrom<&'s Message> for InterfacesRemovedArgs<'s>

source§

type Error = Error

The type returned in the event of a conversion error.
source§

fn try_from(message: &'s Message) -> Result<Self>

Performs the conversion.
source§

impl<'s> TryFrom<&'s Message> for NameAcquiredArgs<'s>

source§

type Error = Error

The type returned in the event of a conversion error.
source§

fn try_from(message: &'s Message) -> Result<Self>

Performs the conversion.
source§

impl<'s> TryFrom<&'s Message> for NameAcquiredArgs<'s>

source§

type Error = Error

The type returned in the event of a conversion error.
source§

fn try_from(message: &'s Message) -> Result<Self>

Performs the conversion.
source§

impl<'s> TryFrom<&'s Message> for NameLostArgs<'s>

source§

type Error = Error

The type returned in the event of a conversion error.
source§

fn try_from(message: &'s Message) -> Result<Self>

Performs the conversion.
source§

impl<'s> TryFrom<&'s Message> for NameLostArgs<'s>

source§

type Error = Error

The type returned in the event of a conversion error.
source§

fn try_from(message: &'s Message) -> Result<Self>

Performs the conversion.
source§

impl<'s> TryFrom<&'s Message> for NameOwnerChangedArgs<'s>

source§

type Error = Error

The type returned in the event of a conversion error.
source§

fn try_from(message: &'s Message) -> Result<Self>

Performs the conversion.
source§

impl<'s> TryFrom<&'s Message> for NameOwnerChangedArgs<'s>

source§

type Error = Error

The type returned in the event of a conversion error.
source§

fn try_from(message: &'s Message) -> Result<Self>

Performs the conversion.
source§

impl<'s> TryFrom<&'s Message> for PropertiesChangedArgs<'s>

source§

type Error = Error

The type returned in the event of a conversion error.
source§

fn try_from(message: &'s Message) -> Result<Self>

Performs the conversion.
source§

impl<'s> TryFrom<&'s Message> for PropertiesChangedArgs<'s>

source§

type Error = Error

The type returned in the event of a conversion error.
source§

fn try_from(message: &'s Message) -> Result<Self>

Performs the conversion.

Auto Trait Implementations§

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> CloneToUninit for T
where T: Clone,

source§

unsafe fn clone_to_uninit(&self, dst: *mut T)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dst. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T> Instrument for T

source§

fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
source§

fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T> Same for T

source§

type Output = T

Should always be Self
source§

impl<T> ToOwned for T
where T: Clone,

source§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
source§

impl<T> ToString for T
where T: Display + ?Sized,

source§

default fn to_string(&self) -> String

Converts the given value to a String. Read more
source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

source§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
source§

impl<V, T> VZip<V> for T
where V: MultiLane<T>,

source§

fn vzip(self) -> V

source§

impl<T> WithSubscriber for T

source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
source§

fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more