Struct MatchRule

pub struct MatchRule<'m> { /* private fields */ }

A bus match rule for subscribing to specific messages.

This is mainly used by peer to subscribe to specific signals as by default the bus will not send out most broadcasted signals. This API is intended to make it easy to create and parse match rules. See the match rules section of the D-Bus specification for a description of each possible element of a match rule.

Examples

use std::convert::TryFrom;

// Let's take the most typical example of match rule to subscribe to properties' changes:
let rule = MatchRule::builder()
    .msg_type(zbus::MessageType::Signal)
    .sender("org.freedesktop.DBus")?
    .interface("org.freedesktop.DBus.Properties")?
    .member("PropertiesChanged")?
    .add_arg("org.zbus")?
    // Sometimes it's useful to match empty strings (null check).
    .add_arg("")?
    .build();
let rule_str = rule.to_string();
assert_eq!(
    rule_str,
    "type='signal',\
     sender='org.freedesktop.DBus',\
     interface='org.freedesktop.DBus.Properties',\
     member='PropertiesChanged',\
     arg0='org.zbus',\
     arg1=''",
);

// Let's parse it back.
let parsed_rule = MatchRule::try_from(rule_str.as_str())?;
assert_eq!(rule, parsed_rule);

// Now for `ObjectManager::InterfacesAdded` signal.
let rule = MatchRule::builder()
    .msg_type(zbus::MessageType::Signal)
    .sender("org.zbus")?
    .interface("org.freedesktop.DBus.ObjectManager")?
    .member("InterfacesAdded")?
    .arg_path(0, "/org/zbus/NewPath")?
    .build();
let rule_str = rule.to_string();
assert_eq!(
    rule_str,
    "type='signal',\
     sender='org.zbus',\
     interface='org.freedesktop.DBus.ObjectManager',\
     member='InterfacesAdded',\
     arg0path='/org/zbus/NewPath'",
);

// Let's parse it back.
let parsed_rule = MatchRule::try_from(rule_str.as_str())?;
assert_eq!(rule, parsed_rule);

Caveats

The PartialEq implementation assumes arguments in both rules are in the same order.

Implementations

impl<'m> MatchRule<'m>

pub fn builder() -> MatchRuleBuilder<'m>

Create a builder for MatchRuleBuilder.

pub fn sender(&self) -> Option<&BusName<'_>>

The sender, if set.

pub fn msg_type(&self) -> Option<MessageType>

The message type, if set.

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

The interfac, if set.

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

The member name if set.

pub fn path_spec(&self) -> Option<&MatchRulePathSpec<'_>>

The path or path namespace, if set.

pub fn destination(&self) -> Option<&UniqueName<'_>>

The destination, if set.

pub fn args(&self) -> &[(u8, Str<'_>)]

The arguments.

pub fn arg_paths(&self) -> &[(u8, ObjectPath<'_>)]

The argument paths.

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

👎Deprecated: use arg0ns instead

Match messages whose first argument is within the specified namespace.

This function is deprecated because the choice of InterfaceName was too restrictive.

pub fn arg0ns(&self) -> Option<&Str<'m>>

Match messages whose first argument is within the specified namespace.

pub fn to_owned(&self) -> MatchRule<'static>

Creates an owned clone of self.

pub fn into_owned(self) -> MatchRule<'static>

Creates an owned clone of self.

pub fn matches(&self, msg: &Message) -> Result<bool>

Match the given message against this rule.

Caveats

Since this method doesn’t have any knowledge of names on the bus (or even connection to a bus) matching always succeeds for:

• sender in the rule (if set) that is a well-known name. The sender on a message is always a unique name.
• destination in the rule when destination on the msg is a well-known name. The destination on match rule is always a unique name.

Trait Implementations

impl<'m> Clone for MatchRule<'m>

fn clone(&self) -> MatchRule<'m>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<'m> Debug for MatchRule<'m>

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

Formats the value using the given formatter.

impl<'de: 'm, 'm> Deserialize<'de> for MatchRule<'m>

fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>

where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for MatchRule<'_>

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

Formats the value using the given formatter.

impl<'unowned, 'owned: 'unowned> From<&'owned OwnedMatchRule> for MatchRule<'unowned>

fn from(rule: &'owned OwnedMatchRule) -> Self

Converts to this type from the input type.

impl From<MatchRule<'_>> for OwnedMatchRule

fn from(rule: MatchRule<'_>) -> Self

Converts to this type from the input type.

impl From<OwnedMatchRule> for MatchRule<'static>

fn from(o: OwnedMatchRule) -> Self

Converts to this type from the input type.

impl<'m> Hash for MatchRule<'m>

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq<MatchRule<'_>> for OwnedMatchRule

fn eq(&self, other: &MatchRule<'_>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<'m> PartialEq for MatchRule<'m>

fn eq(&self, other: &MatchRule<'m>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Serialize for MatchRule<'_>

fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>

where S: Serializer,

Serialize this value into the given Serde serializer.

impl<'m> TryFrom<&'m str> for MatchRule<'m>

type Error = Error

The type returned in the event of a conversion error.

fn try_from(s: &'m str) -> Result<Self>

Performs the conversion.

impl<'m> Type for MatchRule<'m>

fn signature() -> Signature<'static>

Get the signature for the implementing type.

impl<'m> Eq for MatchRule<'m>

impl<'m> StructuralPartialEq for MatchRule<'m>