@spec introspectable() :: t()

The standard org.freedesktop.DBus.Introspectable interface.

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

Builds an interface declaration, validating every name, signature and annotation.

Names follow the D-Bus grammar: the interface name is checked as an interface name, and method, signal, property and argument names as member names. Annotation names follow the interface-name grammar, and annotation values must be strings that XML can carry. Duplicate methods, signals, properties or annotations are rejected, as is a no-reply method with a Unix file descriptor (h) among its out arguments.

Examples

iex> {:ok, interface} =
...>   Rebus.Interface.new("org.example.Calculator",
...>     methods: [{"Add", in: [a: "i", b: "i"], out: [sum: "i"]}]
...>   )
iex> interface.methods["Add"].in_signature
"ii"

iex> Rebus.Interface.new("Calculator")
{:error, {:invalid_interface_name, "Calculator"}}

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

Builds an interface declaration, raising ArgumentError when it is invalid.

@spec object_manager() :: t()

The standard org.freedesktop.DBus.ObjectManager interface.

@spec peer() :: t()

The standard org.freedesktop.DBus.Peer interface.

@spec properties() :: t()

The standard org.freedesktop.DBus.Properties interface.

@spec properties_changed(
  t(),
  binary(),
  %{required(binary()) => term()},
  [binary()],
  keyword()
) ::
  {:ok, Rebus.Message.t()}
  | {:error,
     property_error()
     | {:invalid_property_change, binary()}
     | {:invalid_option, term()}
     | Rebus.Message.construction_error()}

Builds an org.freedesktop.DBus.Properties.PropertiesChanged signal for properties declared by interface.

changed maps property names to their new values, which are typed by the declaration. invalidated names properties that changed without their values. Each property's emits_changed decides where it may appear: one that emits true only in changed, one that emits :invalidates only in invalidated, and one that emits false or :const in neither.

opts takes :destination, :flags and :fds, as signal/5 does, so a value of a property declared with a Unix file descriptor type can refer to a descriptor.

Returns {:error, {:unknown_property, name}} for a property the interface does not declare, {:error, {:invalid_property_change, name}} for one whose declaration does not allow it where it appears, and Rebus.Message.new/2's errors otherwise.

@spec signal(t(), binary(), binary(), [term()], keyword()) ::
  {:ok, Rebus.Message.t()}
  | {:error,
     :unknown_signal
     | {:invalid_option, term()}
     | Rebus.Message.construction_error()}

Builds a signal message for a signal declared by interface, typed by its declaration.

opts takes :destination, :flags and :fds, as Rebus.Message.new/2 does. Returns {:error, :unknown_signal} when the interface does not declare member, and Rebus.Message.new/2's errors otherwise; a body that does not fit the declared signature is {:error, :invalid_body}.

Example

iex> interface =
...>   Rebus.Interface.new!("org.example.Calculator",
...>     signals: [{"Computed", args: [sum: "i"]}]
...>   )
iex> {:ok, message} =
...>   Rebus.Interface.signal(interface, "/org/example/Calc", "Computed", [42])
iex> Rebus.Message.signature(message)
"i"

@spec wrap_properties(t(), %{required(binary()) => term()}) ::
  {:ok, [{binary(), {binary(), term()}}]} | {:error, property_error()}

Wraps property values as the a{sv} body element that GetAll replies and PropertiesChanged signals carry, typing each value by its declaration.

Entries are sorted by property name. Values are not checked against their signatures here; the message they are placed in reports one that does not fit as :invalid_body.

Example

iex> interface =
...>   Rebus.Interface.new!("org.example.Calculator",
...>     properties: [{"Precision", "u", :readwrite}, {"Version", "s", :read}]
...>   )
iex> Rebus.Interface.wrap_properties(interface, %{"Version" => "1.0", "Precision" => 3})
{:ok, [{"Precision", {"u", 3}}, {"Version", {"s", "1.0"}}]}

@spec wrap_properties!(t(), %{required(binary()) => term()}) :: [
  {binary(), {binary(), term()}}
]

Wraps property values as wrap_properties/2 does, raising ArgumentError for a property the interface does not declare.