At the same time, amend/extend the documentation.
# 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.
/**
* 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);
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.
* 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"
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,
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)
{
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,
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,
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);
* 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);
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;
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);
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);
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);
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)
{
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);
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)
{
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);
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)
{
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)
{
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)
{
* 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*
}
/**
- * 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*
/**
* 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);
}
/**
- * 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);
}
/**
- * 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,
}
/**
- * 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,
/**
* 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,
/**
* 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,
}
/**
- * 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,
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,
gpointer user_data);
void signon_identity_verify_user(SignonIdentity *self,
- const gchar *message,
+ const gchar *username,
SignonIdentityVerifyCb cb,
gpointer user_data);
projects / platform / upstream / libgsignon-glib.git / commitdiff