## 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).