pub struct MatchRule<'m> { /* private fields */ }Expand description
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")?
.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'",
);
// 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§
source§impl<'m> MatchRule<'m>
impl<'m> MatchRule<'m>
sourcepub fn builder() -> MatchRuleBuilder<'m>
pub fn builder() -> MatchRuleBuilder<'m>
Create a builder for MatchRuleBuilder.
sourcepub fn msg_type(&self) -> Option<MessageType>
pub fn msg_type(&self) -> Option<MessageType>
The message type, if set.
sourcepub fn interface(&self) -> Option<&InterfaceName<'_>>
pub fn interface(&self) -> Option<&InterfaceName<'_>>
The interfac, if set.
sourcepub fn member(&self) -> Option<&MemberName<'_>>
pub fn member(&self) -> Option<&MemberName<'_>>
The member name if set.
sourcepub fn path_spec(&self) -> Option<&MatchRulePathSpec<'_>>
pub fn path_spec(&self) -> Option<&MatchRulePathSpec<'_>>
The path or path namespace, if set.
sourcepub fn destination(&self) -> Option<&UniqueName<'_>>
pub fn destination(&self) -> Option<&UniqueName<'_>>
The destination, if set.
sourcepub fn arg_paths(&self) -> &[(u8, ObjectPath<'_>)]
pub fn arg_paths(&self) -> &[(u8, ObjectPath<'_>)]
The argument paths.
sourcepub fn arg0namespace(&self) -> Option<&InterfaceName<'_>>
pub fn arg0namespace(&self) -> Option<&InterfaceName<'_>>
Match messages whose first argument is within the specified namespace.
Note that while the spec allows this to be any string that’s a valid bus or interface name
except that it can have no ., we only allow valid interface names. The reason is not only
to keep things simple and type safe at the same time but also for the fact that use cases of
only matching on the first component of a bus or interface name are unheard of.
sourcepub fn into_owned(self) -> MatchRule<'static>
pub fn into_owned(self) -> MatchRule<'static>
Creates an owned clone of self.
sourcepub fn matches(&self, msg: &Message) -> Result<bool>
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:
senderin the rule (if set) that is a well-known name. Thesenderon a message is always a unique name.destinationin the rule whendestinationon themsgis a well-known name. Thedestinationon match rule is always a unique name.