Deprecated PolkitBackendActionLookup

Instead, pass the untranslated message as polkit.message and set the
gettext domain on polkit.gettext_domain. For printf()-style messages,
occurences of the form $(name_of_key) in the translated version of
polkit.message are expanded with the value of the property
name_of_key. See the pkexec(1) mechanism for an example of how to use
this.

Additionally, the property polkit.icon_name can be set to the
icon. Note that not all authentication agents use this - in
particular, gnome-shell does not.

It is no longer possible to set the details to be shown in the
authentication dialog. It was never a good idea to hide information
there anyway. Instead, the mechanism should format a meaningful
message.

Signed-off-by: David Zeuthen <davidz@redhat.com>

5 files changed, 59 insertions, 26 deletions

diff --git a/docs/man/pkexec.xml b/docs/man/pkexec.xml
index 97ab315..2a0e721 100644
--- a/docs/man/pkexec.xml
+++ b/docs/man/pkexec.xml
@@ -152,13 +152,21 @@
     <programlisting>
 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../src/examples/org.freedesktop.policykit.examples.pkexec.policy"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting>
     <para>
-      and drop it in
-      the <filename>/usr/share/polkit-1/actions</filename> directory
-      under a suitable name (e.g. matching the namespace of the
-      action).  Note that in addition to specifying the program, the
+      and drop it in the
+      <filename>/usr/share/polkit-1/actions</filename> directory under
+      a suitable name (e.g. matching the namespace of the action).
+      Note that in addition to specifying the program, the
       authentication message, description, icon and defaults can be
-      specified. For example, for the action defined above, the following
-      authentication dialog will be shown:
+      specified. Note that occurences of the strings
+      <literal>$(user)</literal>, <literal>$(program)</literal> and
+      <literal>$(command_line)</literal> in the message will be
+      replaced with respectively the user (of the form "Real Name
+      (username)" or just "username" if there is no real name for the
+      username), the binary to execute (a fully-qualified path,
+      e.g. "<literal>/usr/bin/pk-example-frobnicate</literal>") and
+      the command-line, e.g. "<literal>pk-example-frobnicate foo
+      bar</literal>". For example, for the action defined above, the
+      following authentication dialog will be shown:
     </para>
     <mediaobject id="pkexec-frobnicate">
       <imageobject>
diff --git a/docs/polkit/docbook-interface-org.freedesktop.PolicyKit1.AuthenticationAgent.xml b/docs/polkit/docbook-interface-org.freedesktop.PolicyKit1.AuthenticationAgent.xml
index b01fceb..ec59626 100644
--- a/docs/polkit/docbook-interface-org.freedesktop.PolicyKit1.AuthenticationAgent.xml
+++ b/docs/polkit/docbook-interface-org.freedesktop.PolicyKit1.AuthenticationAgent.xml
@@ -87,9 +87,13 @@ The themed icon describing the action or the empty string if no icon is set.
     <term><literal>IN  Dict&lt;String,String&gt; <parameter>details</parameter></literal>:</term>
     <listitem>
       <para>
-Details about the authentication request. This is a dictionary of key/value pairs where both key and value are strings. These strings are translated into the locale passed when registering the authentication agent using <link linkend="eggdbus-method-org.freedesktop.PolicyKit1.Authority.RegisterAuthenticationAgent">RegisterAuthenticationAgent()</link>.
-Keys starting with <literal>polkit.</literal> are reserved for internal use and should never be displayed in the UI.
-Known key/value-pairs include <literal>polkit.caller-pid</literal> (the process id of the mechanism making the authorization check) and <literal>polkit.subject-pid</literal> (the process id of the subject the check is for).
+        Details about the authentication request. This is a dictionary
+        of key/value pairs where both key and value are strings.
+        Known key/value-pairs include
+        <literal>polkit.caller-pid</literal> (the process id of the
+        mechanism making the authorization check) and
+        <literal>polkit.subject-pid</literal> (the process id of the
+        subject the check is for).
       </para>
     </listitem>
   </varlistentry>
diff --git a/docs/polkit/docbook-interface-org.freedesktop.PolicyKit1.Authority.xml b/docs/polkit/docbook-interface-org.freedesktop.PolicyKit1.Authority.xml
index ee29c4c..74338c3 100644
--- a/docs/polkit/docbook-interface-org.freedesktop.PolicyKit1.Authority.xml
+++ b/docs/polkit/docbook-interface-org.freedesktop.PolicyKit1.Authority.xml
@@ -571,7 +571,26 @@ CheckAuthorization (IN  <link linkend="eggdbus-struct-Subject">Subject</link>
                     OUT <link linkend="eggdbus-struct-AuthorizationResult">AuthorizationResult</link>      result)
     </programlisting>
     <para>
-<para>Checks if <parameter>subject</parameter> is authorized to perform the action with identifier <parameter>action_id</parameter>.</para><para>If <parameter>cancellation_id</parameter> is non-empty and already in use for the caller, the <link linkend="eggdbus-constant-Error.org.freedesktop.PolicyKit1.Error.CancellationIdNotUnique">org.freedesktop.PolicyKit1.Error.CancellationIdNotUnique</link> error is returned.</para><para>Note that <link linkend="eggdbus-constant-CheckAuthorizationFlags.AllowUserInteraction">CheckAuthorizationFlags.AllowUserInteraction</link> SHOULD be passed ONLY if the event that triggered the authorization check is stemming from an user action, e.g. the user pressing a button or attaching a device.</para>
+      <para>
+        Checks if <parameter>subject</parameter> is authorized to
+        perform the action with identifier
+        <parameter>action_id</parameter>
+      </para>
+      <para>
+        If <parameter>cancellation_id</parameter> is non-empty and
+        already in use for the caller, the <link
+        linkend="eggdbus-constant-Error.org.freedesktop.PolicyKit1.Error.CancellationIdNotUnique">org.freedesktop.PolicyKit1.Error.CancellationIdNotUnique</link>
+        error is returned.
+      </para>
+      <para>
+        Note that <link
+        linkend="eggdbus-constant-CheckAuthorizationFlags.AllowUserInteraction">CheckAuthorizationFlags.AllowUserInteraction</link>
+        SHOULD be passed ONLY if the event that triggered the
+        authorization check is stemming from an user action, e.g. the
+        user pressing a button or attaching a device.
+      </para>
+      <para>
+      </para>
     </para>
 <variablelist role="params">
   <varlistentry>
@@ -594,15 +613,27 @@ Identifier for the action that <parameter>subject</parameter> is attempting to d
     <term><literal>IN  Dict&lt;String,String&gt; <parameter>details</parameter></literal>:</term>
     <listitem>
       <para>
-Details describing the action. Keys starting with <literal>polkit.</literal> are reserved for internal use and cannot be used.
+Details describing the action. Keys starting with <literal>polkit.</literal> are can only be set if defined in this document.
       </para>
       <para>
         Known keys include <literal>polkit.message</literal> and
-        <literal>polkit.message.gettext-domain</literal> that can be
-        used to override the message shown to the user (the user might
-        be running an authentication agent in another locale than the
-        calling process so that's why both the message and gettext
-        domain is needed.
+        <literal>polkit.gettext_domain</literal> that can be used to
+        override the message shown to the user. This latter is needed
+        because the user could be running an authentication agent in
+        another locale than the calling process.
+      </para>
+      <para>
+        The (translated version of) <literal>polkit.message</literal>
+        may include references to other keys that are expanded with
+        their respective values. For example if the key
+        <literal>device_file</literal> has the value
+        <literal>/dev/sda</literal> then the message
+        "<literal>Authenticate to format $(device_file)</literal>" is
+        expanded to "<literal>Authenticate to format
+        /dev/sda</literal>".
+      </para>
+      <para>
+        The key <literal>polkit.icon_name</literal> is used to override the icon shown in the authentication dialog.
       </para>
       <para>
         If non-empty, then the request will fail with
diff --git a/docs/polkit/overview.xml b/docs/polkit/overview.xml
index 31f856f..20f019c 100644
--- a/docs/polkit/overview.xml
+++ b/docs/polkit/overview.xml
@@ -123,14 +123,5 @@
       </para>
     </formalpara>
 
-    <formalpara>
-      <title>POLKIT_BACKEND_ACTION_LOOKUP_EXTENSION_POINT_NAME</title>
-      <para>
-        Allows a mechanism to customize the contents of authentication
-        dialogs. Implementations of this extension point must
-        implement the #PolkitBackendActionLookup interface.
-      </para>
-    </formalpara>
-
   </chapter>
 </part>
diff --git a/docs/polkit/polkit-1-docs.xml b/docs/polkit/polkit-1-docs.xml
index 06510ca..22092d9 100644
--- a/docs/polkit/polkit-1-docs.xml
+++ b/docs/polkit/polkit-1-docs.xml
@@ -94,7 +94,6 @@
     <xi:include href="xml/polkitbackendauthority.xml"/>
     <xi:include href="xml/polkitbackendinteractiveauthority.xml"/>
     <xi:include href="xml/polkitbackendlocalauthority.xml"/>
-    <xi:include href="xml/polkitbackendactionlookup.xml"/>
   </part>
 
   <part id="ref-authentication-agent-api">