From c5c9af541454fa3575ba0fbb8e231600ae895656 Mon Sep 17 00:00:00 2001 From: David Zeuthen Date: Sun, 1 Feb 2009 20:44:43 -0500 Subject: [PATCH] add docs for PolkitBackendAuthority --- docs/polkitbackend/Makefile.am | 20 +- docs/polkitbackend/polkitbackend-sections.txt | 79 ++++++ docs/polkitbackend/polkitbackend.types | 4 + src/polkit/polkitauthority.c | 2 +- src/polkitbackend/polkitbackendauthority.c | 313 +++++++++++++++++++++--- src/polkitbackend/polkitbackendauthority.h | 132 ++++++---- src/polkitbackend/polkitbackendlocalauthority.c | 27 +- src/polkitbackend/polkitbackendlocalauthority.h | 19 +- 8 files changed, 484 insertions(+), 112 deletions(-) create mode 100644 docs/polkitbackend/polkitbackend-sections.txt create mode 100644 docs/polkitbackend/polkitbackend.types diff --git a/docs/polkitbackend/Makefile.am b/docs/polkitbackend/Makefile.am index 98c8cc0..8725334 100644 --- a/docs/polkitbackend/Makefile.am +++ b/docs/polkitbackend/Makefile.am @@ -59,11 +59,14 @@ HTML_IMAGES = \ # Extra options to supply to gtkdoc-fixref FIXXREF_OPTIONS= -MAINTAINERCLEANFILES = \ - *~ \ - Makefile.in \ - polkitbackend.types \ - polkit-*.txt \ +MAINTAINERCLEANFILES = \ + *~ \ + Makefile.in \ + polkitbackend-decl-list.txt \ + polkitbackend-decl.txt \ + polkitbackend-overrides.txt \ + polkitbackend-undeclared.txt \ + polkitbackend-undocumented.txt \ $(NULL) if ENABLE_GTK_DOC @@ -74,14 +77,17 @@ endif CLEANFILES += *~ \ polkitbackend-scan.* \ - polkitbackend.* \ + polkitbackend.args \ + polkitbackend.hierarchy \ + polkitbackend.interfaces \ + polkitbackend.prerequisites \ + polkitbackend.signals \ *.bak \ polkitbackend-decl-list.txt \ polkitbackend-decl.txt \ polkitbackend-overrides.txt \ polkitbackend-undeclared.txt \ polkitbackend-undocumented.txt \ - polkitbackend-sections.txt \ *.stamp \ -rf html xml \ $(NULL) diff --git a/docs/polkitbackend/polkitbackend-sections.txt b/docs/polkitbackend/polkitbackend-sections.txt new file mode 100644 index 0000000..4bbdb9a --- /dev/null +++ b/docs/polkitbackend/polkitbackend-sections.txt @@ -0,0 +1,79 @@ +
+polkitbackendauthority +PolkitBackendAuthority +PolkitBackendAuthority +PolkitBackendAuthorityClass +polkit_backend_authority_check_authorization +polkit_backend_authority_check_authorization_finish +polkit_backend_authority_register_authentication_agent +polkit_backend_authority_unregister_authentication_agent +polkit_backend_authority_authentication_agent_response +polkit_backend_authority_enumerate_actions +polkit_backend_authority_enumerate_users +polkit_backend_authority_enumerate_groups +polkit_backend_authority_enumerate_authorizations +polkit_backend_authority_add_authorization +polkit_backend_authority_remove_authorization +polkit_backend_authority_system_bus_name_owner_changed +polkit_backend_register_authority + +POLKIT_BACKEND_AUTHORITY +POLKIT_BACKEND_IS_AUTHORITY +POLKIT_BACKEND_TYPE_AUTHORITY +polkit_backend_authority_get_type +POLKIT_BACKEND_AUTHORITY_CLASS +POLKIT_BACKEND_IS_AUTHORITY_CLASS +POLKIT_BACKEND_AUTHORITY_GET_CLASS +
+ +
+polkitbackendlocalauthority +PolkitBackendLocalAuthority +PolkitBackendLocalAuthority +PolkitBackendLocalAuthorityClass +polkit_backend_local_authority_new + +POLKIT_BACKEND_LOCAL_AUTHORITY +POLKIT_BACKEND_IS_LOCAL_AUTHORITY +POLKIT_BACKEND_TYPE_LOCAL_AUTHORITY +polkit_backend_local_authority_get_type +POLKIT_BACKEND_LOCAL_AUTHORITY_CLASS +POLKIT_BACKEND_IS_LOCAL_AUTHORITY_CLASS +POLKIT_BACKEND_LOCAL_AUTHORITY_GET_CLASS +
+ +
+polkitbackendactionpool +PolkitBackendActionPool +PolkitBackendActionPool +polkit_backend_action_pool_new +polkit_backend_action_pool_get_all_actions +polkit_backend_action_pool_get_action + +POLKIT_BACKEND_ACTION_POOL +POLKIT_BACKEND_IS_ACTION_POOL +POLKIT_BACKEND_TYPE_ACTION_POOL +polkit_backend_action_pool_get_type +POLKIT_BACKEND_ACTION_POOL_CLASS +POLKIT_BACKEND_IS_ACTION_POOL_CLASS +POLKIT_BACKEND_ACTION_POOL_GET_CLASS +
+ +
+polkitbackendsessionmonitor +PolkitBackendSessionMonitor +polkit_backend_session_monitor_new +polkit_backend_session_monitor_get_sessions +polkit_backend_session_monitor_get_user_for_subject +polkit_backend_session_monitor_get_session_for_subject +polkit_backend_session_monitor_is_session_local +polkit_backend_session_monitor_is_session_active + +POLKIT_BACKEND_SESSION_MONITOR +POLKIT_BACKEND_IS_SESSION_MONITOR +POLKIT_BACKEND_TYPE_SESSION_MONITOR +polkit_backend_session_monitor_get_type +POLKIT_BACKEND_SESSION_MONITOR_CLASS +POLKIT_BACKEND_IS_SESSION_MONITOR_CLASS +POLKIT_BACKEND_SESSION_MONITOR_GET_CLASS +
diff --git a/docs/polkitbackend/polkitbackend.types b/docs/polkitbackend/polkitbackend.types new file mode 100644 index 0000000..9b16c54 --- /dev/null +++ b/docs/polkitbackend/polkitbackend.types @@ -0,0 +1,4 @@ +polkit_backend_authority_get_type +polkit_backend_local_authority_get_type +polkit_backend_action_pool_get_type +polkit_backend_session_monitor_get_type diff --git a/src/polkit/polkitauthority.c b/src/polkit/polkitauthority.c index 6bcedc7..aa09c10 100644 --- a/src/polkit/polkitauthority.c +++ b/src/polkit/polkitauthority.c @@ -244,7 +244,7 @@ polkit_authority_enumerate_actions (PolkitAuthority *authority, * * Finishes retrieving all registered actions. * - * Returns: A list of #PolkitActionDescription or %NULL if @error is set. The returned list + * 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(). **/ GList * diff --git a/src/polkitbackend/polkitbackendauthority.c b/src/polkitbackend/polkitbackendauthority.c index 5ab6a4f..996e87a 100644 --- a/src/polkitbackend/polkitbackendauthority.c +++ b/src/polkitbackend/polkitbackendauthority.c @@ -29,6 +29,17 @@ #include "polkitbackendprivate.h" +/** + * SECTION:polkitbackendauthority + * @title: PolkitBackendAuthority + * @short_description: Abstract base class for authority backends + * @stability: Unstable + * @see_also: PolkitBackendLocalAuthority + * + * To implement an authority backend, simply subclass #PolkitBackendAuthority + * and implement the required VFuncs. + */ + enum { CHANGED_SIGNAL, @@ -51,7 +62,7 @@ polkit_backend_authority_class_init (PolkitBackendAuthorityClass *klass) * PolkitBackendAuthority::changed: * @authority: A #PolkitBackendAuthority. * - * Emitted when actions and/or authorizations change + * Emitted when actions and/or authorizations change. */ signals[CHANGED_SIGNAL] = g_signal_new ("changed", POLKIT_BACKEND_TYPE_AUTHORITY, @@ -77,46 +88,129 @@ polkit_backend_authority_system_bus_name_owner_changed (PolkitBackendAuthority klass->system_bus_name_owner_changed (authority, name, old_owner, new_owner); } +/** + * polkit_backend_authority_enumerate_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. + * + * Retrieves all registered actions. + * + * 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(). + **/ GList * polkit_backend_authority_enumerate_actions (PolkitBackendAuthority *authority, PolkitSubject *caller, const gchar *locale, - GCancellable *cancellable, GError **error) { PolkitBackendAuthorityClass *klass; klass = POLKIT_BACKEND_AUTHORITY_GET_CLASS (authority); - return klass->enumerate_actions (authority, caller, locale, cancellable, error); + if (klass->enumerate_actions == NULL) + { + g_warning ("enumerate_actions is not implemented (it is not optional)"); + g_set_error (error, + POLKIT_ERROR, + POLKIT_ERROR_NOT_SUPPORTED, + "Operation not supported (bug in backend)"); + return NULL; + } + else + { + return klass->enumerate_actions (authority, caller, locale, error); + } } +/** + * polkit_backend_authority_enumerate_users: + * @authority: A #PolkitBackendAuthority. + * @caller: The system bus name that initiated the query. + * @error: Return location for error or %NULL. + * + * Enumerates all users known by @authority. + * + * Returns: A list of #PolkitIdentity 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(). + **/ GList * polkit_backend_authority_enumerate_users (PolkitBackendAuthority *authority, PolkitSubject *caller, - GCancellable *cancellable, GError **error) { PolkitBackendAuthorityClass *klass; klass = POLKIT_BACKEND_AUTHORITY_GET_CLASS (authority); - return klass->enumerate_users (authority, caller, cancellable, error); + if (klass->enumerate_users == NULL) + { + g_set_error (error, + POLKIT_ERROR, + POLKIT_ERROR_NOT_SUPPORTED, + "Operation not supported"); + return NULL; + } + else + { + return klass->enumerate_users (authority, caller, error); + } } +/** + * polkit_backend_authority_enumerate_groups: + * @authority: A #PolkitBackendAuthority. + * @caller: The system bus name that initiated the query. + * @error: Return location for error or %NULL. + * + * Enumerates all groups known by @authority. + * + * Returns: A list of #PolkitIdentity 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(). + **/ GList * polkit_backend_authority_enumerate_groups (PolkitBackendAuthority *authority, PolkitSubject *caller, - GCancellable *cancellable, GError **error) { PolkitBackendAuthorityClass *klass; klass = POLKIT_BACKEND_AUTHORITY_GET_CLASS (authority); - return klass->enumerate_groups (authority, caller, cancellable, error); + if (klass->enumerate_groups == NULL) + { + g_set_error (error, + POLKIT_ERROR, + POLKIT_ERROR_NOT_SUPPORTED, + "Operation not supported"); + return NULL; + } + else + { + return klass->enumerate_groups (authority, caller, error); + } } +/** + * polkit_backend_authority_check_authorization: + * @authority: A #PolkitBackendAuthority. + * @caller: The system bus name that initiated the query. + * @subject: A #PolkitSubject. + * @action_id: The action to check for. + * @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. + * + * 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. + **/ void polkit_backend_authority_check_authorization (PolkitBackendAuthority *authority, PolkitSubject *caller, @@ -131,9 +225,37 @@ polkit_backend_authority_check_authorization (PolkitBackendAuthority *aut klass = POLKIT_BACKEND_AUTHORITY_GET_CLASS (authority); - klass->check_authorization (authority, caller, subject, action_id, flags, cancellable, callback, user_data); + if (klass->check_authorization == NULL) + { + GSimpleAsyncResult *simple; + + g_warning ("check_authorization is not implemented (it is not optional)"); + + simple = g_simple_async_result_new_error (G_OBJECT (authority), + callback, + user_data, + POLKIT_ERROR, + POLKIT_ERROR_NOT_SUPPORTED, + "Operation not supported (bug in backend)"); + g_simple_async_result_complete (simple); + g_object_unref (simple); + } + else + { + klass->check_authorization (authority, caller, subject, action_id, flags, cancellable, callback, user_data); + } } +/** + * polkit_backend_authority_check_authorization_finish: + * @authority: A #PolkitBackendAuthority. + * @res: A #GAsyncResult obtained from the callback. + * @error: Return location for error or %NULL. + * + * Finishes checking if a subject is authorized for an action. + * + * Returns: A #PolkitAuthorizationResult. + **/ PolkitAuthorizationResult polkit_backend_authority_check_authorization_finish (PolkitBackendAuthority *authority, GAsyncResult *res, @@ -143,94 +265,234 @@ polkit_backend_authority_check_authorization_finish (PolkitBackendAuthority *au klass = POLKIT_BACKEND_AUTHORITY_GET_CLASS (authority); - return klass->check_authorization_finish (authority, res, error); + if (klass->check_authorization_finish == NULL) + { + g_warning ("check_authorization_finish is not implemented (it is not optional)"); + g_simple_async_result_propagate_error (G_SIMPLE_ASYNC_RESULT (res), error); + return POLKIT_AUTHORIZATION_RESULT_NOT_AUTHORIZED; + } + else + { + return klass->check_authorization_finish (authority, res, error); + } } +/** + * polkit_backend_authority_enumerate_authorizations: + * @authority: A #PolkitBackendAuthority. + * @caller: The system bus name that initiated the query. + * @identity: The identity to retrieve authorizations from. + * @error: Return location for error or %NULL. + * + * Retrieves all authorizations for @identity. + * + * Returns: A list of #PolkitAuthorization 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(). + **/ GList * polkit_backend_authority_enumerate_authorizations (PolkitBackendAuthority *authority, PolkitSubject *caller, PolkitIdentity *identity, - GCancellable *cancellable, GError **error) { PolkitBackendAuthorityClass *klass; klass = POLKIT_BACKEND_AUTHORITY_GET_CLASS (authority); - return klass->enumerate_authorizations (authority, caller, identity, cancellable, error); + if (klass->enumerate_authorizations == NULL) + { + g_set_error (error, + POLKIT_ERROR, + POLKIT_ERROR_NOT_SUPPORTED, + "Operation not supported"); + return NULL; + } + else + { + return klass->enumerate_authorizations (authority, caller, identity, error); + } } +/** + * polkit_backend_authority_add_authorization: + * @authority: A #PolkitBackendAuthority. + * @caller: The system bus name that initiated the query. + * @identity: The identity to add @authorization to. + * @authorization: The authorization to add. + * @error: Return location for error or %NULL. + * + * Adds @authorization to @identity. + * + * Returns: %TRUE if the operation succeeded or %FALSE if @error is set. + **/ gboolean polkit_backend_authority_add_authorization (PolkitBackendAuthority *authority, PolkitSubject *caller, PolkitIdentity *identity, PolkitAuthorization *authorization, - GCancellable *cancellable, GError **error) { PolkitBackendAuthorityClass *klass; klass = POLKIT_BACKEND_AUTHORITY_GET_CLASS (authority); - return klass->add_authorization (authority, caller, identity, authorization, cancellable, error); + if (klass->add_authorization == NULL) + { + g_set_error (error, + POLKIT_ERROR, + POLKIT_ERROR_NOT_SUPPORTED, + "Operation not supported"); + return FALSE; + } + else + { + return klass->add_authorization (authority, caller, identity, authorization, error); + } } +/** + * polkit_backend_authority_remove_authorization: + * @authority: A #PolkitBackendAuthority. + * @caller: The system bus name that initiated the query. + * @identity: The identity to remove @authorization from. + * @authorization: The authorization to remove. + * @error: Return location for error or %NULL. + * + * Removes @authorization from @identity. + * + * Returns: %TRUE if the operation succeeded or %FALSE if @error is set. + **/ gboolean polkit_backend_authority_remove_authorization (PolkitBackendAuthority *authority, PolkitSubject *caller, PolkitIdentity *identity, PolkitAuthorization *authorization, - GCancellable *cancellable, GError **error) { PolkitBackendAuthorityClass *klass; klass = POLKIT_BACKEND_AUTHORITY_GET_CLASS (authority); - return klass->remove_authorization (authority, caller, identity, authorization, cancellable, error); + if (klass->remove_authorization == NULL) + { + g_set_error (error, + POLKIT_ERROR, + POLKIT_ERROR_NOT_SUPPORTED, + "Operation not supported"); + return FALSE; + } + else + { + return klass->remove_authorization (authority, caller, identity, authorization, error); + } } +/** + * polkit_backend_authority_register_authentication_agent: + * @authority: A #PolkitBackendAuthority. + * @caller: The system bus name that initiated the query. + * @object_path: The object path for the authentication agent. + * @error: Return location for error or %NULL. + * + * Registers an authentication agent. + * + * Returns: %TRUE if the authentication agent was successfully registered, %FALSE if @error is set. + **/ gboolean polkit_backend_authority_register_authentication_agent (PolkitBackendAuthority *authority, PolkitSubject *caller, const gchar *object_path, - GCancellable *cancellable, GError **error) { PolkitBackendAuthorityClass *klass; klass = POLKIT_BACKEND_AUTHORITY_GET_CLASS (authority); - return klass->register_authentication_agent (authority, caller, object_path, cancellable, error); + if (klass->register_authentication_agent == NULL) + { + g_set_error (error, + POLKIT_ERROR, + POLKIT_ERROR_NOT_SUPPORTED, + "Operation not supported"); + return FALSE; + } + else + { + return klass->register_authentication_agent (authority, caller, object_path, error); + } } +/** + * polkit_backend_authority_unregister_authentication_agent: + * @authority: A #PolkitBackendAuthority. + * @caller: The system bus name that initiated the query. + * @object_path: The object path that the authentication agent is registered at. + * @error: Return location for error or %NULL. + * + * Unregisters an authentication agent. + * + * Returns: %TRUE if the authentication agent was successfully unregistered, %FALSE if @error is set. + **/ gboolean polkit_backend_authority_unregister_authentication_agent (PolkitBackendAuthority *authority, PolkitSubject *caller, const gchar *object_path, - GCancellable *cancellable, GError **error) { PolkitBackendAuthorityClass *klass; klass = POLKIT_BACKEND_AUTHORITY_GET_CLASS (authority); - return klass->unregister_authentication_agent (authority, caller, object_path, cancellable, error); + if (klass->unregister_authentication_agent == NULL) + { + g_set_error (error, + POLKIT_ERROR, + POLKIT_ERROR_NOT_SUPPORTED, + "Operation not supported"); + return FALSE; + } + else + { + return klass->unregister_authentication_agent (authority, caller, object_path, error); + } } +/** + * polkit_backend_authority_authentication_agent_response: + * @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. + * + * Provide response that @identity successfully authenticated for the + * authentication request identified by @cookie. + * + * Returns: %TRUE if @authority acknowledged the call, %FALSE if @error is set. + **/ gboolean polkit_backend_authority_authentication_agent_response (PolkitBackendAuthority *authority, PolkitSubject *caller, const gchar *cookie, PolkitIdentity *identity, - GCancellable *cancellable, GError **error) { PolkitBackendAuthorityClass *klass; klass = POLKIT_BACKEND_AUTHORITY_GET_CLASS (authority); - return klass->authentication_agent_response (authority, caller, cookie, identity, cancellable, error); + if (klass->authentication_agent_response == NULL) + { + g_set_error (error, + POLKIT_ERROR, + POLKIT_ERROR_NOT_SUPPORTED, + "Operation not supported"); + return FALSE; + } + else + { + return klass->authentication_agent_response (authority, caller, cookie, identity, error); + } } /* ---------------------------------------------------------------------------------------------------- */ @@ -355,7 +617,6 @@ authority_handle_enumerate_actions (_PolkitAuthority *instance, actions = polkit_backend_authority_enumerate_actions (server->authority, caller, locale, - NULL, &error); if (error != NULL) { @@ -407,7 +668,6 @@ authority_manager_handle_enumerate_users (_PolkitAuthorityManager *instance, identities = polkit_backend_authority_enumerate_users (server->authority, caller, - NULL, &error); if (error != NULL) { @@ -461,7 +721,6 @@ authority_manager_handle_enumerate_groups (_PolkitAuthorityManager *instance, identities = polkit_backend_authority_enumerate_groups (server->authority, caller, - NULL, &error); if (error != NULL) { @@ -574,7 +833,6 @@ authority_manager_handle_enumerate_authorizations (_PolkitAuthorityManager authorizations = polkit_backend_authority_enumerate_authorizations (server->authority, caller, identity, - NULL, &error); if (error != NULL) @@ -638,7 +896,6 @@ authority_manager_handle_add_authorization (_PolkitAuthorityManager *inst caller, identity, authorization, - NULL, &error)) { egg_dbus_method_invocation_return_gerror (method_invocation, error); @@ -680,7 +937,6 @@ authority_manager_handle_remove_authorization (_PolkitAuthorityManager *i caller, identity, authorization, - NULL, &error)) { egg_dbus_method_invocation_return_gerror (method_invocation, error); @@ -713,7 +969,6 @@ authority_handle_register_authentication_agent (_PolkitAuthority * if (!polkit_backend_authority_register_authentication_agent (server->authority, caller, object_path, - NULL, &error)) { egg_dbus_method_invocation_return_gerror (method_invocation, error); @@ -744,7 +999,6 @@ authority_handle_unregister_authentication_agent (_PolkitAuthority if (!polkit_backend_authority_unregister_authentication_agent (server->authority, caller, object_path, - NULL, &error)) { egg_dbus_method_invocation_return_gerror (method_invocation, error); @@ -780,7 +1034,6 @@ authority_handle_authentication_agent_response (_PolkitAuthority * caller, cookie, identity, - NULL, &error)) { egg_dbus_method_invocation_return_gerror (method_invocation, error); diff --git a/src/polkitbackend/polkitbackendauthority.h b/src/polkitbackend/polkitbackendauthority.h index dcef4cb..80d224e 100644 --- a/src/polkitbackend/polkitbackendauthority.h +++ b/src/polkitbackend/polkitbackendauthority.h @@ -40,42 +40,76 @@ G_BEGIN_DECLS typedef struct _PolkitBackendAuthorityClass PolkitBackendAuthorityClass; +/** + * PolkitBackendAuthority: + * + * The #PolkitBackendAuthority struct should not be accessed directly. + */ struct _PolkitBackendAuthority { GObject parent_instance; }; +/** + * PolkitBackendAuthorityClass: + * @parent_class: The parent class. + * @changed: Function pointer for #PolkitBackendAuthorityClass::changed signal. + * @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_users: Enumerates users on the system or %NULL if the + * backend doesn't support the operation. See + * polkit_backend_authority_enumerate_users() for details. + * @enumerate_groups: Enumerates groups on the system or %NULL if the + * backend doesn't support the operation. See + * polkit_backend_authority_enumerate_groups() for details. + * @enumerate_authorizations: Enumerates authorizations for a given + * identity or %NULL if the backend doesn't support the operation. See + * polkit_backend_authority_enumerate_authorizations() for details. + * @add_authorization: Add an authorization to a given identity or + * %NULL if the backend doesn't support the operation. See + * polkit_backend_authority_add_authorization() for details. + * @remove_authorization: Remove an authorization for a given identity + * or %NULL if the backend doesn't support the operation. See + * polkit_backend_authority_remove_authorization() for details. + * @system_bus_name_owner_changed: temporary VFunc, to be removed before 1.0. + * + * VFuncs that authority backends need to implement. + */ struct _PolkitBackendAuthorityClass { - GObjectClass parent_class; - /*< public >*/ + GObjectClass parent_class; /* Signals */ void (*changed) (PolkitBackendAuthority *authority); /* VTable */ - /* 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); - GList *(*enumerate_actions) (PolkitBackendAuthority *authority, PolkitSubject *caller, const gchar *locale, - GCancellable *cancellable, - GError **error); - - GList *(*enumerate_users) (PolkitBackendAuthority *authority, - PolkitSubject *caller, - GCancellable *cancellable, - GError **error); - - GList *(*enumerate_groups) (PolkitBackendAuthority *authority, - PolkitSubject *caller, - GCancellable *cancellable, GError **error); void (*check_authorization) (PolkitBackendAuthority *authority, @@ -91,44 +125,52 @@ struct _PolkitBackendAuthorityClass GAsyncResult *res, GError **error); + gboolean (*register_authentication_agent) (PolkitBackendAuthority *authority, + PolkitSubject *caller, + const gchar *object_path, + GError **error); + + gboolean (*unregister_authentication_agent) (PolkitBackendAuthority *authority, + PolkitSubject *caller, + const gchar *object_path, + GError **error); + + gboolean (*authentication_agent_response) (PolkitBackendAuthority *authority, + PolkitSubject *caller, + const gchar *cookie, + PolkitIdentity *identity, + GError **error); + + GList *(*enumerate_users) (PolkitBackendAuthority *authority, + PolkitSubject *caller, + GError **error); + + GList *(*enumerate_groups) (PolkitBackendAuthority *authority, + PolkitSubject *caller, + GError **error); + GList *(*enumerate_authorizations) (PolkitBackendAuthority *authority, PolkitSubject *caller, PolkitIdentity *identity, - GCancellable *cancellable, GError **error); gboolean (*add_authorization) (PolkitBackendAuthority *authority, PolkitSubject *caller, PolkitIdentity *identity, PolkitAuthorization *authorization, - GCancellable *cancellable, GError **error); gboolean (*remove_authorization) (PolkitBackendAuthority *authority, PolkitSubject *caller, PolkitIdentity *identity, PolkitAuthorization *authorization, - GCancellable *cancellable, GError **error); - gboolean (*register_authentication_agent) (PolkitBackendAuthority *authority, - PolkitSubject *caller, - const gchar *object_path, - GCancellable *cancellable, - GError **error); - - gboolean (*unregister_authentication_agent) (PolkitBackendAuthority *authority, - PolkitSubject *caller, - const gchar *object_path, - GCancellable *cancellable, - GError **error); - - gboolean (*authentication_agent_response) (PolkitBackendAuthority *authority, - PolkitSubject *caller, - const gchar *cookie, - PolkitIdentity *identity, - GCancellable *cancellable, - 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); /*< private >*/ /* Padding for future expansion */ @@ -154,17 +196,14 @@ void polkit_backend_authority_system_bus_name_owner_changed (PolkitBackendAu GList *polkit_backend_authority_enumerate_actions (PolkitBackendAuthority *authority, PolkitSubject *caller, const gchar *locale, - GCancellable *cancellable, GError **error); GList *polkit_backend_authority_enumerate_users (PolkitBackendAuthority *authority, PolkitSubject *caller, - GCancellable *cancellable, GError **error); GList *polkit_backend_authority_enumerate_groups (PolkitBackendAuthority *authority, PolkitSubject *caller, - GCancellable *cancellable, GError **error); void polkit_backend_authority_check_authorization (PolkitBackendAuthority *authority, @@ -183,40 +222,34 @@ PolkitAuthorizationResult polkit_backend_authority_check_authorization_finish (P GList *polkit_backend_authority_enumerate_authorizations (PolkitBackendAuthority *authority, PolkitSubject *caller, PolkitIdentity *identity, - GCancellable *cancellable, GError **error); gboolean polkit_backend_authority_add_authorization (PolkitBackendAuthority *authority, PolkitSubject *caller, PolkitIdentity *identity, PolkitAuthorization *authorization, - GCancellable *cancellable, GError **error); gboolean polkit_backend_authority_remove_authorization (PolkitBackendAuthority *authority, PolkitSubject *caller, PolkitIdentity *identity, PolkitAuthorization *authorization, - GCancellable *cancellable, GError **error); gboolean polkit_backend_authority_register_authentication_agent (PolkitBackendAuthority *authority, PolkitSubject *caller, const gchar *object_path, - GCancellable *cancellable, GError **error); gboolean polkit_backend_authority_unregister_authentication_agent (PolkitBackendAuthority *authority, PolkitSubject *caller, const gchar *object_path, - GCancellable *cancellable, GError **error); gboolean polkit_backend_authority_authentication_agent_response (PolkitBackendAuthority *authority, PolkitSubject *caller, const gchar *cookie, PolkitIdentity *identity, - GCancellable *cancellable, GError **error); /* --- */ @@ -229,4 +262,3 @@ gboolean polkit_backend_register_authority (PolkitBackendAuthority *authority, G_END_DECLS #endif /* __POLKIT_BACKEND_AUTHORITY_H */ - diff --git a/src/polkitbackend/polkitbackendlocalauthority.c b/src/polkitbackend/polkitbackendlocalauthority.c index 31557ca..4a23ea5 100644 --- a/src/polkitbackend/polkitbackendlocalauthority.c +++ b/src/polkitbackend/polkitbackendlocalauthority.c @@ -34,6 +34,15 @@ #include "_polkitagentbindings.h" #include +/** + * SECTION:polkitbackendlocalauthority + * @title: PolkitBackendLocalAuthority + * @short_description: Local Authority + * @stability: Unstable + * + * An implementation of #PolkitBackendAuthority that stores authorizations on the local file system + * and supports interaction with authentication agents. + */ typedef struct { @@ -134,17 +143,14 @@ static void polkit_backend_local_authority_system_bus_name_owner_changed (Polkit static GList *polkit_backend_local_authority_enumerate_actions (PolkitBackendAuthority *authority, PolkitSubject *caller, const gchar *locale, - GCancellable *cancellable, GError **error); static GList *polkit_backend_local_authority_enumerate_users (PolkitBackendAuthority *authority, PolkitSubject *caller, - GCancellable *cancellable, GError **error); static GList *polkit_backend_local_authority_enumerate_groups (PolkitBackendAuthority *authority, PolkitSubject *caller, - GCancellable *cancellable, GError **error); static void polkit_backend_local_authority_check_authorization (PolkitBackendAuthority *authority, @@ -171,40 +177,34 @@ static PolkitAuthorizationResult check_authorization_sync (PolkitBackendAuthorit static GList *polkit_backend_local_authority_enumerate_authorizations (PolkitBackendAuthority *authority, PolkitSubject *caller, PolkitIdentity *identity, - GCancellable *cancellable, GError **error); static gboolean polkit_backend_local_authority_add_authorization (PolkitBackendAuthority *authority, PolkitSubject *caller, PolkitIdentity *identity, PolkitAuthorization *authorization, - GCancellable *cancellable, GError **error); static gboolean polkit_backend_local_authority_remove_authorization (PolkitBackendAuthority *authority, PolkitSubject *caller, PolkitIdentity *identity, PolkitAuthorization *authorization, - GCancellable *cancellable, GError **error); static gboolean polkit_backend_local_authority_register_authentication_agent (PolkitBackendAuthority *authority, PolkitSubject *caller, const gchar *object_path, - GCancellable *cancellable, GError **error); static gboolean polkit_backend_local_authority_unregister_authentication_agent (PolkitBackendAuthority *authority, PolkitSubject *caller, const gchar *object_path, - GCancellable *cancellable, GError **error); static gboolean polkit_backend_local_authority_authentication_agent_response (PolkitBackendAuthority *authority, PolkitSubject *caller, const gchar *cookie, PolkitIdentity *identity, - GCancellable *cancellable, GError **error); /* ---------------------------------------------------------------------------------------------------- */ @@ -315,7 +315,6 @@ static GList * polkit_backend_local_authority_enumerate_actions (PolkitBackendAuthority *authority, PolkitSubject *caller, const gchar *locale, - GCancellable *cancellable, GError **error) { PolkitBackendLocalAuthority *local_authority; @@ -335,7 +334,6 @@ polkit_backend_local_authority_enumerate_actions (PolkitBackendAuthority *auth static GList * polkit_backend_local_authority_enumerate_users (PolkitBackendAuthority *authority, PolkitSubject *caller, - GCancellable *cancellable, GError **error) { PolkitBackendLocalAuthority *local_authority; @@ -380,7 +378,6 @@ polkit_backend_local_authority_enumerate_users (PolkitBackendAuthority *author static GList * polkit_backend_local_authority_enumerate_groups (PolkitBackendAuthority *authority, PolkitSubject *caller, - GCancellable *cancellable, GError **error) { PolkitBackendLocalAuthority *local_authority; @@ -868,7 +865,6 @@ static GList * polkit_backend_local_authority_enumerate_authorizations (PolkitBackendAuthority *authority, PolkitSubject *caller, PolkitIdentity *identity, - GCancellable *cancellable, GError **error) { PolkitBackendLocalAuthority *local_authority; @@ -899,7 +895,6 @@ polkit_backend_local_authority_add_authorization (PolkitBackendAuthority *auth PolkitSubject *caller, PolkitIdentity *identity, PolkitAuthorization *authorization, - GCancellable *cancellable, GError **error) { PolkitBackendLocalAuthority *local_authority; @@ -963,7 +958,6 @@ polkit_backend_local_authority_remove_authorization (PolkitBackendAuthority *a PolkitSubject *caller, PolkitIdentity *identity, PolkitAuthorization *authorization, - GCancellable *cancellable, GError **error) { PolkitBackendLocalAuthority *local_authority; @@ -1443,7 +1437,6 @@ static gboolean polkit_backend_local_authority_register_authentication_agent (PolkitBackendAuthority *authority, PolkitSubject *caller, const gchar *object_path, - GCancellable *cancellable, GError **error) { PolkitBackendLocalAuthority *local_authority; @@ -1508,7 +1501,6 @@ static gboolean polkit_backend_local_authority_unregister_authentication_agent (PolkitBackendAuthority *authority, PolkitSubject *caller, const gchar *object_path, - GCancellable *cancellable, GError **error) { PolkitBackendLocalAuthority *local_authority; @@ -1587,7 +1579,6 @@ polkit_backend_local_authority_authentication_agent_response (PolkitBackendAutho PolkitSubject *caller, const gchar *cookie, PolkitIdentity *identity, - GCancellable *cancellable, GError **error) { PolkitBackendLocalAuthority *local_authority; diff --git a/src/polkitbackend/polkitbackendlocalauthority.h b/src/polkitbackend/polkitbackendlocalauthority.h index 6f8e527..be0232f 100644 --- a/src/polkitbackend/polkitbackendlocalauthority.h +++ b/src/polkitbackend/polkitbackendlocalauthority.h @@ -39,22 +39,29 @@ G_BEGIN_DECLS #define POLKIT_BACKEND_IS_LOCAL_AUTHORITY(o) (G_TYPE_CHECK_INSTANCE_TYPE ((o), POLKIT_BACKEND_TYPE_LOCAL_AUTHORITY)) #define POLKIT_BACKEND_IS_LOCAL_AUTHORITY_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), POLKIT_BACKEND_TYPE_LOCAL_AUTHORITY)) -#if 0 -typedef struct _PolkitBackendLocalAuthority PolkitBackendLocalAuthority; -#endif - typedef struct _PolkitBackendLocalAuthorityClass PolkitBackendLocalAuthorityClass; +/** + * PolkitBackendLocalAuthority: + * + * The #PolkitBackendLocalAuthority struct should not be accessed directly. + */ struct _PolkitBackendLocalAuthority { + /*< private >*/ PolkitBackendAuthority parent_instance; }; +/** + * PolkitBackendLocalAuthorityClass: + * @parent_class: The parent class. + * + * Class structure for #PolkitBackendLocalAuthority. + */ struct _PolkitBackendLocalAuthorityClass { - PolkitBackendAuthorityClass parent_class; - /*< public >*/ + PolkitBackendAuthorityClass parent_class; /*< private >*/ /* Padding for future expansion */ -- 2.7.4