Authentication Dialogs

Authentication Dialogs — Show authentication dialogs to gain privileges

Synopsis

void                (*PolKitGnomeAuthCB)                (PolKitAction *action,
                                                         gboolean gained_privilege,
                                                         GError *error,
                                                         gpointer user_data);
gboolean            polkit_gnome_auth_obtain            (PolKitAction *action,
                                                         guint xid,
                                                         pid_t pid,
                                                         PolKitGnomeAuthCB callback,
                                                         gpointer user_data,
                                                         GError **error);

Description

Show authentication dialogs to gain privileges.

Details

PolKitGnomeAuthCB ()

void                (*PolKitGnomeAuthCB)                (PolKitAction *action,
                                                         gboolean gained_privilege,
                                                         GError *error,
                                                         gpointer user_data);

The type of the callback function for polkit_gnome_auth_show_dialog().

action :

the PolKitAction passed in polkit_gnome_auth_show_dialog()

gained_privilege :

whether the user gained the privilege. Set to FALSE if error is set. If set to TRUE, error will not be set.

error :

if the call failed, this parameter will be non-NULL. The callee shall free the error.

user_data :

user data

polkit_gnome_auth_obtain ()

gboolean            polkit_gnome_auth_obtain            (PolKitAction *action,
                                                         guint xid,
                                                         pid_t pid,
                                                         PolKitGnomeAuthCB callback,
                                                         gpointer user_data,
                                                         GError **error);

Applications can use this function to show a dialog for the user asking her to authenticate in order to gain privileges to do the given action. The authentication, for security reasons, happens in a separate process; this function is merely a wrapper around a D-Bus call across the session message bus to the org.freedesktop.PolicyKit.AuthenticationAgent service. Depending on the setup, this may be the Authentication Agent shipped with PolicyKit-gnome or it may be another implementation. For example, if the user is in KDE it may be an Authentication Agent using the Qt toolkit.

The Authentication Agent shipped with PolicyKit-gnome is described in this section.

This function is similar to the polkit_auth_obtain() function supplied in libpolkit-dbus except that this function is asynchronous.

action :

The PolKitAction to make the user authenticate for

xid :

X11 window ID for the window that the dialog will be transient for. If there is no window, pass 0.

pid :

Process ID of process to grant authorization to. Normally one wants to pass result of getpid().

callback :

Function to call when authentication is done

user_data :

Data to pass to the callback function

error :

Return location for error

Returns :

TRUE if the authentication session was scheduled to start. FALSE if error is set (and no callback will be made).