PolkitBackendAuthority

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

## Stability Level

Unstable, unless otherwise indicated

## Synopsis

    #define             POLKIT_BACKEND_AUTHORITY_EXTENSION_POINT_NAME
                        PolkitBackendAuthority;
                        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,
                                                             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);
    void                polkit_backend_authority_system_bus_name_owner_changed
                                                            (PolkitBackendAuthority *authority,
                                                             const gchar *name,
                                                             const gchar *old_owner,
                                                             const gchar *new_owner);
    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);
    void                polkit_backend_authority_add_lockdown_for_action
                                                            (PolkitBackendAuthority *authority,
                                                             PolkitSubject *caller,
                                                             const gchar *action_id,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            polkit_backend_authority_add_lockdown_for_action_finish
                                                            (PolkitBackendAuthority *authority,
                                                             GAsyncResult *res,
                                                             GError **error);
    void                polkit_backend_authority_remove_lockdown_for_action
                                                            (PolkitBackendAuthority *authority,
                                                             PolkitSubject *caller,
                                                             const gchar *action_id,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            polkit_backend_authority_remove_lockdown_for_action_finish
                                                            (PolkitBackendAuthority *authority,
                                                             GAsyncResult *res,
                                                             GError **error);
    PolkitBackendAuthority * polkit_backend_authority_get   (void);
    gboolean            polkit_backend_register_authority   (PolkitBackendAuthority *authority,
                                                             const gchar *well_known_name,
                                                             const gchar *object_path,
                                                             GError **error);

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

### PolkitBackendAuthorityClass

    typedef struct {
      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,
                                                 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);

      void (*add_lockdown_for_action) (PolkitBackendAuthority  *authority,
                                       PolkitSubject           *caller,
                                       const gchar             *action_id,
                                       GAsyncReadyCallback      callback,
                                       gpointer                 user_data);

      gboolean (*add_lockdown_for_action_finish) (PolkitBackendAuthority  *authority,
                                                  GAsyncResult            *res,
                                                  GError                 **error);

      void (*remove_lockdown_for_action) (PolkitBackendAuthority  *authority,
                                          PolkitSubject           *caller,
                                          const gchar             *action_id,
                                          GAsyncReadyCallback      callback,
                                          gpointer                 user_data);

      gboolean (*remove_lockdown_for_action_finish) (PolkitBackendAuthority  *authority,
                                                     GAsyncResult            *res,
                                                     GError                 **error);

      /* TODO: need something more efficient such that we don't watch all name changes */
      void (*system_bus_name_owner_changed)  (PolkitBackendAuthority   *authority,
                                              const gchar              *name,
                                              const gchar              *old_owner,
                                              const gchar              *new_owner);
    } PolkitBackendAuthorityClass;

VFuncs that authority backends need to implement.

GObjectClass `parent_class`; | The parent class.
`changed` () | Function pointer for "changed" signal.
`get_name` () |
`get_version` () |
`get_features` () |
`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.
`add_lockdown_for_action` () | Called to add lock down for an action. See `polkit_backend_authority_add_lockdown_for_action()` for details. Can be `NULL` if not supported by the backend.
`add_lockdown_for_action_finish` () | Called to finish adding lock down for an an action. See `polkit_backend_authority_add_lockdown_for_action_finish()` for details. Can be `NULL` if not supported by the backend.
`remove_lockdown_for_action` () | Called when removing lock down for an action. See `polkit_backend_authority_remove_lockdown_for_action()` for details. Can be `NULL` if not supported by the backend.
`remove_lockdown_for_action_finish` () | Called to finish removing lock down for an action. See `polkit_backend_authority_remove_lockdown_for_action_finish()` for details. Can be `NULL` if not supported by the backend.
`system_bus_name_owner_changed` () | temporary VFunc, to be removed before API is declared stable.

### 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,
                                                             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.
`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_system_bus_name_owner_changed ()

    void                polkit_backend_authority_system_bus_name_owner_changed
                                                            (PolkitBackendAuthority *authority,
                                                             const gchar *name,
                                                             const gchar *old_owner,
                                                             const gchar *new_owner);

### 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_add_lockdown_for_action ()

    void                polkit_backend_authority_add_lockdown_for_action
                                                            (PolkitBackendAuthority *authority,
                                                             PolkitSubject *caller,
                                                             const gchar *action_id,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Asynchronously add locks down for `action_id`.

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

`authority` : | A PolkitBackendAuthority.
`caller` : | The system bus name that called the method.
`action_id` : | The action id.
`callback` : | A GAsyncReadyCallback to call when the request is satisfied.
`user_data` : | The data to pass to `callback`.

### polkit_backend_authority_add_lockdown_for_action_finish ()

    gboolean            polkit_backend_authority_add_lockdown_for_action_finish
                                                            (PolkitBackendAuthority *authority,
                                                             GAsyncResult *res,
                                                             GError **error);

Finishes adding lock down for an action.

`authority` : | A PolkitBackendAuthority.
`res` : | A GAsyncResult obtained from the callback.
`error` : | Return location for error or `NULL`.
Returns : | `TRUE` if the operation succeeded or, `FALE` if `error` is set.

### polkit_backend_authority_remove_lockdown_for_action ()

    void                polkit_backend_authority_remove_lockdown_for_action
                                                            (PolkitBackendAuthority *authority,
                                                             PolkitSubject *caller,
                                                             const gchar *action_id,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Asynchronously remove locks down for `action_id`.

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

`authority` : | A PolkitBackendAuthority.
`caller` : | The system bus name that called the method.
`action_id` : | The action id.
`callback` : | A GAsyncReadyCallback to call when the request is satisfied.
`user_data` : | The data to pass to `callback`.

### polkit_backend_authority_remove_lockdown_for_action_finish ()

    gboolean            polkit_backend_authority_remove_lockdown_for_action_finish
                                                            (PolkitBackendAuthority *authority,
                                                             GAsyncResult *res,
                                                             GError **error);

Finishes removing lock down for an action.

`authority` : | A PolkitBackendAuthority.
`res` : | A GAsyncResult obtained from the callback.
`error` : | Return location for error or `NULL`.
Returns : | `TRUE` if the operation succeeded or, `FALE` 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_register_authority ()

    gboolean            polkit_backend_register_authority   (PolkitBackendAuthority *authority,
                                                             const gchar *well_known_name,
                                                             const gchar *object_path,
                                                             GError **error);

Registers `authority` on the system message bus.

`authority` : | A PolkitBackendAuthority.
`well_known_name` : | Well-known name to claim on the system bus or `NULL` to not claim a well-known name.
`object_path` : | Object path of the authority.
`error` : | Return location for error.
Returns : | `TRUE` if `authority` was registered, `FALSE` if `error` is set.

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