diff options
author | David Zeuthen <davidz@redhat.com> | 2011-03-03 13:13:11 -0500 |
---|---|---|
committer | David Zeuthen <davidz@redhat.com> | 2011-03-03 13:18:05 -0500 |
commit | 02cebdb060e76e6d176f05ef24968e6d17225edb (patch) | |
tree | ad0bf3810442b299a21e5014364ab6733ead4475 /docs/polkit | |
parent | 76792accc8c846059b551dfba91ec3cd24d45d71 (diff) |
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>
Diffstat (limited to 'docs/polkit')
4 files changed, 45 insertions, 20 deletions
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<String,String> <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<String,String> <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"> |