From 02cebdb060e76e6d176f05ef24968e6d17225edb Mon Sep 17 00:00:00 2001 From: David Zeuthen Date: Thu, 3 Mar 2011 13:13:11 -0500 Subject: 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 --- docs/man/pkexec.xml | 20 +++++++--- ....freedesktop.PolicyKit1.AuthenticationAgent.xml | 10 +++-- ...erface-org.freedesktop.PolicyKit1.Authority.xml | 45 ++++++++++++++++++---- docs/polkit/overview.xml | 9 ----- docs/polkit/polkit-1-docs.xml | 1 - 5 files changed, 59 insertions(+), 26 deletions(-) (limited to 'docs') 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 @@ FIXME: MISSING XINCLUDE CONTENT - and drop it in - the /usr/share/polkit-1/actions 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 + /usr/share/polkit-1/actions 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 + $(user), $(program) and + $(command_line) 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. "/usr/bin/pk-example-frobnicate") and + the command-line, e.g. "pk-example-frobnicate foo + bar". For example, for the action defined above, the + following authentication dialog will be shown: 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. IN Dict<String,String> details: -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 RegisterAuthenticationAgent(). -Keys starting with polkit. are reserved for internal use and should never be displayed in the UI. -Known key/value-pairs include polkit.caller-pid (the process id of the mechanism making the authorization check) and polkit.subject-pid (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 + polkit.caller-pid (the process id of the + mechanism making the authorization check) and + polkit.subject-pid (the process id of the + subject the check is for). 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 Subject OUT AuthorizationResult result) -Checks if subject is authorized to perform the action with identifier action_id.If cancellation_id is non-empty and already in use for the caller, the org.freedesktop.PolicyKit1.Error.CancellationIdNotUnique error is returned.Note that CheckAuthorizationFlags.AllowUserInteraction 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. + + Checks if subject is authorized to + perform the action with identifier + action_id + + + If cancellation_id is non-empty and + already in use for the caller, the org.freedesktop.PolicyKit1.Error.CancellationIdNotUnique + error is returned. + + + Note that CheckAuthorizationFlags.AllowUserInteraction + 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. + + + @@ -594,15 +613,27 @@ Identifier for the action that subject is attempting to d IN Dict<String,String> details: -Details describing the action. Keys starting with polkit. are reserved for internal use and cannot be used. +Details describing the action. Keys starting with polkit. are can only be set if defined in this document. Known keys include polkit.message and - polkit.message.gettext-domain 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. + polkit.gettext_domain 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. + + + The (translated version of) polkit.message + may include references to other keys that are expanded with + their respective values. For example if the key + device_file has the value + /dev/sda then the message + "Authenticate to format $(device_file)" is + expanded to "Authenticate to format + /dev/sda". + + + The key polkit.icon_name is used to override the icon shown in the authentication dialog. 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 @@ - - POLKIT_BACKEND_ACTION_LOOKUP_EXTENSION_POINT_NAME - - Allows a mechanism to customize the contents of authentication - dialogs. Implementations of this extension point must - implement the #PolkitBackendActionLookup interface. - - - 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 @@ - -- cgit v1.2.1