From: Steven Allen <steven@stebalien.com>
Date: Mon, 21 Jul 2025 07:50:33 +0000 (+0200)
Subject: Add an example for the :authorizable `dbus-call-method' keyword
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=4d0a7f51e7c4b4650e2c585cbfd1f8bf5bb824f2;p=emacs.git

Add an example for the :authorizable `dbus-call-method' keyword

This was requested in bug#71969 over a year ago.

* doc/misc/dbus.texi (Synchronous Methods): Add example for
`dbus-call-method' with authorization.  (Bug#79062)

(cherry picked from commit 59575c32aa1e0d28c1c7113f1ce73cb64cec8e92)
---

diff --git a/doc/misc/dbus.texi b/doc/misc/dbus.texi
index 89a0ca086a6..f9ab2c56e3c 100644
--- a/doc/misc/dbus.texi
+++ b/doc/misc/dbus.texi
@@ -1228,7 +1228,19 @@ and Events}).
 
 If the parameter @code{:authorizable} is given and the following
 @var{auth} is non-@code{nil}, the invoked method may interactively
-prompt the user for authorization.  The default is @code{nil}.
+prompt the user for authorization.  The default is @code{nil}.  For
+example, the following will restart the Bluez systemd service, prompting
+the user for authorization via polkit (assuming a polkit agent is
+running):
+
+@lisp
+(dbus-call-method
+ :system
+ "org.freedesktop.systemd1" "/org/freedesktop/systemd1"
+ "org.freedesktop.systemd1.Manager" "RestartUnit"
+ :authorizable t
+ "bluetooth.service" "replace")
+@end lisp
 
 The remaining arguments @var{args} are passed to @var{method} as
 arguments.  They are converted into D-Bus types as described in