PolkitBackendAuthority

## PolkitBackendAuthority PolkitBackendAuthority — Abstract base class for authority backends |

## Stability Level

Unstable, unless otherwise indicated

## Synopsis

    #define             POLKIT_BACKEND_AUTHORITY_EXTENSION_POINT_NAME
                        PolkitBackendAuthority;
    struct              PolkitBackendAuthorityClass;
    const gchar *       polkit_backend_authority_get_name   (PolkitBackendAuthority *authority);
    const gchar *       polkit_backend_authority_get_version
                                                            (PolkitBackendAuthority *authority);
    PolkitAuthorityFeatures polkit_backend_authority_get_features
                                                            (PolkitBackendAuthority *authority);
    void                polkit_backend_authority_check_authorization
                                                            (PolkitBackendAuthority *authority,
                                                             PolkitSubject *caller,
                                                             PolkitSubject *subject,
                                                             const gchar *action_id,
                                                             PolkitDetails *details,
                                                             PolkitCheckAuthorizationFlags flags,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    PolkitAuthorizationResult * polkit_backend_authority_check_authorization_finish
                                                            (PolkitBackendAuthority *authority,
                                                             GAsyncResult *res,
                                                             GError **error);
    gboolean            polkit_backend_authority_register_authentication_agent
                                                            (PolkitBackendAuthority *authority,
                                                             PolkitSubject *caller,
                                                             PolkitSubject *subject,
                                                             const gchar *locale,
                                                             const gchar *object_path,
                                                             GVariant *options,
                                                             GError **error);
    gboolean            polkit_backend_authority_unregister_authentication_agent
                                                            (PolkitBackendAuthority *authority,
                                                             PolkitSubject *caller,
                                                             PolkitSubject *subject,
                                                             const gchar *object_path,
                                                             GError **error);
    gboolean            polkit_backend_authority_authentication_agent_response
                                                            (PolkitBackendAuthority *authority,
                                                             PolkitSubject *caller,
                                                             const gchar *cookie,
                                                             PolkitIdentity *identity,
                                                             GError **error);
    GList *             polkit_backend_authority_enumerate_actions
                                                            (PolkitBackendAuthority *authority,
                                                             PolkitSubject *caller,
                                                             const gchar *locale,
                                                             GError **error);
    GList *             polkit_backend_authority_enumerate_temporary_authorizations
                                                            (PolkitBackendAuthority *authority,
                                                             PolkitSubject *caller,
                                                             PolkitSubject *subject,
                                                             GError **error);
    gboolean            polkit_backend_authority_revoke_temporary_authorizations
                                                            (PolkitBackendAuthority *authority,
                                                             PolkitSubject *caller,
                                                             PolkitSubject *subject,
                                                             GError **error);
    gboolean            polkit_backend_authority_revoke_temporary_authorization_by_id
                                                            (PolkitBackendAuthority *authority,
                                                             PolkitSubject *caller,
                                                             const gchar *id,
                                                             GError **error);
    PolkitBackendAuthority * polkit_backend_authority_get   (void);
    gpointer            polkit_backend_authority_register   (PolkitBackendAuthority *authority,
                                                             GDBusConnection *connection,
                                                             const gchar *object_path,
                                                             GError **error);
    void                polkit_backend_authority_unregister (gpointer registration_id);

## Object Hierarchy

      GObject
       +----PolkitBackendAuthority
             +----PolkitBackendInteractiveAuthority

## Signals

      "changed"                                        : Run Last

## Description

To implement an authority backend, simply subclass PolkitBackendAuthority and implement the required VFuncs.

## Details

### POLKIT_BACKEND_AUTHORITY_EXTENSION_POINT_NAME

    #define POLKIT_BACKEND_AUTHORITY_EXTENSION_POINT_NAME "polkit-backend-authority-1"

Extension point name for authority backend implementations.

### PolkitBackendAuthority

    typedef struct _PolkitBackendAuthority PolkitBackendAuthority;

The PolkitBackendAuthority struct should not be accessed directly.

### struct PolkitBackendAuthorityClass

    struct PolkitBackendAuthorityClass {
      GObjectClass parent_class;

      /* Signals */
      void (*changed)  (PolkitBackendAuthority   *authority);

      /* VTable */

      const gchar             *(*get_name)     (PolkitBackendAuthority *authority);
      const gchar             *(*get_version)  (PolkitBackendAuthority *authority);
      PolkitAuthorityFeatures  (*get_features) (PolkitBackendAuthority *authority);

      GList *(*enumerate_actions)  (PolkitBackendAuthority   *authority,
                                    PolkitSubject            *caller,
                                    const gchar              *locale,
                                    GError                  **error);

      void (*check_authorization) (PolkitBackendAuthority        *authority,
                                   PolkitSubject                 *caller,
                                   PolkitSubject                 *subject,
                                   const gchar                   *action_id,
                                   PolkitDetails                 *details,
                                   PolkitCheckAuthorizationFlags  flags,
                                   GCancellable                  *cancellable,
                                   GAsyncReadyCallback            callback,
                                   gpointer                       user_data);

      PolkitAuthorizationResult * (*check_authorization_finish) (PolkitBackendAuthority  *authority,
                                                                 GAsyncResult            *res,
                                                                 GError                 **error);

      gboolean (*register_authentication_agent) (PolkitBackendAuthority   *authority,
                                                 PolkitSubject            *caller,
                                                 PolkitSubject            *subject,
                                                 const gchar              *locale,
                                                 const gchar              *object_path,
                                                 GVariant                 *options,
                                                 GError                  **error);

      gboolean (*unregister_authentication_agent) (PolkitBackendAuthority   *authority,
                                                   PolkitSubject            *caller,
                                                   PolkitSubject            *subject,
                                                   const gchar              *object_path,
                                                   GError                  **error);

      gboolean (*authentication_agent_response) (PolkitBackendAuthority   *authority,
                                                 PolkitSubject            *caller,
                                                 const gchar              *cookie,
                                                 PolkitIdentity           *identity,
                                                 GError                  **error);

      GList *(*enumerate_temporary_authorizations) (PolkitBackendAuthority   *authority,
                                                    PolkitSubject            *caller,
                                                    PolkitSubject            *subject,
                                                    GError                  **error);

      gboolean (*revoke_temporary_authorizations) (PolkitBackendAuthority   *authority,
                                                   PolkitSubject            *caller,
                                                   PolkitSubject            *subject,
                                                   GError                  **error);

      gboolean (*revoke_temporary_authorization_by_id) (PolkitBackendAuthority   *authority,
                                                        PolkitSubject            *caller,
                                                        const gchar              *id,
                                                        GError                  **error);
    };

Class structure for PolkitBackendAuthority.

GObjectClass `parent_class`; | The parent class.
`changed` () | Function pointer for "changed" signal.
`get_name` () | Function pointer for the `polkit_backend_authority_get_name()` function.
`get_version` () | Function pointer for the `polkit_backend_authority_get_version()` function.
`get_features` () | Function pointer for the `polkit_backend_authority_get_features()` function.
`enumerate_actions` () | Enumerates registered actions on the system. See `polkit_backend_authority_enumerate_actions()` for details.
`check_authorization` () | Called to initiate an asynchronous authorization check. See `polkit_backend_authority_check_authorization()` for details.
`check_authorization_finish` () | Called when finishing an authorization check. See `polkit_backend_authority_check_authorization_finish()` for details.
`register_authentication_agent` () | Called when an authentication agent is attempting to register or `NULL` if the backend doesn't support the operation. See `polkit_backend_authority_register_authentication_agent()` for details.
`unregister_authentication_agent` () | Called when an authentication agent is attempting to unregister or `NULL` if the backend doesn't support the operation. See `polkit_backend_authority_unregister_authentication_agent()` for details.
`authentication_agent_response` () | Called by an authentication agent when the user successfully authenticates or `NULL` if the backend doesn't support the operation. See `polkit_backend_authority_authentication_agent_response()` for details.
`enumerate_temporary_authorizations` () | Called to enumerate temporary authorizations or `NULL` if the backend doesn't support the operation. See `polkit_backend_authority_enumerate_temporary_authorizations()` for details.
`revoke_temporary_authorizations` () | Called to revoke temporary authorizations or `NULL` if the backend doesn't support the operation. See `polkit_backend_authority_revoke_temporary_authorizations()` for details.
`revoke_temporary_authorization_by_id` () | Called to revoke a temporary authorization identified by id or `NULL` if the backend doesn't support the operation. See `polkit_backend_authority_revoke_temporary_authorization_by_id()` for details.

### polkit_backend_authority_get_name ()

    const gchar *       polkit_backend_authority_get_name   (PolkitBackendAuthority *authority);

Gets the name of the authority backend.

`authority` : | A PolkitBackendAuthority.
Returns : | The name of the backend.

### polkit_backend_authority_get_version ()

    const gchar *       polkit_backend_authority_get_version
                                                            (PolkitBackendAuthority *authority);

Gets the version of the authority backend.

`authority` : | A PolkitBackendAuthority.
Returns : | The name of the backend.

### polkit_backend_authority_get_features ()

    PolkitAuthorityFeatures polkit_backend_authority_get_features
                                                            (PolkitBackendAuthority *authority);

Gets the features supported by the authority backend.

`authority` : | A PolkitBackendAuthority.
Returns : | Flags from PolkitAuthorityFeatures.

### polkit_backend_authority_check_authorization ()

    void                polkit_backend_authority_check_authorization
                                                            (PolkitBackendAuthority *authority,
                                                             PolkitSubject *caller,
                                                             PolkitSubject *subject,
                                                             const gchar *action_id,
                                                             PolkitDetails *details,
                                                             PolkitCheckAuthorizationFlags flags,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Asynchronously checks if `subject` is authorized to perform the action represented by `action_id`.

When the operation is finished, `callback` will be invoked. You can then call `polkit_backend_authority_check_authorization_finish()` to get the result of the operation.

`authority` : | A PolkitBackendAuthority.
`caller` : | The system bus name that initiated the query.
`subject` : | A PolkitSubject.
`action_id` : | The action to check for.
`details` : | Details about the action or `NULL`.
`flags` : | A set of PolkitCheckAuthorizationFlags.
`cancellable` : | A GCancellable.
`callback` : | A GAsyncReadyCallback to call when the request is satisfied.
`user_data` : | The data to pass to `callback`.

### polkit_backend_authority_check_authorization_finish ()

    PolkitAuthorizationResult * polkit_backend_authority_check_authorization_finish
                                                            (PolkitBackendAuthority *authority,
                                                             GAsyncResult *res,
                                                             GError **error);

Finishes checking if a subject is authorized for an action.

`authority` : | A PolkitBackendAuthority.
`res` : | A GAsyncResult obtained from the callback.
`error` : | Return location for error or `NULL`.
Returns : | A PolkitAuthorizationResult or `NULL` if `error` is set. Free with `g_object_unref()`.

### polkit_backend_authority_register_authentication_agent ()

    gboolean            polkit_backend_authority_register_authentication_agent
                                                            (PolkitBackendAuthority *authority,
                                                             PolkitSubject *caller,
                                                             PolkitSubject *subject,
                                                             const gchar *locale,
                                                             const gchar *object_path,
                                                             GVariant *options,
                                                             GError **error);

Registers an authentication agent.

`authority` : | A PolkitBackendAuthority.
`caller` : | The system bus name that initiated the query.
`subject` : | The subject the authentication agent wants to register for.
`locale` : | The locale of the authentication agent.
`object_path` : | The object path for the authentication agent.
`options` : | A GVariant with options or `NULL`.
`error` : | Return location for error or `NULL`.
Returns : | `TRUE` if the authentication agent was successfully registered, `FALSE` if `error` is set.

### polkit_backend_authority_unregister_authentication_agent ()

    gboolean            polkit_backend_authority_unregister_authentication_agent
                                                            (PolkitBackendAuthority *authority,
                                                             PolkitSubject *caller,
                                                             PolkitSubject *subject,
                                                             const gchar *object_path,
                                                             GError **error);

Unregisters an authentication agent.

`authority` : | A PolkitBackendAuthority.
`caller` : | The system bus name that initiated the query.
`subject` : | The subject the agent claims to be registered at.
`object_path` : | The object path that the authentication agent is registered at.
`error` : | Return location for error or `NULL`.
Returns : | `TRUE` if the authentication agent was successfully unregistered, `FALSE` if `error` is set.

### polkit_backend_authority_authentication_agent_response ()

    gboolean            polkit_backend_authority_authentication_agent_response
                                                            (PolkitBackendAuthority *authority,
                                                             PolkitSubject *caller,
                                                             const gchar *cookie,
                                                             PolkitIdentity *identity,
                                                             GError **error);

Provide response that `identity` successfully authenticated for the authentication request identified by `cookie`.

`authority` : | A PolkitBackendAuthority.
`caller` : | The system bus name that initiated the query.
`cookie` : | The cookie passed to the authentication agent from the authority.
`identity` : | The identity that was authenticated.
`error` : | Return location for error or `NULL`.
Returns : | `TRUE` if `authority` acknowledged the call, `FALSE` if `error` is set.

### polkit_backend_authority_enumerate_actions ()

    GList *             polkit_backend_authority_enumerate_actions
                                                            (PolkitBackendAuthority *authority,
                                                             PolkitSubject *caller,
                                                             const gchar *locale,
                                                             GError **error);

Retrieves all registered actions.

`authority` : | A PolkitBackendAuthority.
`caller` : | The system bus name that initiated the query.
`locale` : | The locale to retrieve descriptions for.
`error` : | Return location for error or `NULL`.
Returns : | A list of PolkitActionDescription objects or `NULL` if `error` is set. The returned list should be freed with `g_list_free()` after each element have been freed with `g_object_unref()`.

### polkit_backend_authority_enumerate_temporary_authorizations ()

    GList *             polkit_backend_authority_enumerate_temporary_authorizations
                                                            (PolkitBackendAuthority *authority,
                                                             PolkitSubject *caller,
                                                             PolkitSubject *subject,
                                                             GError **error);

Gets temporary authorizations for `subject`.

`authority` : | A PolkitBackendAuthority.
`caller` : | The system bus name that initiated the query.
`subject` : | The subject to get temporary authorizations for.
`error` : | Return location for error.
Returns : | A list of PolkitTemporaryAuthorization objects or `NULL` if `error` is set. The returned list should be freed with `g_list_free()` after each element have been freed with `g_object_unref()`.

### polkit_backend_authority_revoke_temporary_authorizations ()

    gboolean            polkit_backend_authority_revoke_temporary_authorizations
                                                            (PolkitBackendAuthority *authority,
                                                             PolkitSubject *caller,
                                                             PolkitSubject *subject,
                                                             GError **error);

Revokes temporary authorizations for `subject`.

`authority` : | A PolkitBackendAuthority.
`caller` : | The system bus name that initiated the query.
`subject` : | The subject to revoke temporary authorizations for.
`error` : | Return location for error.
Returns : | `TRUE` if the operation succeeded, `FALSE` if `error` is set.

### polkit_backend_authority_revoke_temporary_authorization_by_id ()

    gboolean            polkit_backend_authority_revoke_temporary_authorization_by_id
                                                            (PolkitBackendAuthority *authority,
                                                             PolkitSubject *caller,
                                                             const gchar *id,
                                                             GError **error);

Revokes a temporary authorizations with opaque identifier `id`.

`authority` : | A PolkitBackendAuthority.
`caller` : | The system bus name that initiated the query.
`id` : | The opaque identifier of the temporary authorization.
`error` : | Return location for error.
Returns : | `TRUE` if the operation succeeded, `FALSE` if `error` is set.

### polkit_backend_authority_get ()

    PolkitBackendAuthority * polkit_backend_authority_get   (void);

Loads all GIOModules from `$(libdir)/polkit-1/extensions` to determine what implementation of PolkitBackendAuthority to use. Then instantiates an object of the implementation with the highest priority and unloads all other modules.

Returns : | A PolkitBackendAuthority. Free with `g_object_unref()`.

### polkit_backend_authority_register ()

    gpointer            polkit_backend_authority_register   (PolkitBackendAuthority *authority,
                                                             GDBusConnection *connection,
                                                             const gchar *object_path,
                                                             GError **error);

Registers `authority` on a GDBusConnection.

`connection` : | The GDBusConnection to register the authority on.
`authority` : | A PolkitBackendAuthority.
`object_path` : | Object path of the authority.
`error` : | Return location for error.
Returns : | A gpointer that can be used with `polkit_backend_authority_unregister()` or `NULL` if `error` is set.

### polkit_backend_authority_unregister ()

    void                polkit_backend_authority_unregister (gpointer registration_id);

Unregisters a PolkitBackendAuthority registered with `polkit_backend_authority_register()`.

`registration_id` : | A gpointer obtained from `polkit_backend_authority_register()`.

## Signal Details

### The `"changed"` signal

    void                user_function                      (PolkitBackendAuthority *authority,
                                                            gpointer                user_data)      : Run Last

Emitted when actions and/or authorizations change.

`authority` : | A PolkitBackendAuthority.
`user_data` : | user data set when the signal handler was connected.

## See Also

PolkitBackendLocalAuthority