{"id":13454400,"url":"https://github.com/stefano-m/lua-dbus_proxy","last_synced_at":"2025-10-03T18:31:08.250Z","repository":{"id":52669068,"uuid":"87658638","full_name":"stefano-m/lua-dbus_proxy","owner":"stefano-m","description":"Simple API around GLib's GIO:GDBusProxy built on top of lgi","archived":false,"fork":false,"pushed_at":"2024-10-04T16:38:55.000Z","size":94,"stargazers_count":17,"open_issues_count":1,"forks_count":7,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-02-02T08:32:21.717Z","etag":null,"topics":["dbus","gio","glib","lgi","lua","proxy"],"latest_commit_sha":null,"homepage":"https://stefano-m.github.io/lua-dbus_proxy/","language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/stefano-m.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-04-08T19:24:37.000Z","updated_at":"2024-10-04T16:38:59.000Z","dependencies_parsed_at":"2023-01-25T21:31:34.306Z","dependency_job_id":null,"html_url":"https://github.com/stefano-m/lua-dbus_proxy","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stefano-m%2Flua-dbus_proxy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stefano-m%2Flua-dbus_proxy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stefano-m%2Flua-dbus_proxy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stefano-m%2Flua-dbus_proxy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stefano-m","download_url":"https://codeload.github.com/stefano-m/lua-dbus_proxy/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":238968301,"owners_count":19560586,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["dbus","gio","glib","lgi","lua","proxy"],"created_at":"2024-07-31T08:00:53.751Z","updated_at":"2025-10-03T18:31:08.161Z","avatar_url":"https://github.com/stefano-m.png","language":"Lua","readme":"[![Build\nStatus](https://travis-ci.com/stefano-m/lua-dbus_proxy.svg?branch=master)](https://travis-ci.com/stefano-m/lua-dbus_proxy)\n[![codecov](https://codecov.io/gh/stefano-m/lua-dbus_proxy/branch/master/graph/badge.svg)](https://codecov.io/gh/stefano-m/lua-dbus_proxy)\n\nDBus Proxy Objects for Lua - @VERSION@\n--------------------------\n\n`dbus_proxy` is a Lua module built on top\nof [lgi](https://github.com/pavouk/lgi) to offer a simple API to GLib's\nGIO\n[GDBusProxy](https://developer.gnome.org/gio/stable/GDBusProxy.html#GDBusProxy.description)\nobjects. This should make it easier to interact\nwith [DBus](https://dbus.freedesktop.org/doc/dbus-tutorial.html) interfaces.\n\nCreating a proxy object is as easy as doing\n\n```lua\np = require(\"dbus_proxy\")\nproxy = p.Proxy:new(\n  {\n    bus = p.Bus.SYSTEM, -- or p.Bus.SESSION\n    name = \"com.example.BusName\",\n    interface = \"com.example.InterfaceName\",\n    path = \"/com/example/objectPath\"\n  }\n)\n```\n\nAt this point, all the properties, methods and signals of the object are\navailable in the `proxy` table.  Be aware that properties, methods and signals\nwill likely be written in `CamelCase` since this it the convention in DBus\n(e.g. `proxy.SomeProperty` or `proxy:SomeMethod()`). Please refer to the\ndocumentation of the object you are proxying for more information.\n\n-----\n\n**NOTE**\n\n*If* a property has the same name as a *method*, as e.g. it happens with\n`org.freedesktop.systemd1.Unit` in the case of `Restart`, an *underscore* will\nbe added to it.\n\nFor example:\n\n``` lua\nlocal p = require(\"dbus_proxy\")\n\nlocal proxy = p.Proxy:new(\n  {\n    bus = p.Bus.SESSION,\n    name = \"org.freedesktop.systemd1\",\n    interface = \"org.freedesktop.systemd1.Unit\",\n    path = \"/org/freedesktop/systemd1/unit/redshift_2eservice\"\n  }\n)\n\n-- https://github.com/systemd/systemd/blob/v246/src/core/job.c#L1623\nlocal job_mode = \"replace\"\nok, err = proxy:Restart(_job_mode)\nassert(ok, tostring(err))\nprint(ok) -- e.g. \"/org/freedesktop/systemd1/job/123\"\n\nrestart_property = proxy._Restart\n-- same as: proxy.accessors._Restart.getter(proxy)\n```\n\n-----\n\nThe code is released under the Apache License Version 2.0, see the LICENSE file\nfor full information.\n\nFor more detailed information, see the documentation in the `docs` folder.\n\n\n# Motivation\n\nI have written a few widgets for the Awesome Window Manager that use DBus. The\nwidgets depend on [`ldbus_api`](https://github.com/stefano-m/lua-ldbus_api) -\nalso written by me - which is a high level API written on top\nof [`ldbus`](https://github.com/daurnimator/ldbus/).  `ldbus` has\nan [outstanding bug](https://github.com/daurnimator/ldbus/issues/6) that may\ncause of random crashes.  I have been looking into a more actively developed\nlibrary to replace `ldbus_api` and `ldbus` and found `lgi`, which offers a much\nbetter way of interacting with DBus using GIO's Proxy objects.\n\n# Documentation\n\nThe documentation is built using [`ldoc`](stevedonovan.github.io/ldoc/). For\nconvenience, a copy of the generated documentation is available in the `docs`\nfolder.\n\nTo generate the documentation from source, run\n\n```sh\nldoc .\n```\n\nfrom the root of the repository.\n\n# Installation\n\n## Luarocks\n\nYou can install `dbus_proxy` with `luarocks` by running:\n\n```shell\nluarocks install dbus_proxy\n```\n\nYou may need to use the `--local` option if you can't or don't want to install\nthe module at the system level.\n\n## NixOS\n\nIf you are on NixOS, you can install this package from\n[nix-stefano-m-overlays](https://github.com/stefano-m/nix-stefano-m-nix-overlays).\n\n# Testing\n\nTo test the code, you need to install\nthe [busted](http://olivinelabs.com/busted/) framework.  Then run\n\n``` sh\nbusted .\n```\n\n(node the dot!) from the root of the repository to run the tests.\n\nThe tests depend on a number of DBus interfaces being available on the\nsystem.  It would be nice to not depend on this, but I don't have time to come\nup with a complete DBus mock (contributions are welcome!).\n\n\n# Contributing\n\nThis project is developed in my own spare time, progress will likely be slow as\nsoon as I reach a decent level of satisfaction with it.  That said, for\nfeedback, suggestions, bug reports and improvements, please create an issue in\nGitHub and I'll do my best to respond.\n\n\n# Synchronizing Proxy Objects\n\nAs already explained, the Proxy objects expose methods, properties and signals\nof the corresponding remote DBus objects.  When a property in a DBus object\nchanges, the same change is reflected in the proxy.  Similarly, when a signal\nis emitted, the proxy object is notified accordingly.\n\nFor all this to work though, the code must run\ninside\n[GLib's main event loop](https://developer.gnome.org/glib/stable/glib-The-Main-Event-Loop.html#glib-The-Main-Event-Loop.description). This\ncan be achieved in two ways:\n\n- Create\n   a\n   [main loop](https://developer.gnome.org/glib/stable/glib-The-Main-Event-Loop.html#GMainLoop) and\n   run it when the application starts:\n\n```lua\n   GLib = require(\"lgi\").GLib\n   -- Set up the application, then do:\n   main_loop = GLib.MainLoop()\n   main_loop:run()\n   -- use main_loop:quit() to stop the main loop.\n```\n\n- Use more fine-grained control by running an iteration at a time from\n   the\n   [main context](https://developer.gnome.org/glib/stable/glib-The-Main-Event-Loop.html#GMainContext);\n   this is particularly useful when you want to integrate your code with an\n   **external main loop**:\n\n```lua\n   GLib = require(\"lgi\").GLib\n   -- Set up the code, then do\n   ctx = GLib.MainLoop():get_context()\n   -- Run a single blocking iteration\n   if ctx:iteration(true) == true then\n     print(\"something changed!\")\n   end\n   -- Run a single non-blocking iteration\n   if ctx:iteration() == true then\n     print(\"something changed here too!\")\n   end\n```\n\n\n--------\n\n  **NOTE**\n\n  If you use the [Awesome Window Manager](https://awesomewm.org/), the code\n  will be already running inside a main loop.\n\n--------\n","funding_links":[],"categories":["Installation"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstefano-m%2Flua-dbus_proxy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstefano-m%2Flua-dbus_proxy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstefano-m%2Flua-dbus_proxy/lists"}