Module dbus_proxy

Simple API around GLib's GIO:GDBusProxy built on top of lgi.

Info:

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

_proxy Functions

Proxy A proxy object

Proxy objects act as intermediares between your lua code and DBus.
Proxy:connect_signal (callback, signal_name[, sender_name]) Connect a callback function to a signal.
Proxy:on_properties_changed (callback) Call a function when the properties of the proxy object change.
Proxy:new (opts) Create a new proxy object

_bus Functions

Bus Available connections to the DBus daemon.

_variant Functions

variant.strip (v) Strip an lgi.GLib.VariantType object of its types

_monitored Functions

monitored.new (opts) Create a monitored proxy object from the given options.


_proxy Functions

Proxy

A proxy object

Proxy objects act as intermediares between your lua code and DBus. All the properties, methods and signals of the object are exposed. Be aware that properties, methods and signals will likely be written in CamelCase since this it the convention in DBus (e.g. proxy.SomeProperty or proxy:SomeMethod()). Please refer to the documentation of the object you are proxying for more information.

When a property in a DBus object changes, the same change is reflected in the proxy. Similarly, when a signal is emitted, the proxy object is notified accordingly.

Additionally, the following fields reflect the corresponding g-* properties:

  • connection: g-connection
  • flags: g-flags
  • interface: g-interface-name
  • name: g-name
  • name_owner: g-name-owner
  • object_path: g-object-path

For all this to work though, the code must run inside GLib's main event loop. This can be achieved in two ways:

  1. Create a main loop and run it when the application starts:

       local GLib = require("lgi").GLib
   -- Set up the application, then do:
   local main_loop = GLib.MainLoop()
   main_loop:run()
   -- use main_loop:quit() to stop the main loop.

  2. Use more fine-grained control by running an iteration at a time from the main context; this is particularly useful when you want to integrate your code with an external main loop:

      local GLib = require("lgi").GLib
  -- Set up the code, then do
  local ctx = GLib.MainLoop():get_context()
  -- Run a single non-blocking iteration
  if ctx:iteration() == true then
    print("something changed!")
  end
  -- Run a single blocking iteration
  if ctx:iteration(true) == true then
    print("something changed here too!")
  end

Usage:

    p = require("dbus_proxy")
proxy = p.Proxy:new(
                      {
                        bus = p.Bus.SYSTEM,
                        name = "com.example.BusName",
                        interface = "com.example.InterfaceName",
                        path = "/com/example/objectPath"
                      }
                    )
proxy:SomeMethod()
proxy:SomeMethodWithArguments("hello", 123)
proxy.SomeProperty
Proxy:connect_signal (callback, signal_name[, sender_name])
Connect a callback function to a signal.

Parameters:

  • callback function a callback function to be called. The proxy object itself and the parameters from the signal as (simple lua types) will be passed to the callback when the signal is emitted
  • signal_name string the name of the signal
  • sender_name string the name of the sender. This may have the form of a well known name (e.g. "org.freedesktop.DBus") or a specific connection name ( e.g. ":1.113"). See also the Bus Names section of the DBus tutorial. If specified, only signals from this sender will be taken into account. (optional)

Usage:

    proxy:connect_signal(
  function (p, x, y)
    assert(p == proxy)
    print("SomeSignalName emitted with params: ", x, y)
  end,
  "SomeSignalName"
)
Proxy:on_properties_changed (callback)
Call a function when the properties of the proxy object change.

Parameters:

  • callback function a function that will be called when the properties change. The callback will receive the proxy object itself and two tables: changed_properties (a table where the keys are the properties that changed and the values the new values) and invalidated_properties (an array containg the names of the invalidated properties). Either may be empty. The local cache has already been updated when the signal is emitted, so the properties on the object will be up-to-date

Usage:

    proxy:on_properties_changed(function (p, changed, invalidated)
    assert(p == proxy)
    print("******")
    print("changed properties:")
    for k, v in pairs(changed) do
      print("name", k, "ne value", v)
    end
    print("invalidated properties")
    for _, v in ipairs(invalidated) do
      print("name", v)
    end
    print("******")
end)
Proxy:new (opts)
Create a new proxy object

Parameters:

  • opts table

    table that specifies what DBus object should be proxied. The opts table should have the following fields:

    • bus: a DBus connection from the Bus table
    • interface: a (string) representing the interface name
    • name: a (string) representing the Bus name
    • path: a (string) representing the object path
    • flags: one of the lgi.Gio.DBusProxyFlags; defaults to lgi.Gio.DBusProxyFlags.NONE (optional)

Returns:

    a new proxy object

_bus Functions

Bus
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 an invalid address is passed, its value will be nil.

Usage:

    Bus = require("dbus_proxy").Bus
system_bus = Bus.SYSTEM
session_bus = Bus.SESSION

-- This is a string that looks like
-- "unix:path=/run/user/1000/bus"
address = os.getenv("DBUS_SESSION_BUS_ADDRESS")

bus = Bus[address]
assert("Gio.DBusConnection" == bus._name)

invalid1 = Bus["something really wrong"]
assert(nil == invalid1)

invalid2 = Bus.this_will_not_work
assert(nil == invalid2)

_variant Functions

variant.strip (v)
Strip an lgi.GLib.VariantType object of its types

Parameters:

  • v lgi.GLib.VariantType an lgi.GLib.VariantType object

Returns:

    simple lua data (nested structures will be stripped too). The C to lua type correspondence is straightforward:

    • numeric types will be returned as lua numbers
    • booleans are preserved
    • string are preserved,
    • object paths (e.g. /org/freedesktop/DBus) will be returned as strings too
    • arrays (homogeneous types, signature a) and tuples (mixed types, signature ()) will be returned as lua arrays
    • dictionaries (signature {}) will be returned as lua tables

Usage:

    GVariant = require("lgi").GLib.VariantType

-- strip a nested variant
v1 = GVariant("v", GVariant("s", "in a variant"))
stripped1 = variant.strip(v1)
-- "in a variant"

-- strip a dictionary of variants
v2 = GVariant("a{sv}", {one = GVariant("i", 123),
                              two = GVariant("s", "Lua!")})
stripped2 = variant.strip(v2)
-- {one = 123, two = "Lua!"}

-- strip a nested array
v3 = GVariant("aai", {{1, 2, 3}, {4, 1, 2, 3}})
stripped3 = variant.strip(v3)
-- {{1, 2, 3}, {4, 1, 2, 3}, n=2}

_monitored Functions

monitored.new (opts)
Create a monitored proxy object from the given options.

This function creates a monitored Proxy object that can come "live" as soon as the referenced DBus name is available.

When the name is available (i.e. connected), the object will have the exact same behavior as a normal Proxy object.

When the name is not available, the object will raise an error when trying to access properties or call methods of the Proxy object with the exception of the name property.

Parameters:

  • opts table options that specify the DBus object to be proxied. In addition to the fields documented in Proxy:new, the optional watcher_flags can be set to either lgi.Gio.BusNameWatcherFlags.NONE (the default) or lgi.Gio.BusNameWatcherFlags.AUTO_START. The latter will ask the bus to launch an owner for the name if there is no owner when beginning to watch the name (see also the GBusNameWatcherFlags documentation on the GNOME website)

Returns:

    a Proxy object with extra properties:

    • is_connected a boolean property that indicates whether the monitored proxy is actually connected. It can be checked before calling methods or accessing other properties on the object to avoid errors.

See also:

generated by LDoc 1.4.6 Last updated 2017-10-23 22:23:59