Rebus.MatchRule (rebus v0.4.0)

View Source

A validated, canonical D-Bus signal match rule.

Build rules with new/1 and pass them to Rebus.add_match/3. Rebus takes structured criteria rather than raw rule strings, so every rule it sends is bounded and correctly quoted, and can also be evaluated locally when several subscriptions share a connection.

The generated rule always contains type='signal'. The criteria are :sender, :interface, :member, :path, :path_namespace, :destination, :args, :arg_paths and :arg0namespace. :path and :path_namespace cannot be combined. :args and :arg_paths are maps or keyword lists keyed by argument index, 0 through 63.

eavesdrop is not accepted. Sender matching is split between the bus and Rebus, as Signal subscriptions and match rules describes.

Summary

Types

criteria()
t()
validation_error()

Functions

matches?(rule, message)

Returns whether a signal matches the parts of the rule that can be checked locally, after the bus has routed it.

new(opts)

Builds a signal match rule from the criteria in opts.

new!(opts)

Builds a match rule, raising ArgumentError when it is invalid.

to_string(match_rule)

Returns the rule as the string sent to the bus in AddMatch and RemoveMatch.

Types

criteria()

@type criteria() :: %{
  optional(:sender) => binary(),
  optional(:interface) => binary(),
  optional(:member) => binary(),
  optional(:path) => binary(),
  optional(:path_namespace) => binary(),
  optional(:destination) => binary(),
  optional(:args) => %{required(non_neg_integer()) => binary()},
  optional(:arg_paths) => %{required(non_neg_integer()) => binary()},
  optional(:arg0namespace) => binary()
}

t()

@type t() :: %Rebus.MatchRule{criteria: criteria(), string: binary()}

validation_error()

@type validation_error() ::
  :duplicate_match_option
  | :invalid_match_rule
  | :invalid_match_option
  | :invalid_match_value
  | :invalid_match_argument
  | :conflicting_match_paths
  | :match_rule_too_long

Functions

matches?(rule, message)

@spec matches?(t(), Rebus.Message.t()) :: boolean()

Returns whether a signal matches the parts of the rule that can be checked locally, after the bus has routed it.

Every criterion is compared except a well-known :sender, which is left to the bus for broadcast signals; a directed signal matches such a sender only when its sender header is that exact name. The connection adds ownership tracking for subscribed signals on top of this. Bus access policy and eavesdropping are not emulated.

new(opts)

@spec new(keyword()) :: {:ok, t()} | {:error, validation_error()}

Builds a signal match rule from the criteria in opts.

The encoded rule is limited to 1024 bytes, the reference D-Bus implementation's limit. Invalid input returns a fixed atom that never includes the caller's text.

Examples

iex> {:ok, rule} = Rebus.MatchRule.new(
...>   sender: "org.freedesktop.DBus",
...>   member: "NameOwnerChanged"
...> )
iex> Rebus.MatchRule.to_string(rule)
"type='signal',sender='org.freedesktop.DBus',member='NameOwnerChanged'"

new!(opts)

@spec new!(keyword()) :: t()

Builds a match rule, raising ArgumentError when it is invalid.

to_string(match_rule)

@spec to_string(t()) :: binary()

Returns the rule as the string sent to the bus in AddMatch and RemoveMatch.