|
|
|
PolicyKit-gnome Library Reference Manual | |
|---|---|---|---|---|
PolKitGnomeActionPolKitGnomeAction — A GtkAction subclass where instances can be tied to a specific PolicyKit action. |
PolKitGnomeActionPrivate;
PolKitGnomeAction;
PolKitGnomeAction* polkit_gnome_action_new (const gchar *name);
PolKitGnomeAction* polkit_gnome_action_new_default (const gchar *name,
PolKitAction *polkit_action,
const gchar *label,
const gchar *tooltip);
PolKitResult polkit_gnome_action_get_polkit_result
(PolKitGnomeAction *action);
gboolean polkit_gnome_action_get_sensitive (PolKitGnomeAction *action);
void polkit_gnome_action_set_sensitive (PolKitGnomeAction *action,
gboolean sensitive);
gboolean polkit_gnome_action_get_visible (PolKitGnomeAction *action);
void polkit_gnome_action_set_visible (PolKitGnomeAction *action,
gboolean visible);
GtkWidget* polkit_gnome_action_create_button (PolKitGnomeAction *action);
"auth-icon-name" gchar* : Read / Write "auth-label" gchar* : Read / Write "auth-sensitive" gboolean : Read / Write "auth-short-label" gchar* : Read / Write "auth-tooltip" gchar* : Read / Write "auth-visible" gboolean : Read / Write "master-sensitive" gboolean : Read / Write "master-visible" gboolean : Read / Write "no-icon-name" gchar* : Read / Write "no-label" gchar* : Read / Write "no-sensitive" gboolean : Read / Write "no-short-label" gchar* : Read / Write "no-tooltip" gchar* : Read / Write "no-visible" gboolean : Read / Write "polkit-action" gpointer : Read / Write / Construct "polkit-action-sufficient" GValueArray* : Read / Write / Construct "self-blocked-icon-name" gchar* : Read / Write "self-blocked-label" gchar* : Read / Write "self-blocked-sensitive" gboolean : Read / Write "self-blocked-short-label" gchar* : Read / Write "self-blocked-tooltip" gchar* : Read / Write "self-blocked-visible" gboolean : Read / Write "target-pid" guint : Read / Write / Construct "yes-icon-name" gchar* : Read / Write "yes-label" gchar* : Read / Write "yes-sensitive" gboolean : Read / Write "yes-short-label" gchar* : Read / Write "yes-tooltip" gchar* : Read / Write "yes-visible" gboolean : Read / Write
Actions in GTK+ represent operations that the user can be perform, along with some information how it should be presented in the interface. Each action provides methods to create icons, menu items and toolbar items representing itself. Each action can have one or more proxy menu item, toolbar button or other proxy widgets. Proxies mirror the state of the action (text label, tooltip, icon, visible, sensitive, etc), and should change when the action's state changes. When the proxy is activated, it should activate its action.
Instances of PolKitGnomeAction class updates the label, tooltip, icon-name, visible and properties of the parent GtkAction instance according to what result PolicyKit gives about a given PolKitAction object. The PolKitGnomeContext class is used internally to track changes. This means that external events (such as the editing of the /etc/PolicyKit/PolicyKit.conf file, ConsoleKit session activity changes or if the user gains a privilege via authentication) will trigger the action, and thus connected proxy widgets, to be updated.
In addition, the PolKitGnomeAction class intercepts the ::activate signal defined in GtkAction. When the result from PolicyKit is yes, the signal is propagated. If the result is auth, polkit_gnome_auth_show_dialog() will be used to bring up an authentication dialog for the given PolKitAction. If the user succesfully gained the privilege, a ::activate signal will be synthesized. If the result is no, the signal is also propagated.
As a result, everything happens under the covers; the application programmer using PolKitGnomeAction will only get the ::activate signal when the answer from PolicyKit is yes and as such don't have to worry about bringing up authentication dialogs if the property "no-sensitive" is set to FALSE.
When an authentication dialog is show, the PolKitGnomeAction class will pass the XID of the top-level window that the proxy widget causing the activation to polkit_gnome_auth_show_dialog().
An example of how to use PolKitGnomeAction follows. First, build the following program
/* -*- Mode: C; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 8 -*-
*
* polkit-gnome-example: Simple example showing how a GTK+ application
* can use PolicyKit.
*
* Copyright (C) 2007 David Zeuthen <david@fubar.dk>
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation; either version 2 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
*
*/
#ifdef HAVE_CONFIG_H
# include "config.h"
#endif
#include <sys/types.h>
#include <unistd.h>
#include <stdlib.h>
#include <string.h>
#include <glib/gi18n.h>
#include <polkit-gnome/polkit-gnome.h>
static GtkWidget *toplevel_window;
static PolKitGnomeContext *pkgc;
static void
_button_toggled (GtkToggleButton *toggle_button, PolKitGnomeAction *action)
{
g_debug ("in _button_toggled for action '%s'", gtk_action_get_name (GTK_ACTION (action)));
}
static void
_button_clicked (GtkToggleButton *toggle_button, PolKitGnomeAction *action)
{
g_debug ("in _button_clicked for '%s'", gtk_action_get_name (GTK_ACTION (action)));
}
/* This function is called when the following two conditions are true
*
* - the user clicks one of the buttons created via the method
* polkit_gnome_action_create_button() (see main() below)
*
* - For the PolKitAction associated with the button, PolicyKit
* reports either 'no' or 'yes'.
*
* In the event the user clicks a button and he is not privileged
* (e.g. PolicyKit returns one of the 'auth' results) he will be
* asked to authenticate; this all happens behind the scenes; the
* application _only_ gets the ::activate signal on PolKitGnomeAction
* instances when PolicyKit reports that the user is privileged.
*
* Note that for action org.gnome.policykit.examples.tweak, the
* corresponding PolKitGnomeAction is configured to be sensitive (see
* main() below) even when PolicyKit reports 'no'. Hence we need to
* handle that case too and we do that by popping up a dialog. Note
* that this can only be triggered by adding a stanza like
*
* <match action="org.gnome.policykit.examples.tweak">
* <return result="no"/>
* </match>
*
* to the /etc/PolicyKit/PolicyKit.conf file.
*/
static void
activate_polkit_gnome_action (PolKitGnomeAction *action, gpointer user_data)
{
PolKitCaller *pk_caller;
PolKitAction *pk_action;
PolKitResult pk_result;
DBusError dbus_error;
if (strcmp (gtk_action_get_name (GTK_ACTION (action)), "toggle") == 0) {
/* we're not supposed to run actions when the
* authorization is flipped.. we're supposed to make
* some UI sensitive and de-sensitive.. (one use at least) */
g_debug ("toggled for '%s'", gtk_action_get_name (GTK_ACTION (action)));
return;
}
g_debug ("pretending to be the mechanism for action '%s'", gtk_action_get_name (GTK_ACTION (action)));
g_object_get (action, "polkit-action", &pk_action, NULL);
dbus_error_init (&dbus_error);
pk_caller = polkit_tracker_get_caller_from_pid (pkgc->pk_tracker,
getpid (),
&dbus_error);
if (pk_caller == NULL) {
g_warning ("Cannot get PolKitCaller object for ourselves (pid=%d): %s: %s",
getpid (), dbus_error.name, dbus_error.message);
dbus_error_free (&dbus_error);
} else {
/* note how we pass #TRUE to revoke_if_one_shot - this is because we're
* pretending to be the mechanism
*/
pk_result = polkit_context_is_caller_authorized (pkgc->pk_context,
pk_action,
pk_caller,
TRUE,
NULL);
polkit_caller_unref (pk_caller);
}
polkit_action_unref (pk_action);
}
static void
activate_action (GtkAction *action, gpointer user_data)
{
if (g_ascii_strcasecmp (gtk_action_get_name (action), "Quit") == 0) {
exit (0);
} else if (g_ascii_strcasecmp (gtk_action_get_name (action), "About") == 0) {
const char *authors[] = {
"David Zeuthen <david@fubar.dk>",
NULL};
const char *documenters[] = {
"David Zeuthen <david@fubar.dk>",
NULL};
gtk_show_about_dialog (NULL,
"version", VERSION,
"copyright", _("Copyright © 2007 David Zeuthen"),
"website-label", _("PolicyKit-gnome Website"),
"website", "http://hal.freedesktop.org/docs/PolicyKit-gnome/",
"program-name", _("PolicyKit-gnome demo"),
"comments", _("PolicyKit for the GNOME desktop"),
"logo-icon-name", GTK_STOCK_DIALOG_AUTHENTICATION,
"authors", authors,
"documenters", documenters,
NULL);
}
}
static GtkActionEntry entries[] = {
{ "FileMenu", NULL, N_("_File") }, /* name, stock id, label */
{ "ActionsMenu", NULL, N_("_Actions") }, /* name, stock id, label */
{ "HelpMenu", NULL, N_("_Help") }, /* name, stock id, label */
{ "Quit", GTK_STOCK_QUIT, /* name, stock id */
N_("_Quit"), "<control>Q", /* label, accelerator */
N_("Quit"), /* tooltip */
G_CALLBACK (activate_action) },
{ "About", GTK_STOCK_ABOUT, /* name, stock id */
N_("_About"), "<control>A", /* label, accelerator */
N_("About"), /* tooltip */
G_CALLBACK (activate_action) },
};
static guint n_entries = G_N_ELEMENTS (entries);
static const gchar *ui_info =
"<ui>"
" <menubar name='MenuBar'>"
" <menu action='FileMenu'>"
" <menuitem action='Quit'/>"
" </menu>"
" <menu action='ActionsMenu'>"
" <menuitem action='frobnicate'/>"
" <menuitem action='jump'/>"
" <menuitem action='tweak'/>"
" <menuitem action='twiddle'/>"
" <menuitem action='punch'/>"
" <menuitem action='toggle'/>"
" </menu>"
" <menu action='HelpMenu'>"
" <menuitem action='About'/>"
" </menu>"
" </menubar>"
" <toolbar name='ToolBar'>"
" <toolitem action='Quit'/>"
" <toolitem action='About'/>"
" <separator action='Sep1'/>"
" <toolitem action='frobnicate'/>"
" <toolitem action='jump'/>"
" <toolitem action='tweak'/>"
" <toolitem action='twiddle'/>"
" <toolitem action='punch'/>"
" <toolitem action='toggle'/>"
" </toolbar>"
"</ui>";
int
main (int argc, char **argv)
{
GtkWidget *hbox;
GtkWidget *vbox;
GtkWidget *vbox2;
GtkWidget *label;
GMainLoop*loop;
PolKitAction *pk_action;
PolKitGnomeAction *action;
GtkWidget *button;
GtkUIManager *ui;
GtkActionGroup *actions;
gtk_init (&argc, &argv);
pkgc = polkit_gnome_context_get (NULL);
loop = g_main_loop_new (NULL, FALSE);
toplevel_window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
actions = gtk_action_group_new ("Actions");
gtk_action_group_add_actions (actions, entries, n_entries, NULL);
ui = gtk_ui_manager_new ();
gtk_ui_manager_insert_action_group (ui, actions, 0);
gtk_window_add_accel_group (GTK_WINDOW (toplevel_window),
gtk_ui_manager_get_accel_group (ui));
gtk_ui_manager_add_ui_from_string (ui, ui_info, -1, NULL);
/*----------------------------------------------------------------*/
vbox = gtk_vbox_new (FALSE, 10);
gtk_container_add (GTK_CONTAINER (toplevel_window), vbox);
vbox2 = gtk_vbox_new (FALSE, 0);
gtk_box_pack_start (GTK_BOX (vbox), vbox2, FALSE, FALSE, 0);
/*----------------------------------------------------------------*/
label = gtk_label_new (NULL);
gtk_label_set_markup (GTK_LABEL (label), _("Making the helper <b>Frobnicate</b> requires the "
"user to authenticate. The authorization is kept for "
"the life time of the process"));
gtk_misc_set_alignment (GTK_MISC (label), 0.0, 0.0);
gtk_label_set_line_wrap (GTK_LABEL (label), TRUE);
gtk_box_pack_start (GTK_BOX (vbox), label, FALSE, FALSE, 0);
pk_action = polkit_action_new ();
polkit_action_set_action_id (pk_action, "org.gnome.policykit.examples.frobnicate");
action = polkit_gnome_action_new_default ("frobnicate", pk_action, _("Frobnicate!"), NULL);
polkit_action_unref (pk_action);
g_signal_connect (action, "activate", G_CALLBACK (activate_polkit_gnome_action), NULL);
gtk_action_group_add_action (actions, GTK_ACTION (action));
button = polkit_gnome_action_create_button (action);
gtk_box_pack_start (GTK_BOX (vbox),
button,
FALSE, FALSE, 0);
g_signal_connect (button, "clicked", G_CALLBACK (_button_clicked), action);
/*----------------------------------------------------------------*/
gtk_box_pack_start (GTK_BOX (vbox), gtk_hseparator_new (), FALSE, FALSE, 0);
/*----------------------------------------------------------------*/
label = gtk_label_new (NULL);
gtk_label_set_markup (GTK_LABEL (label), _("Making the helper <b>Jump</b> requires the "
"user to authenticate. This is a one-shot authorization."));
gtk_misc_set_alignment (GTK_MISC (label), 0.0, 0.0);
gtk_label_set_line_wrap (GTK_LABEL (label), TRUE);
gtk_box_pack_start (GTK_BOX (vbox), label, FALSE, FALSE, 0);
pk_action = polkit_action_new ();
polkit_action_set_action_id (pk_action, "org.gnome.policykit.examples.jump");
action = polkit_gnome_action_new_default ("jump", pk_action, _("Jump!"), NULL);
polkit_action_unref (pk_action);
g_signal_connect (action, "activate", G_CALLBACK (activate_polkit_gnome_action), NULL);
gtk_action_group_add_action (actions, GTK_ACTION (action));
button = polkit_gnome_action_create_button (action);
gtk_box_pack_start (GTK_BOX (vbox),
button,
FALSE, FALSE, 0);
g_signal_connect (button, "clicked", G_CALLBACK (_button_clicked), action);
/*----------------------------------------------------------------*/
gtk_box_pack_start (GTK_BOX (vbox), gtk_hseparator_new (), FALSE, FALSE, 0);
/*----------------------------------------------------------------*/
label = gtk_label_new (NULL);
gtk_label_set_markup (GTK_LABEL (label), _("Making the helper <b>Tweak</b> requires a system "
"administrator to authenticate. This instance "
"overrides the defaults set in polkit_gnome_action_new()."));
gtk_misc_set_alignment (GTK_MISC (label), 0.0, 0.0);
gtk_label_set_line_wrap (GTK_LABEL (label), TRUE);
gtk_box_pack_start (GTK_BOX (vbox), label, FALSE, FALSE, 0);
pk_action = polkit_action_new ();
polkit_action_set_action_id (pk_action, "org.gnome.policykit.examples.tweak");
action = polkit_gnome_action_new_default ("tweak", pk_action, _("Tweak!"), NULL);
polkit_action_unref (pk_action);
/* For this particular GtkAction instance, we want to customize the appearence */
g_object_set (action,
"no-visible", TRUE,
"no-sensitive", TRUE,
"no-short-label", _("Tweak"),
"no-label", _("Tweak (long)"),
"no-tooltip", _("If your admin wasn't annoying, you could do this"),
"no-icon-name", GTK_STOCK_NO,
"auth-visible", TRUE,
"auth-sensitive", TRUE,
"auth-short-label", _("Tweak..."),
"auth-label", _("Tweak... (long)"),
"auth-tooltip", _("Only card carrying tweakers can do this!"),
"auth-icon-name", GTK_STOCK_DIALOG_AUTHENTICATION,
"yes-visible", TRUE,
"yes-sensitive", TRUE,
"yes-short-label", _("Tweak!"),
"yes-label", _("Tweak! (long)"),
"yes-tooltip", _("Go ahead, tweak tweak tweak!"),
"yes-icon-name", GTK_STOCK_YES,
NULL);
g_signal_connect (action, "activate", G_CALLBACK (activate_polkit_gnome_action), NULL);
gtk_action_group_add_action (actions, GTK_ACTION (action));
button = polkit_gnome_action_create_button (action);
gtk_box_pack_start (GTK_BOX (vbox),
button,
FALSE, FALSE, 0);
g_signal_connect (button, "clicked", G_CALLBACK (_button_clicked), action);
/*----------------------------------------------------------------*/
gtk_box_pack_start (GTK_BOX (vbox), gtk_hseparator_new (), FALSE, FALSE, 0);
/*----------------------------------------------------------------*/
label = gtk_label_new (NULL);
gtk_label_set_markup (GTK_LABEL (label), _("Making the helper <b>Twiddle</b> requires a system "
"administrator to authenticate. Once authenticated, this "
"privilege can be retained indefinitely."));
gtk_misc_set_alignment (GTK_MISC (label), 0.0, 0.0);
gtk_label_set_line_wrap (GTK_LABEL (label), TRUE);
gtk_box_pack_start (GTK_BOX (vbox), label, FALSE, FALSE, 0);
pk_action = polkit_action_new ();
polkit_action_set_action_id (pk_action, "org.gnome.policykit.examples.twiddle");
action = polkit_gnome_action_new_default ("twiddle", pk_action, _("Twiddle!"), NULL);
polkit_action_unref (pk_action);
g_signal_connect (action, "activate", G_CALLBACK (activate_polkit_gnome_action), NULL);
gtk_action_group_add_action (actions, GTK_ACTION (action));
button = polkit_gnome_action_create_button (action);
gtk_box_pack_start (GTK_BOX (vbox),
button,
FALSE, FALSE, 0);
g_signal_connect (button, "clicked", G_CALLBACK (_button_clicked), action);
/*----------------------------------------------------------------*/
gtk_box_pack_start (GTK_BOX (vbox), gtk_hseparator_new (), FALSE, FALSE, 0);
/*----------------------------------------------------------------*/
label = gtk_label_new (NULL);
gtk_label_set_markup (GTK_LABEL (label), _("Making the helper <b>Punch</b> requires the user to "
"authenticate. Once authenticated, this privilege can "
"be retained for the remainder of the desktop session."));
gtk_misc_set_alignment (GTK_MISC (label), 0.0, 0.0);
gtk_label_set_line_wrap (GTK_LABEL (label), TRUE);
gtk_box_pack_start (GTK_BOX (vbox), label, FALSE, FALSE, 0);
pk_action = polkit_action_new ();
polkit_action_set_action_id (pk_action, "org.gnome.policykit.examples.punch");
action = polkit_gnome_action_new_default ("punch", pk_action, _("Punch!"), NULL);
polkit_action_unref (pk_action);
g_signal_connect (action, "activate", G_CALLBACK (activate_polkit_gnome_action), NULL);
gtk_action_group_add_action (actions, GTK_ACTION (action));
button = polkit_gnome_action_create_button (action);
gtk_box_pack_start (GTK_BOX (vbox),
polkit_gnome_action_create_button (action),
FALSE, FALSE, 0);
g_signal_connect (button, "clicked", G_CALLBACK (_button_clicked), action);
/*----------------------------------------------------------------*/
gtk_box_pack_start (GTK_BOX (vbox), gtk_hseparator_new (), FALSE, FALSE, 0);
/*----------------------------------------------------------------*/
label = gtk_label_new (NULL);
gtk_label_set_markup (GTK_LABEL (label), _("The <b>Toggle</b> action demonstrates the use of "
"PolicyKit to drive a GtkToggleButton; it's an intuitive "
"way to ask users to give up authorizations when they "
"are done with them. E.g. the button is 'pressed in' exactly"
"when the authorization is held. Toggling the button means "
"obtaining resp. revoking the authorization in question."));
gtk_misc_set_alignment (GTK_MISC (label), 0.0, 0.0);
gtk_label_set_line_wrap (GTK_LABEL (label), TRUE);
gtk_box_pack_start (GTK_BOX (vbox), label, FALSE, FALSE, 0);
pk_action = polkit_action_new ();
polkit_action_set_action_id (pk_action, "org.gnome.policykit.examples.toggle");
PolKitGnomeToggleAction *toggle_action;
toggle_action = polkit_gnome_toggle_action_new_default ("toggle", pk_action,
_("Click to make changes..."),
_("Click to prevent changes"));
//g_object_set (toggle_action, "target-pid", 24887, NULL);
polkit_action_unref (pk_action);
g_signal_connect (toggle_action, "activate", G_CALLBACK (activate_polkit_gnome_action), NULL);
gtk_action_group_add_action (actions, GTK_ACTION (toggle_action));
GtkWidget *toggle_button;
toggle_button = polkit_gnome_toggle_action_create_toggle_button (toggle_action);
g_signal_connect (toggle_button, "toggled", G_CALLBACK (_button_toggled), toggle_action);
gtk_box_pack_start (GTK_BOX (vbox),
toggle_button,
FALSE, FALSE, 0);
/*----------------------------------------------------------------*/
gtk_box_pack_start (GTK_BOX (vbox), gtk_hseparator_new (), FALSE, FALSE, 0);
/*----------------------------------------------------------------*/
hbox = gtk_hbox_new (FALSE, 5);
gtk_box_pack_start (GTK_BOX (hbox), gtk_image_new_from_stock (GTK_STOCK_DIALOG_INFO,
GTK_ICON_SIZE_SMALL_TOOLBAR), FALSE, FALSE, 0);
label = gtk_label_new (NULL);
gtk_label_set_markup (GTK_LABEL (label), _("<i>Tip: try editing /etc/PolicyKit/Policy.conf and see the proxy widgets update in real-time.</i>."));
gtk_misc_set_alignment (GTK_MISC (label), 0.0, 0.0);
gtk_label_set_line_wrap (GTK_LABEL (label), TRUE);
gtk_box_pack_start (GTK_BOX (hbox), label, FALSE, FALSE, 0);
gtk_box_pack_start (GTK_BOX (vbox), hbox, FALSE, FALSE, 0);
/*----------------------------------------------------------------*/
g_object_unref (actions);
gtk_box_pack_start (GTK_BOX (vbox2),
gtk_ui_manager_get_widget (ui, "/MenuBar"),
FALSE, FALSE, 0);
GtkWidget *toolbar;
toolbar = gtk_ui_manager_get_widget (ui, "/ToolBar");
gtk_toolbar_set_style (GTK_TOOLBAR (toolbar), GTK_TOOLBAR_BOTH);
gtk_box_pack_start (GTK_BOX (vbox2),
toolbar,
FALSE, FALSE, 0);
/*----------------------------------------------------------------*/
gtk_window_set_default_size (GTK_WINDOW (toplevel_window), 700, 0);
gtk_window_set_title (GTK_WINDOW (toplevel_window), _("PolicyKit-gnome demo"));
g_signal_connect (toplevel_window, "delete-event", (GCallback) exit, NULL);
gtk_widget_show_all (toplevel_window);
g_main_loop_run (loop);
return 0;
}
with
gcc -o polkit-gnome-example `pkg-config --cflags --libs polkit-gnome` polkit-gnome-example.c
Then, put the following content
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE policyconfig PUBLIC
"-//freedesktop//DTD PolicyKit Policy Configuration 1.0//EN"
"http://www.freedesktop.org/standards/PolicyKit/1.0/policyconfig.dtd">
<policyconfig>
<action id="org.gnome.policykit.examples.jump">
<description>Jump</description>
<description xml:lang="en_GB">Jump</description>
<description xml:lang="fi">Hyppää</description>
<description xml:lang="fr">Sauter</description>
<description xml:lang="ja">Jump</description>
<message>System policy prevents the PolicyKit-gnome example helper from Jumping</message>
<message xml:lang="en_GB">System policy prevents the PolicyKit-gnome example helper from Jumping</message>
<message xml:lang="fi">Järjestelmäkäytäntö estää PolicyKit-gnomen esimerkkiavustinta hyppäämästä</message>
<message xml:lang="fr">La stratégie système empêche l'assistant exemple de PolicyKit-gnome de sauter</message>
<message xml:lang="ja">System policy prevents the PolicyKit-gnome example helper from Jumping</message>
<defaults>
<allow_inactive>no</allow_inactive>
<allow_active>auth_self_one_shot</allow_active>
</defaults>
</action>
<action id="org.gnome.policykit.examples.frobnicate">
<description>Frobnicate</description>
<description xml:lang="da">Frobniker</description>
<description xml:lang="en_GB">Frobnicate</description>
<description xml:lang="fi">Säädä</description>
<description xml:lang="fr">Tripatouiller</description>
<description xml:lang="ja">Frobnicate</description>
<message>System policy prevents the PolicyKit-gnome example helper from Frobnicating</message>
<message xml:lang="da">System indstillinger forhindrer PolicyKit-gnome eksempel hjælper i at Frobnikere!</message>
<message xml:lang="en_GB">System policy prevents the PolicyKit-gnome example helper from Frobnicating</message>
<message xml:lang="fi">Järjestelmäkäytäntö estää PolicyKit-gnomen esimerkkiavustinta säätämästä</message>
<message xml:lang="fr">La stratégie système empêche l'assistant exemple de PolicyKit-gnome de tripatouiller</message>
<message xml:lang="ja">System policy prevents the PolicyKit-gnome example helper from Frobnicating</message>
<defaults>
<allow_inactive>no</allow_inactive>
<allow_active>auth_self</allow_active>
</defaults>
</action>
<action id="org.gnome.policykit.examples.tweak">
<description>Tweak</description>
<description xml:lang="da">Tvæk</description>
<description xml:lang="en_GB">Tweak</description>
<description xml:lang="fi">Viritä</description>
<description xml:lang="fr">Ajuster</description>
<description xml:lang="ja">Tweak</description>
<message>System policy prevents the PolicyKit-gnome example helper from Tweaking</message>
<message xml:lang="da">System indstillinger forhindrer PolicyKit-gnome eksempel hjælper i at Tvække!</message>
<message xml:lang="en_GB">System policy prevents the PolicyKit-gnome example helper from Tweaking</message>
<message xml:lang="fi">Järjestelmäkäytäntö estää PolicyKit-gnomen esimerkkiavustinta virittämästä</message>
<message xml:lang="fr">La stratégie système empêche l'assistant exemple de PolicyKit-gnome d'ajuster</message>
<message xml:lang="ja">System policy prevents the PolicyKit-gnome example helper from Tweaking</message>
<defaults>
<allow_inactive>no</allow_inactive>
<allow_active>auth_admin</allow_active>
</defaults>
</action>
<action id="org.gnome.policykit.examples.twiddle">
<description>Twiddle</description>
<description xml:lang="da">Tvidl</description>
<description xml:lang="en_GB">Twiddle</description>
<description xml:lang="fi">Pyörittele</description>
<description xml:lang="fr">Bidouiller</description>
<description xml:lang="ja">Twiddle</description>
<message>System policy prevents the PolicyKit-gnome example helper from Twiddling</message>
<message xml:lang="da">System indstillinger forhindrer PolicyKit-gnome eksempel hjælper i at Tvidle!</message>
<message xml:lang="en_GB">System policy prevents the PolicyKit-gnome example helper from Twiddling</message>
<message xml:lang="fi">Järjestelmäkäytäntö estää PolicyKit-gnomen esimerkkiavustinta pyörittelemästä</message>
<message xml:lang="fr">La stratégie système empêche l'assistant exemple de PolicyKit-gnome de bidouiller</message>
<message xml:lang="ja">System policy prevents the PolicyKit-gnome example helper from Twiddling</message>
<defaults>
<allow_inactive>no</allow_inactive>
<allow_active>auth_admin_keep_always</allow_active>
</defaults>
</action>
<action id="org.gnome.policykit.examples.punch">
<description>Punch</description>
<description xml:lang="da">Smadre</description>
<description xml:lang="en_GB">Punch</description>
<description xml:lang="fi">Näpäytä</description>
<description xml:lang="fr">Frapper</description>
<description xml:lang="ja">Punch</description>
<message>System policy prevents the PolicyKit-gnome example helper from Punching</message>
<message xml:lang="da">System indstillinger forhindrer PolicyKit-gnome eksempel hjælper i at Smadre!</message>
<message xml:lang="en_GB">System policy prevents the PolicyKit-gnome example helper from Punching</message>
<message xml:lang="fi">Järjestelmäkäytäntö estää PolicyKit-gnomen esimerkkiavustinta näpäyttämästä</message>
<message xml:lang="fr">La stratégie système empêche l'assistant exemple de PolicyKit-gnome de frapper</message>
<message xml:lang="ja">System policy prevents the PolicyKit-gnome example helper from Punching</message>
<defaults>
<allow_inactive>no</allow_inactive>
<allow_active>auth_self_keep_session</allow_active>
</defaults>
</action>
<action id="org.gnome.policykit.examples.toggle">
<description>Toggle</description>
<description xml:lang="el">Εναλλαγή</description>
<description xml:lang="en_GB">Toggle</description>
<description xml:lang="fi">Kytke</description>
<description xml:lang="fr">Basculer</description>
<description xml:lang="ja">Toggle</description>
<description xml:lang="sv">Växla</description>
<message>System policy prevents the PolicyKit-gnome example helper from Toggling</message>
<message xml:lang="en_GB">System policy prevents the PolicyKit-gnome example helper from Toggling</message>
<message xml:lang="fi">Järjestelmäkäytäntö estää PolicyKit-gnomen esimerkkiavustinta kytkemästä</message>
<message xml:lang="fr">La stratégie système empêche l'assistant exemple de PolicyKit-gnome de basculer</message>
<message xml:lang="ja">System policy prevents the PolicyKit-gnome example helper from Toggling</message>
<defaults>
<allow_inactive>no</allow_inactive>
<allow_active>auth_admin_keep_always</allow_active>
</defaults>
</action>
<action id="org.gnome.policykit.examples.kick-foo">
<description>Kick foo</description>
<description xml:lang="en_GB">Kick foo</description>
<description xml:lang="fi">Potkaise foota</description>
<description xml:lang="fr">Pousser toto</description>
<description xml:lang="ja">Kick foo</description>
<message>System policy prevents the PolicyKit-gnome example helper from Kicking foo</message>
<message xml:lang="da">System indstillinger forhindrer PolicyKit-gnome eksempel hjælper fra at Sparke foo!</message>
<message xml:lang="en_GB">System policy prevents the PolicyKit-gnome example helper from Kicking foo</message>
<message xml:lang="fi">Järjestelmäkäytäntö estää PolicyKit-gnomen esimerkkiavustinta potkaisemasta foota</message>
<message xml:lang="fr">La stratégie système empêche l'assistant exemple de PolicyKit-gnome de pousser toto</message>
<message xml:lang="ja">System policy prevents the PolicyKit-gnome example helper from Kicking foo</message>
<defaults>
<allow_inactive>no</allow_inactive>
<allow_active>auth_self</allow_active>
</defaults>
<annotate key="org.gnome.policykit.examples.kick-path">foo</annotate>
</action>
<action id="org.gnome.policykit.examples.kick-bar">
<description>Kick bar</description>
<description xml:lang="en_GB">Kick bar</description>
<description xml:lang="fi">Potkaise baria</description>
<description xml:lang="fr">Pousser titi</description>
<description xml:lang="ja">Kick bar</description>
<message>System policy prevents the PolicyKit-gnome example helper from Kicking bar</message>
<message xml:lang="da">System indstillinger forhindrer PolicyKit-gnome eksempel hjælper fra at Sparke bar!</message>
<message xml:lang="en_GB">System policy prevents the PolicyKit-gnome example helper from Kicking bar</message>
<message xml:lang="fi">Järjestelmäkäytäntö estää PolicyKit-gnomen esimerkkiavustinta potkaisemasta baria</message>
<message xml:lang="fr">La stratégie système empêche l'assistant exemple de PolicyKit-gnome de pousser titi</message>
<message xml:lang="ja">System policy prevents the PolicyKit-gnome example helper from Kicking bar</message>
<defaults>
<allow_inactive>no</allow_inactive>
<allow_active>auth_self</allow_active>
</defaults>
<annotate key="org.gnome.policykit.examples.kick-path">bar</annotate>
</action>
<action id="org.gnome.policykit.examples.kick-baz">
<description>Kick baz</description>
<description xml:lang="en_GB">Kick baz</description>
<description xml:lang="fi">Potkaise bazia</description>
<description xml:lang="fr">Pousser tata</description>
<description xml:lang="ja">Kick baz</description>
<message>System policy prevents the PolicyKit-gnome example helper from Kicking baz</message>
<message xml:lang="da">System indstillinger forhindrer PolicyKit-gnome eksempel hjælper fra at Sparke baz!</message>
<message xml:lang="en_GB">System policy prevents the PolicyKit-gnome example helper from Kicking baz</message>
<message xml:lang="fi">Järjestelmäkäytäntö estää PolicyKit-gnomen esimerkkiavustinta potkaisemasta bazia</message>
<message xml:lang="fr">La stratégie système empêche l'assistant exemple de PolicyKit-gnome de pousser tata</message>
<message xml:lang="ja">System policy prevents the PolicyKit-gnome example helper from Kicking baz</message>
<defaults>
<allow_inactive>no</allow_inactive>
<allow_active>auth_self</allow_active>
</defaults>
<annotate key="org.gnome.policykit.examples.kick-path">baz</annotate>
</action>
</policyconfig>
into a file /usr/share/PolicyKit/policy/polkit-gnome-example.policy. Finally, run polkit-gnome-example. It should display a window like this:
If the "Twiddle!" button is pressed, an authentication dialog should pop up
Here is how what the application looks like if the user gains authorization for all the actions:
Regarding how to build an example mechanism that this GTK+ application can take advantage of, please refer to the PolKitContext class for examples.
typedef struct _PolKitGnomeAction PolKitGnomeAction;
The PolKitGnomeAction struct contains only private data members and should not be accessed directly.
PolKitGnomeAction* polkit_gnome_action_new (const gchar *name);
Creates a new PolKitGnomeAction object. The typical use for this function is for specialized use where polkit_gnome_action_new_default() does not meet the needs of the application. A short example of the usage of this contructor follows.
If the 'polkit-action' property is NULL the behavior is similar to as if a PolKitAction returned POLKIT_RESULT_YES.
One can set the 'polkit-action-sufficient' property to a GValueArray of pointers to PolKitAction objects. The semantics of this property is that if the user is authorized for any of the given actions in 'polkit-action-sufficient' then the behavior is the same as if they're authorized for the action denoted by 'polkit-action'. This is useful in a setup where you have two similar actions and one implies the other. For example, in gnome-system-monitor there are two actions org.gnome.system-monitor.increase-own-priority (Increase the priority of a process owned by yourself) and org.gnome.system-monitor.change-priorty (Change priority of any process). As the latter clearly implies the former, one would set the latter in the 'polkit-action-sufficient' property when constructing a PolKitAction for the former.
PolKitAction *polkit_action;
PolKitGnomeAction *action;
polkit_action = polkit_action_new ();
polkit_action_set_action_id (polkit_action, "org.example.some-policykit-action");
action = polkit_gnome_action_new ("blabla", NULL);
g_object_set (action,
"polkit-action", polkit_action,
"no-visible", TRUE,
"no-sensitive", FALSE,
"no-short-label", "The Action no can do!",
"no-label", "The Action is not permitted!",
"no-tooltip", "The Tooltip (no)",
"no-icon-name", GTK_STOCK_NO,
"auth-visible", TRUE,
"auth-sensitive", TRUE,
"auth-short-label", "The Action requires auth...",
"auth-label", "The Action requires auth...",
"auth-tooltip", "The Tooltip (auth)",
"auth-icon-name", GTK_STOCK_DIALOG_AUTHENTICATION,
"yes-visible", TRUE,
"yes-sensitive", TRUE,
"yes-short-label", "Action!",
"yes-label", "Just do the Action!",
"yes-tooltip", "The Tooltip (yes)",
"yes-icon-name", GTK_STOCK_YES,
NULL);
| name : | A unique name for the action |
| Returns : | a new PolKitGnomeAction or NULL if error is set |
PolKitGnomeAction* polkit_gnome_action_new_default (const gchar *name, PolKitAction *polkit_action, const gchar *label, const gchar *tooltip);
Creates a new PolKitGnomeAction object with the default behavior for a given PolKitAction object.
Default behavior is defined by the label and tooltip being identical across all three four states, the action being visible in all four states, and the action being insensitive only in the state where the result from PolicyKit is no and self-blocked. Only when PolicyKit returns one of the 'auth*' results, the icon_name property will be set to GTK_STOCK_DIALOG_AUTHENTICATION.
The caller can always modify individual aspects of the action after creation, e.g. change the tooltip for the self-blocked, no, auth and yes states.
If the given polkit_action is NULL the behavior is similar to as if a PolKitAction returned POLKIT_RESULT_YES.
| name : | A unique name for the action |
| polkit_action : | the PolKitAction to track |
| label : | the label to use (will also apply to short-label) |
| tooltip : | the tool tip to use |
| Returns : | a new PolKitGnomeAction or NULL if error is set |
PolKitResult polkit_gnome_action_get_polkit_result (PolKitGnomeAction *action);
Gets the PolKitResult that indicates whether the user is privileged to do the PolKitAction associated with this PolKitGnomeAction object.
| action : | The PolKitGnomeAction object |
| Returns : | The PolKitAction object. The caller shall not unref this object. |
gboolean polkit_gnome_action_get_sensitive (PolKitGnomeAction *action);
Get the master sensitivity, see PolKitGnomeAction:master-sensitive: for details.
| action : | The PolKitGnomeAction object |
| Returns : | the master sensitivity |
void polkit_gnome_action_set_sensitive (PolKitGnomeAction *action, gboolean sensitive);
Set the master sensitivity, see PolKitGnomeAction:master-sensitive: for details.
| action : | The PolKitGnomeAction object |
| sensitive : | master sensitivity |
gboolean polkit_gnome_action_get_visible (PolKitGnomeAction *action);
Get the master visibility, see PolKitGnomeAction:master-visible: for details.
| action : | The PolKitGnomeAction object |
| Returns : | the master visibility |
void polkit_gnome_action_set_visible (PolKitGnomeAction *action, gboolean visible);
Set the master visibility, see PolKitGnomeAction:master-visible: for details.
| action : | The PolKitGnomeAction object |
| visible : | master visibility |
GtkWidget* polkit_gnome_action_create_button (PolKitGnomeAction *action);
Create a button for the given action that displays the label, tooltip and icon_name corresponding to whether the state, according to PolicyKit, is no, auth or yes.
| action : | The PolKitGnomeAction object |
| Returns : | A GtkButton instance connected to the action |
"auth-icon-name" gchar* : Read / Write
If PolicyKit evaluates the result as 'auth', use this icon-name.
Default value: NULL
"auth-label" gchar* : Read / Write
If PolicyKit evaluates the result as 'auth', use this label.
Default value: NULL
"auth-sensitive" gboolean : Read / Write
If PolicyKit evaluates the result as 'auth', whether the action will be sensitive.
Default value: TRUE
"auth-short-label" gchar* : Read / Write
If PolicyKit evaluates the result as 'auth', use this short-label.
Default value: NULL
"auth-tooltip" gchar* : Read / Write
If PolicyKit evaluates the result as 'auth', use this tooltip.
Default value: NULL
"auth-visible" gboolean : Read / Write
If PolicyKit evaluates the result as 'auth', whether the action will be visible.
Default value: TRUE
"master-sensitive" gboolean : Read / Write
Can be set to FALSE to force insensitivity no matter what PolicyKit reports.
Default value: TRUE
"master-visible" gboolean : Read / Write
Can be set to FALSE to force invisibility no matter what PolicyKit reports.
Default value: TRUE
"no-icon-name" gchar* : Read / Write
If PolicyKit evaluates the result as 'no', use this icon-name.
Default value: NULL
"no-label" gchar* : Read / Write
If PolicyKit evaluates the result as 'no', use this label.
Default value: NULL
"no-sensitive" gboolean : Read / Write
If PolicyKit evaluates the result as 'no', whether the action will be sensitive.
Default value: FALSE
"no-short-label" gchar* : Read / Write
If PolicyKit evaluates the result as 'no', use this short-label.
Default value: NULL
"no-tooltip" gchar* : Read / Write
If PolicyKit evaluates the result as 'no', use this tooltip.
Default value: NULL
"no-visible" gboolean : Read / Write
If PolicyKit evaluates the result as 'no', whether the action will be visible.
Default value: TRUE
"polkit-action" gpointer : Read / Write / Construct
The PolKitAction object this GTK+ action is tracking.
"polkit-action-sufficient" GValueArray* : Read / Write / Construct
An array of PolKitAction objects that are sufficient to have authorizations for.
"self-blocked-icon-name" gchar* : Read / Write
If PolicyKit evaluates the result as 'no' and the reason is that the user has a self-granted negative authorization, use this icon-name.
Default value: NULL
"self-blocked-label" gchar* : Read / Write
If PolicyKit evaluates the result as 'no' and the reason is that the user has a self-granted negative authorization, use this label.
Default value: NULL
"self-blocked-sensitive" gboolean : Read / Write
If PolicyKit evaluates the result as 'no' and the reason is that the user has a self-granted negative authorization, whether the action will be sensitive.
Default value: FALSE
"self-blocked-short-label" gchar* : Read / Write
If PolicyKit evaluates the result as 'no' and the reason is that the user has a self-granted negative authorization, use this short-label.
Default value: NULL
"self-blocked-tooltip" gchar* : Read / Write
If PolicyKit evaluates the result as 'no' and the reason is that the user has a self-granted negative authorization, use this tooltip.
Default value: NULL
"self-blocked-visible" gboolean : Read / Write
If PolicyKit evaluates the result as 'no' and the reason is that the user has a self-granted negative authorization, whether the action will be visible.
Default value: TRUE
"target-pid" guint : Read / Write / Construct
The target process id to receive the authorization; if 0 it is the current process.
Default value: 0
"yes-icon-name" gchar* : Read / Write
If PolicyKit evaluates the result as 'yes', use this icon-name.
Default value: NULL
"yes-label" gchar* : Read / Write
If PolicyKit evaluates the result as 'yes', use this label.
Default value: NULL
"yes-sensitive" gboolean : Read / Write
If PolicyKit evaluates the result as 'yes', whether the action will be sensitive.
Default value: TRUE
"yes-short-label" gchar* : Read / Write
If PolicyKit evaluates the result as 'yes', use this short-label.
Default value: NULL
"yes-tooltip" gchar* : Read / Write
If PolicyKit evaluates the result as 'yes', use this tooltip.
Default value: NULL
"yes-visible" gboolean : Read / Write
If PolicyKit evaluates the result as 'yes', whether the action will be visible.
Default value: TRUE
void user_function (PolKitGnomeAction *action, gboolean gained_privilege, gpointer user_data) : Run Last
The ::auth-end signal is emitted when the an authentication session ends and carries information about whether the privilege was obtained or not.
| action : | the object |
| gained_privilege : | whether the privilege was gained |
| user_data : | user data set when the signal handler was connected. |
void user_function (PolKitGnomeAction *action, gpointer user_data) : Run Last
The ::auth-start signal is emitted when an authentication session starts.
| action : | the object |
| user_data : | user data set when the signal handler was connected. |
void user_function (PolKitGnomeAction *action, gint current_result, gpointer user_data) : Run Last
The ::polkit-result-changed signal is emitted when the PolicyKit result changes. This can happen when external factors (config file, ConsoleKit, privilege granted / revoked) change since the PolKitGnomeAction class listens for events using the PolKitGnomeContext class.
| action : | the object |
| current_result : | current PolKitResult from PolicyKit regarding given PolKitAction object |
| user_data : | user data set when the signal handler was connected. |