ldbus_api

Contents

• Functions
• Tables

Modules

• ldbus_api

Topics

• README

Module ldbus_api

A high level DBus API for Lua built on top of the ldbus library.

Adds the ldbus.api and ldbus.buses tables to ldbus.

Info:

• Copyright: 2016 Stefano Mazzucco
• License: Apache License, version 2.0
• Author: Stefano Mazzucco

Functions

ldbus.api.from_iter (iter)	Return a table representing DBus data from a DBus iterable.
ldbus.api.from_message (message)	Return an array of tables representing DBus data from a DBus message, or nil.
ldbus.api.parse_signature (sig)	Parse a string representing a DBus signature.
ldbus.api.call (opts)	Call a DBus method on a given interface blocking execution.
ldbus.api.call_async (opts)	Call a method on a DBus interface asynchrounously.
ldbus.api.get_async_response (pending)	Forcefully get a response from a pending DBus call.
ldbus.api.send_signal (opts)	Send a signal.
ldbus.api.watch (bus, filter)	Watch a bus for messages matching a filter.
ldbus.api.serve (bus, destination, callbacks)	Serve a an interface on the given bus.
ldbus.api.get_value (dbus_data)	Get the value from DBus data
ldbus.api.examples.echo (msg, conn)	Callback that sends back whatever it receives.

Tables

ldbus.buses

Available connections to the DBus daemon.

Functions

ldbus.api.from_iter (iter)

Return a table representing DBus data from a DBus iterable.

Parameters:

• iter A DBus iterable obtained from ldbus.

Returns:

A table with 'sig' and 'value' fields representing DBus data.

See also:

from_message

ldbus.api.from_message (message)

Return an array of tables representing DBus data from a DBus message, or nil.

Parameters:

• message A DBus message obtained from ldbus.

Returns:

1. An array of tables with 'sig' and 'value' fields representing DBus data.
2. nil If the message is empty

See also:

from_iter

ldbus.api.parse_signature (sig)

Parse a string representing a DBus signature. The returned values can be passed to parse_signature again for further refinement.

Parameters:

• sig A string representing a DBus signature.

Returns:

An array of strings representing the components of the signature.

ldbus.api.call (opts)

Call a DBus method on a given interface blocking execution.

Parameters:

• opts A table defining the options to be passed.

  opts must contain the following fields:

  > bus: The bus name ("session" or "system") or a valid > DBus address > as a string.

  > dest: The destination as a string.

  > path: The object path as a string.

  > interface: The interface name as a string.

  > method: The method to be called as a string.

  > args: The arguments to be passed to the method as an array of DBus data.

  The following field is optional:

  > timeout: The timeout in seconds as a number after which the blocking call will fail.

Returns:

A table representing the DBus data.

See also:

• call_async
• from_message

ldbus.api.call_async (opts)

Call a method on a DBus interface asynchrounously.

Parameters:

• opts A table defining the options to be passed.

Returns:

An UserData object representing a pending DBus call

See also:

call

ldbus.api.get_async_response (pending)

Forcefully get a response from a pending DBus call. This is a blocking call that may never return!

Parameters:

• pending An UserData object representing a pending DBus call

Returns:

A table representing the DBus data.

See also:

• from_message
• call_async

ldbus.api.send_signal (opts)

Send a signal.

Parameters:

• opts A table defining the options to be passed.

  opts must contain the following fields:

  > bus: The bus name ("session" or "system") or a valid > DBus address > as a string.

  > path: The object path as a string.

  > interface: The interface name as a string.

  > signal: The signal to be sent as a string.

  > args: The arguments to be passed to the method as an array of DBus data.

  The following field is optional as signals usually do not need a destination:

  > dest: The destination as a string.

Returns:

Whether the signal was sent or not (true or false/nil).

ldbus.api.watch (bus, filter)

Watch a bus for messages matching a filter.

Parameters:

• bus The bus name ("session" or "system") or a valid DBus address as a string.
• filter A string that conforms to the DBus match rules. For example:

  filter="type=signal,sender=org.freedesktop.DBus,\ interface=org.freedesktop.DBus,\ member=Foo,path=/bar/foo"

Returns:

A function (that wraps a coroutine) that can be called with no arguments and the DBus connection returned by the DBus daemon. The function call will return the DBus data table that matches the filter, or "no_answer" if nothing has been received yet. If the connection is closed, the function will return "connection_closed".

Note:

• ldbus.bus.add_match is used internally for the session and system buses only.
• all messages that specify the current connection as its destination will be matched regardless of the filter.
• each call to watch within the same process will append a match rule to the same connection. E.g. when one calls watch("session", "type=signal") and then they call watch("session", "member=SomeMethod"), the function returned by the second call will also match the messages from first filter! This is due to the fact that DBus returns one unique connection per process. You can still use the connection returned to remove the previous filter, e.g. w, c = watch("session", "member=SomeMethod") and then ldbus.bus.remove_match(c, "type=signal). That would of course break the first call though.

ldbus.api.serve (bus, destination, callbacks)

Serve a an interface on the given bus.

Parameters:

• bus The bus name ("session" or "system") or a valid DBus address as a string.
• destination The destination interface.
• callbacks An array of functions that will be called when the interface receives a method call.

  Each callback will be passed a DBus message and a DBus connection and it should return two parameters: status and serial that should be compatible to what ldbus uses in connection:send. In particular, if status is nil it means that the request has not been processed yet. If a callback errors, the {false, <ERROR MESSAGE>} pair is returned istead.

Returns:

A function that accepts no arguments (and wraps a coroutine). Each time the function is called, it will return an array of the status and serial from the callback or the pair "connection_closed", nil if the connection is closed.

See also:

ldbus.api.examples.echo

ldbus.api.get_value (dbus_data)

Get the value from DBus data

Parameters:

• dbus_data A table representing DBus data (i.e. has a key called 'value') or a basic Lua type (number, string, etc.)

Returns:

The value of the DBus data with its signature stripped

ldbus.api.examples.echo (msg, conn)

Callback that sends back whatever it receives.

Parameters:

• msg An ldbus DBus message
• conn An ldbus DBus connection

Returns:

The status, serial pair returned by ldbus connection:send

See also:

serve

Tables

ldbus.buses

Available connections to the DBus daemon. Fields on this table can only be accessed. Trying to set fields will result in an error.

Fields:

• session Connection to the session bus for this process
• system Connection to the system bus for this process
• any_valid_dbus_address Connection to the DBus address. If a connection cannot be established, an error will be raised.