Subject: bug#79062: [PATCH] Add an example for the :authorizable `dbus-call-method' keyword

From: Steven Allen <[email-masked]>
Date: Sun, 20 Jul 2025 14:43:02 -0700

Tags: patch

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

In GNU Emacs 31.0.50 (build 1, x86_64-pc-linux-gnu, cairo version
 1.18.4) of 2025-07-20 built on Laptop
Repository revision: 899bf4e44a18abfcf4da75a20367d37ea5bf0b44
Repository branch: merged
Windowing system distributor 'The X.Org Foundation', version 11.0.12101018
System Description: Arch Linux

Configured using:
 'configure
 'CPPFLAGS=-I/run/user/1000/build/emacs-git/src/mps-git/build/include '
 'LDFLAGS=-L/run/user/1000/build/emacs-git/src/mps-git/build/lib -Wl,-O1
 -Wl,--sort-common -Wl,--as-needed -Wl,-z,relro -Wl,-z,now
 -Wl,-z,pack-relative-relocs -flto=auto' --prefix=/usr --sysconfdir=/etc
 --libexecdir=/usr/lib --localstatedir=/var --mandir=/usr/share/man
 --with-gameuser=:games --with-modules --without-m17n-flt
 --without-selinux --without-pop --without-gconf --disable-gc-mark-trace
 --with-mps=yes --enable-link-time-optimization
 --with-native-compilation=yes --with-xinput2 --with-x-toolkit=no
 --without-toolkit-scroll-bars --without-xaw3d --without-gsettings
 --with-cairo-xcb --without-xft --with-sound=no --with-tree-sitter
 --without-gpm --without-compress-install
 '--program-transform-name=s/\([ec]tags\)/\1.emacs/'
 'CFLAGS=-march=native -mtune=native -O3 -pipe -fno-plt -fexceptions
 -Wp,-D_FORTIFY_SOURCE=3 -Wformat -Werror=format-security
 -fstack-clash-protection -fcf-protection -fomit-frame-pointer
 -fno-math-errno -fno-trapping-math -fno-math-errno -fno-trapping-math
 -flto=auto''

>From e182a3fdadee5ffd88756bfad2c513dc248f9a75 Mon Sep 17 00:00:00 2001
From: Steven Allen <[email-masked]>
Date: Sun, 20 Jul 2025 14:34:36 -0700
Subject: [PATCH] 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.
---
 doc/misc/dbus.texi | 13 ++++++++++++-
 1 file changed, 12 insertions(+), 1 deletion(-)

diff --git a/doc/misc/dbus.texi b/doc/misc/dbus.texi
index 89a0ca086a6..71e74a28584 100644
--- a/doc/misc/dbus.texi
+++ b/doc/misc/dbus.texi
@@ -1228,7 +1228,18 @@ Synchronous Methods
 
 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")
 
 The remaining arguments @var{args} are passed to @var{method} as
 arguments.  They are converted into D-Bus types as described in
-- 
2.50.1