From: Alberto Mardegan Date: Wed, 30 Nov 2011 09:44:08 +0000 (+0200) Subject: Add GObject introspection tags X-Git-Tag: 1.2~27 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=bcd863cbc48f607e64b3d5958555718e325ad079;p=platform%2Fupstream%2Flibgsignon-glib.git Add GObject introspection tags At the same time, amend/extend the documentation. --- diff --git a/docs/reference/Makefile.am b/docs/reference/Makefile.am index 463ce44..a2dbb4d 100644 --- a/docs/reference/Makefile.am +++ b/docs/reference/Makefile.am @@ -44,7 +44,10 @@ CFILE_GLOB=$(top_srcdir)/libsignon-glib/*.c # Header files to ignore when scanning. # e.g. IGNORE_HFILES=gtkdebug.h gtkintl.h IGNORE_HFILES= \ + signon-dbus-queue.h \ + signon-internals.h \ signon-proxy.h \ + signon-utils.h \ so-marshal.h # Images to copy into HTML directory. diff --git a/libsignon-glib/signon-auth-service.c b/libsignon-glib/signon-auth-service.c index cc91189..e9df479 100644 --- a/libsignon-glib/signon-auth-service.c +++ b/libsignon-glib/signon-auth-service.c @@ -173,14 +173,15 @@ auth_query_mechanisms_cb (DBusGProxy *proxy, char **value, /** * signon_auth_service_query_methods: * @auth_service: the #SignonAuthService. - * @cb: callback to be invoke. + * @cb: (scope async): callback to be invoked. * @user_data: user data. * * Lists all the available methods. */ void signon_auth_service_query_methods (SignonAuthService *auth_service, - SignonQueryMethodsCb cb, gpointer user_data) + SignonQueryMethodsCb cb, + gpointer user_data) { g_return_if_fail (SIGNON_IS_AUTH_SERVICE (auth_service)); g_return_if_fail (cb != NULL); @@ -198,11 +199,13 @@ signon_auth_service_query_methods (SignonAuthService *auth_service, auth_query_methods_cb, cb_data); } + /** * signon_auth_service_query_mechanisms: * @auth_service: the #SignonAuthService. - * @method: the name of the method to get mechanisms. - * @cb: callback to be invoke. + * @method: the name of the method whose mechanisms must be + * retrieved. + * @cb: (scope async): callback to be invoked. * @user_data: user data. * * Lists all the available mechanisms. diff --git a/libsignon-glib/signon-auth-session.c b/libsignon-glib/signon-auth-session.c index 4d207f3..207dc73 100644 --- a/libsignon-glib/signon-auth-session.c +++ b/libsignon-glib/signon-auth-session.c @@ -22,6 +22,21 @@ * 02110-1301 USA */ +/** + * SECTION:signon-auth-session + * @title: SignonAuthSession + * @short_description: Authentication session handler. + * + * The #SignonAuthSession object is responsible for handling the client + * authentication. #SignonAuthSession objects can be created from existing + * identities (via signon_identity_create_session() or by passing a non-zero ID + * to signon_auth_session_new()), in which case the authentication data such as + * username and password will be implicitly taken from the identity, or they + * can be created with no existing identity bound to them, in which case all + * the authentication data must be filled in by the client when + * signon_auth_session_process() is called. + */ + #include "signon-internals.h" #include "signon-auth-session.h" #include "signon-dbus-queue.h" @@ -244,6 +259,19 @@ signon_auth_session_class_init (SignonAuthSessionClass *klass) object_class->finalize = signon_auth_session_finalize; } +/** + * signon_auth_session_new: + * @id: the id of the #SignonIdentity to be used. Can be 0, if this session is + * not bound to any stored identity. + * @method_name: the name of the authentication method to be used. + * @err: a pointer to a location which will contain the error, in case this + * function fails. + * + * Creates a new #SignonAuthSession, which can be used to authenticate using + * the specified method. + * + * Returns: a new #SignonAuthSession. + */ SignonAuthSession * signon_auth_session_new (gint id, const gchar *method_name, @@ -309,6 +337,12 @@ signon_auth_session_set_id(SignonAuthSession* self, GINT_TO_POINTER(id)); } +/** + * signon_auth_session_get_method: + * @self: the #SignonAuthSession. + * + * Returns: the authentication method being used. + */ const gchar * signon_auth_session_get_method (SignonAuthSession *self) { @@ -320,6 +354,17 @@ signon_auth_session_get_method (SignonAuthSession *self) return priv->method_name; } +/** + * signon_auth_session_query_available_mechanisms: + * @self: the #SignonAuthSession. + * @wanted_mechanisms: a %NULL-terminated list of mechanisms supported by the client. + * @cb: (scope async): a callback which will be called with the result. + * @user_data: user data to be passed to the callback. + * + * Queries the mechanisms available for this authentication session. the result + * will be the intersection between @wanted_mechanisms and the mechanisms + * supported by the authentication plugin. + */ void signon_auth_session_query_available_mechanisms (SignonAuthSession *self, const gchar **wanted_mechanisms, @@ -347,6 +392,21 @@ signon_auth_session_query_available_mechanisms (SignonAuthSession *self, operation_data); } +/** + * signon_auth_session_process: + * @self: the #SignonAuthSession. + * @session_data: (transfer none) (element-type utf8 GValue): a dictionary of parameters. + * @mechanism: the authentication mechanism to be used. + * @cb: (scope async): a callback which will be called with the result. + * @user_data: user data to be passed to the callback. + * + * Performs one step of the authentication process. If the #SignonAuthSession + * object is bound to an existing identity, the identity properties such as + * username and password will be also passed to the authentication plugin, so + * there's no need to fill them into @session_data. + * @session_data can be used to add additional authentication parameters to the + * session, or to override the parameters otherwise taken from the identity. + */ void signon_auth_session_process (SignonAuthSession *self, const GHashTable *session_data, diff --git a/libsignon-glib/signon-auth-session.h b/libsignon-glib/signon-auth-session.h index 9b4567f..cbbd507 100644 --- a/libsignon-glib/signon-auth-session.h +++ b/libsignon-glib/signon-auth-session.h @@ -97,7 +97,7 @@ G_GNUC_DEPRECATED typedef SignonAuthSessionQueryAvailableMechanismsCb SignonAuthSessionQueryAvailableMethodsCb; -void signon_auth_session_query_available_mechanisms(SignonAuthSession* self, +void signon_auth_session_query_available_mechanisms(SignonAuthSession *self, const gchar **wanted_mechanisms, SignonAuthSessionQueryAvailableMechanismsCb cb, gpointer user_data); diff --git a/libsignon-glib/signon-identity-info.c b/libsignon-glib/signon-identity-info.c index 3c773a7..2395e85 100644 --- a/libsignon-glib/signon-identity-info.c +++ b/libsignon-glib/signon-identity-info.c @@ -170,6 +170,13 @@ identity_ptrarray_to_identity_info (const GPtrArray *identity_array) * Public methods: */ +/** + * signon_identity_info_new: + * + * Creates a new SignonIdentityInfo item. + * + * Returns: a new #SignonIdentityInfo item. + */ SignonIdentityInfo *signon_identity_info_new () { SignonIdentityInfo *info = g_slice_new0 (SignonIdentityInfo); @@ -180,6 +187,12 @@ SignonIdentityInfo *signon_identity_info_new () return info; } +/** + * signon_identity_info_free: + * @info: the #SignonIdentityInfo. + * + * Destroys the given #SignonIdentityInfo item. + */ void signon_identity_info_free (SignonIdentityInfo *info) { if (info == NULL) return; @@ -196,6 +209,12 @@ void signon_identity_info_free (SignonIdentityInfo *info) g_slice_free (SignonIdentityInfo, info); } +/** + * signon_identity_info_copy: + * @other: the #SignonIdentityInfo. + * + * Returns: a copy of the given #SignonIdentityInfo. + */ SignonIdentityInfo *signon_identity_info_copy (const SignonIdentityInfo *other) { g_return_val_if_fail (other != NULL, NULL); @@ -226,48 +245,97 @@ SignonIdentityInfo *signon_identity_info_copy (const SignonIdentityInfo *other) return info; } +/** + * signon_identity_info_get_id: + * @info: the #SignonIdentityInfo. + * + * Returns: the numeric ID of the identity. + */ gint signon_identity_info_get_id (const SignonIdentityInfo *info) { g_return_val_if_fail (info != NULL, -1); return info->id; } +/** + * signon_identity_info_get_username: + * @info: the #SignonIdentityInfo. + * + * Returns: the username. + */ const gchar *signon_identity_info_get_username (const SignonIdentityInfo *info) { g_return_val_if_fail (info != NULL, NULL); return info->username; } +/** + * signon_identity_info_get_storing_secret: + * @info: the #SignonIdentityInfo. + * + * Returns: %TRUE if Signon must store the secret. + */ gboolean signon_identity_info_get_storing_secret (const SignonIdentityInfo *info) { g_return_val_if_fail (info != NULL, FALSE); return info->store_secret; } +/** + * signon_identity_info_get_caption: + * @info: the #SignonIdentityInfo. + * + * Returns: the display name for the identity. + */ const gchar *signon_identity_info_get_caption (const SignonIdentityInfo *info) { g_return_val_if_fail (info != NULL, NULL); return info->caption; } +/** + * signon_identity_info_get_methods: + * @info: the #SignonIdentityInfo. + * + * Returns: (transfer none) (element-type utf8 GStrv): the table of allowed + * methods and mechanisms. + */ const GHashTable *signon_identity_info_get_methods (const SignonIdentityInfo *info) { g_return_val_if_fail (info != NULL, NULL); return info->methods; } +/** + * signon_identity_info_get_realms: + * @info: the #SignonIdentityInfo. + * + * Returns: (transfer none): a %NULL terminated array of realms. + */ const gchar* const *signon_identity_info_get_realms (const SignonIdentityInfo *info) { g_return_val_if_fail (info != NULL, NULL); return (const gchar* const *)info->realms; } +/** + * signon_identity_info_get_access_control_list: + * @info: the #SignonIdentityInfo. + * + * Returns: (transfer none): a %NULL terminated array of ACL statements. + */ const gchar* const *signon_identity_info_get_access_control_list (const SignonIdentityInfo *info) { g_return_val_if_fail (info != NULL, NULL); return (const gchar* const *)info->access_control_list; } +/** + * signon_identity_info_get_identity_type: + * @info: the #SignonIdentityInfo. + * + * Returns: the type of the identity. + */ SignonIdentityType signon_identity_info_get_identity_type (const SignonIdentityInfo *info) { g_return_val_if_fail (info != NULL, -1); @@ -280,6 +348,13 @@ gint signon_identity_info_get_identity_ref_count (const SignonIdentityInfo *info return (SignonIdentityType)info->ref_count; } +/** + * signon_identity_info_set_username: + * @info: the #SignonIdentityInfo. + * @username: the username. + * + * Sets the username for the identity. + */ void signon_identity_info_set_username (SignonIdentityInfo *info, const gchar *username) { g_return_if_fail (info != NULL); @@ -289,6 +364,15 @@ void signon_identity_info_set_username (SignonIdentityInfo *info, const gchar *u info->username = g_strdup (username); } +/** + * signon_identity_info_set_secret: + * @info: the #SignonIdentityInfo. + * @secret: the secret. + * @store_secret: whether signond should store the secret in its DB. + * + * Sets the secret (password) for the identity, and whether the signon daemon + * should remember it. + */ void signon_identity_info_set_secret (SignonIdentityInfo *info, const gchar *secret, gboolean store_secret) { @@ -300,6 +384,13 @@ void signon_identity_info_set_secret (SignonIdentityInfo *info, const gchar *sec info->store_secret = store_secret; } +/** + * signon_identity_info_set_caption: + * @info: the #SignonIdentityInfo. + * @caption: the caption. + * + * Sets the caption (display name) for the identity. + */ void signon_identity_info_set_caption (SignonIdentityInfo *info, const gchar *caption) { g_return_if_fail (info != NULL); @@ -309,6 +400,16 @@ void signon_identity_info_set_caption (SignonIdentityInfo *info, const gchar *ca info->caption = g_strdup (caption); } +/** + * signon_identity_info_set_method: + * @info: the #SignonIdentityInfo. + * @method: an authentication method. + * @mechanisms: a %NULL-termianted list of mechanisms. + * + * Adds a method to the list of allowed methods. If this method is not called + * even once, then all methods are allowed. + * Mechanisms are method-specific variants of authentication. + */ void signon_identity_info_set_method (SignonIdentityInfo *info, const gchar *method, const gchar* const *mechanisms) { @@ -322,6 +423,14 @@ void signon_identity_info_set_method (SignonIdentityInfo *info, const gchar *met g_strdup(method), g_strdupv((gchar **)mechanisms)); } +/** + * signon_identity_info_remove_method: + * @info: the #SignonIdentityInfo. + * @method: an authentication method. + * + * Remove @method from the list of allowed authentication methods. If all + * methods are removed, then all methods are allowed. + */ void signon_identity_info_remove_method (SignonIdentityInfo *info, const gchar *method) { g_return_if_fail (info != NULL); @@ -330,6 +439,13 @@ void signon_identity_info_remove_method (SignonIdentityInfo *info, const gchar * g_hash_table_remove (info->methods, method); } +/** + * signon_identity_info_set_realms: + * @info: the #SignonIdentityInfo. + * @realms: a %NULL-terminated list of realms. + * + * Specify what realms this identity can be used in. + */ void signon_identity_info_set_realms (SignonIdentityInfo *info, const gchar* const *realms) { @@ -340,6 +456,14 @@ void signon_identity_info_set_realms (SignonIdentityInfo *info, info->realms = g_strdupv ((gchar **)realms); } +/** + * signon_identity_info_set_access_control_list: + * @info: the #SignonIdentityInfo. + * @access_control_list: a %NULL-terminated list of ACL security domains. + * + * Specifies the ACL for this identity. The actual meaning of the ACL depends + * on the security framework used by signond. + */ void signon_identity_info_set_access_control_list (SignonIdentityInfo *info, const gchar* const *access_control_list) { @@ -350,6 +474,13 @@ void signon_identity_info_set_access_control_list (SignonIdentityInfo *info, info->access_control_list = g_strdupv ((gchar **)access_control_list); } +/** + * signon_identity_info_set_identity_type: + * @info: the #SignonIdentityInfo. + * @type: the type of the identity. + * + * Specifies the type of this identity. + */ void signon_identity_info_set_identity_type (SignonIdentityInfo *info, SignonIdentityType type) { diff --git a/libsignon-glib/signon-identity.c b/libsignon-glib/signon-identity.c index e3dfed7..4a35132 100644 --- a/libsignon-glib/signon-identity.c +++ b/libsignon-glib/signon-identity.c @@ -524,7 +524,9 @@ identity_check_remote_registration (SignonIdentity *self) * signon_identity_new_from_db: * @id: identity ID. * - * Construct an identity object associated with an existing identity record. + * Construct an identity object associated with an existing identity + * record. + * * Returns: an instance of an #SignonIdentity. */ SignonIdentity* @@ -546,9 +548,10 @@ signon_identity_new_from_db (guint32 id) } /** - * signon_identity_new + * signon_identity_new: + * + * Construct new, empty, identity object. * - * Construct an identity object associated with an existing identity record. * Returns: an instance of an #SignonIdentity. */ SignonIdentity* @@ -580,16 +583,18 @@ identity_session_object_destroyed_cb(gpointer data, /** * signon_identity_create_session: - * @self: self. + * @self: the #SignonIdentity. * @method: method. - * @error: error. + * @error: pointer to a location which will receive the error, if any. * - * Construct an identity object associated with an existing identity record. - * Returns: an instance of an #SignonIdentity. + * Creates an authentication session for this identity. + * + * Returns: (transfer full): a new #SignonAuthSession. */ -SignonAuthSession *signon_identity_create_session(SignonIdentity *self, - const gchar *method, - GError **error) +SignonAuthSession * +signon_identity_create_session(SignonIdentity *self, + const gchar *method, + GError **error) { g_return_val_if_fail (SIGNON_IS_IDENTITY (self), NULL); @@ -649,19 +654,19 @@ SignonAuthSession *signon_identity_create_session(SignonIdentity *self, } /** - * signon_identity_store_credentials: - * @id: identity ID. - * @info: info. - * @cb: callback - * @user_data : user_data. + * signon_identity_store_credentials_with_info: + * @self: the #SignonIdentity. + * @info: the #SignonIdentityInfo data to store. + * @cb: (scope async): callback. + * @user_data: user_data. * - * Stores info for correspondent identity - * Returns: result + * Stores the data from @info into the identity. */ -void signon_identity_store_credentials_with_info(SignonIdentity *self, - const SignonIdentityInfo *info, - SignonIdentityStoreCredentialsCb cb, - gpointer user_data) +void +signon_identity_store_credentials_with_info(SignonIdentity *self, + const SignonIdentityInfo *info, + SignonIdentityStoreCredentialsCb cb, + gpointer user_data) { g_return_if_fail(info != NULL); @@ -690,20 +695,21 @@ identity_methods_to_valuearray (const GHashTable *methods) } /** - * signon_identity_store_credentials: - * @id: identity ID. + * signon_identity_store_credentials_with_args: + * @self: the #SignonIdentity. * @username: username. * @secret: secret. - * @store_secret: store secret flag. - * @methods: methods. + * @store_secret: whether signond should store the password. + * @methods: (transfer none) (element-type utf8 GStrv): methods. * @caption: caption. - * @realms: relams. + * @realms: realms. * @access_control_list: access control list. - * @cb: callback - * @user_data : user_data. + * @type: the type of the identity. + * @cb: (scope async): callback. + * @user_data: user_data. * - * Stores the given identity into credentials DB - */ + * Stores the given data into the identity. + */ void signon_identity_store_credentials_with_args(SignonIdentity *self, const gchar *username, const gchar *secret, @@ -982,34 +988,34 @@ identity_verify_data(SignonIdentity *self, } /** - * sigon_identity_verify_user: - * @message: message. - * @cb: callback - * @user_data : user_data. + * signon_identity_verify_user: + * @self: the #SignonIdentity. + * @username: the username to be verified. + * @cb: (scope async): callback. + * @user_data: user_data. * - * Verifies the given username - * gboolean result: is verified or not + * Verifies the given username. */ void signon_identity_verify_user(SignonIdentity *self, - const gchar *message, + const gchar *username, SignonIdentityVerifyCb cb, gpointer user_data) { identity_verify_data (self, - message, + username, SIGNON_VERIFY_USER, cb, user_data); } /** - * sigon_identity_verify_secret: - * @message: secret. - * @cb: callback - * @user_data : user_data. + * signon_identity_verify_secret: + * @self: the #SignonIdentity. + * @secret: the secret (password) to be verified. + * @cb: (scope async): callback. + * @user_data: user_data. * - * Verifies the given secret - * gboolean result: is verified or not + * Verifies the given secret. */ void signon_identity_verify_secret(SignonIdentity *self, const gchar *secret, @@ -1344,10 +1350,11 @@ identity_void_operation(SignonIdentity *self, /** * signon_identity_remove: - * @cb: callback + * @self: the #SignonIdentity. + * @cb: (scope async): callback. * @user_data: user_data. * - * Removes correspondent credentials record + * Removes correspondent credentials record from teh DB. */ void signon_identity_remove(SignonIdentity *self, SignonIdentityRemovedCb cb, @@ -1374,10 +1381,12 @@ void signon_identity_remove(SignonIdentity *self, /** * signon_identity_signout: - * @cb: callback + * @self: the #SignonIdentity. + * @cb: (scope async): callback. * @user_data: user_data. * - * Makes SignOut + * Asks signond to close all authentication sessions for this + * identity. */ void signon_identity_signout(SignonIdentity *self, SignonIdentitySignedOutCb cb, @@ -1449,11 +1458,13 @@ void signon_identity_remove_reference(SignonIdentity *self, } /** - * signon_identity_info: - * @cb: callback + * signon_identity_query_info: + * @self: the #SignonIdentity. + * @cb: (scope async): callback. * @user_data: user_data. * - * Returns info of the associated record in credentials DB (NULL for new identity) + * Fetches the #SignonIdentityInfo data associated with this + * identity. */ void signon_identity_query_info(SignonIdentity *self, SignonIdentityInfoCb cb, diff --git a/libsignon-glib/signon-identity.h b/libsignon-glib/signon-identity.h index 8a5b190..565ace1 100644 --- a/libsignon-glib/signon-identity.h +++ b/libsignon-glib/signon-identity.h @@ -79,21 +79,11 @@ typedef void (*SignonIdentityStoreCredentialsCb) (SignonIdentity *self, const GError *error, gpointer user_data); -/* - * Later, as the structure SignonIdentityInfo will be brought - * into use, we will announce signon_identity_store_credentials_with_args - * or just simple signon_identity_store_credentials - * */ void signon_identity_store_credentials_with_info(SignonIdentity *self, const SignonIdentityInfo *info, SignonIdentityStoreCredentialsCb cb, gpointer user_data); -/* - * Later, as the structure SignonIdentityInfo will be brought - * into use, we will announce signon_identity_store_credentials_with_args - * or just simple signon_identity_store_credentials - * */ void signon_identity_store_credentials_with_args(SignonIdentity *self, const gchar *username, const gchar *secret, @@ -112,7 +102,7 @@ typedef void (*SignonIdentityVerifyCb) (SignonIdentity *self, gpointer user_data); void signon_identity_verify_user(SignonIdentity *self, - const gchar *message, + const gchar *username, SignonIdentityVerifyCb cb, gpointer user_data);