From 1dee00dd5a41efe4e53a05df7a13ca997e14911a Mon Sep 17 00:00:00 2001 From: Ghislain MARY Date: Fri, 5 Jun 2015 16:22:28 +0200 Subject: [PATCH] Add documentation for account creator. --- coreapi/account_creator.c | 8 +- coreapi/account_creator.h | 160 ++++++++++++++++++++++++++++++++++---- coreapi/xmlrpc.h | 5 ++ gtk/setupwizard.c | 1 + 4 files changed, 155 insertions(+), 19 deletions(-) diff --git a/coreapi/account_creator.c b/coreapi/account_creator.c index 800403cab..991b612fb 100644 --- a/coreapi/account_creator.c +++ b/coreapi/account_creator.c @@ -35,7 +35,7 @@ struct _LinphoneAccountCreator { char *domain; char *route; char *email; - int subscribe; + bool_t subscribe; }; LinphoneAccountCreator * linphone_account_creator_new(LinphoneCore *core, const char *xmlrpc_url) { @@ -85,11 +85,11 @@ const char * linphone_account_creator_get_email(const LinphoneAccountCreator *cr return creator->email; } -void linphone_account_creator_set_subscribe(LinphoneAccountCreator *creator, int subscribe) { +void linphone_account_creator_set_subscribe(LinphoneAccountCreator *creator, bool_t subscribe) { creator->subscribe = subscribe; } -int linphone_account_creator_get_subscribe(const LinphoneAccountCreator *creator) { +bool_t linphone_account_creator_get_subscribe(const LinphoneAccountCreator *creator) { return creator->subscribe; } @@ -190,7 +190,7 @@ LinphoneAccountCreatorStatus linphone_account_creator_validate(LinphoneAccountCr LinphoneXmlRpcArgString, identity, LinphoneXmlRpcArgString, creator->password, LinphoneXmlRpcArgString, creator->email, - LinphoneXmlRpcArgInt, creator->subscribe, + LinphoneXmlRpcArgInt, (creator->subscribe == TRUE) ? 1 : 0, LinphoneXmlRpcArgNone); linphone_xml_rpc_session_send_request(creator->xmlrpc_session, request); linphone_xml_rpc_request_unref(request); diff --git a/coreapi/account_creator.h b/coreapi/account_creator.h index f4c5faef2..953422f1d 100644 --- a/coreapi/account_creator.h +++ b/coreapi/account_creator.h @@ -31,39 +31,169 @@ extern "C" { * @{ */ -enum _LinphoneAccountCreatorStatus { +/** +* Enum describing the status of a LinphoneAccountCreator operation. +**/ +typedef enum _LinphoneAccountCreatorStatus { LinphoneAccountCreatorOk, LinphoneAccountCreatorFailed -}; - -typedef enum _LinphoneAccountCreatorStatus LinphoneAccountCreatorStatus; +} LinphoneAccountCreatorStatus; +/** + * The LinphoneAccountCreator object used to create an account on a server via XML-RPC. +**/ typedef struct _LinphoneAccountCreator LinphoneAccountCreator; +/** + * Callback used to notify the end of a LinphoneAccountCreator operation. + * @param[in] creator LinphoneAccountCreator object + * @param[in] status The status of the LinphoneAccountCreator operation that has just finished + * @param user_data A user data given when setting the callback. +**/ typedef void (*LinphoneAccountCreatorCb)(LinphoneAccountCreator *creator, LinphoneAccountCreatorStatus status, void *user_data); +/** + * Create a LinphoneAccountCreator. + * @param[in] core The LinphoneCore used for the XML-RPC communication + * @param[in] xmlrpc_url The URL to the XML-RPC server + * @return The new LinphoneAccountCreator object +**/ LINPHONE_PUBLIC LinphoneAccountCreator * linphone_account_creator_new(LinphoneCore *core, const char *xmlrpc_url); + +/** + * Destroy a LinphoneAccountCreator. + * @param[in] creator LinphoneAccountCreator object + * @param +**/ LINPHONE_PUBLIC void linphone_account_creator_destroy(LinphoneAccountCreator *creator); +/** + * Set the username. + * @param[in] creator LinphoneAccountCreator object + * @param[in] username The username to set +**/ LINPHONE_PUBLIC void linphone_account_creator_set_username(LinphoneAccountCreator *creator, const char *username); -LINPHONE_PUBLIC const char * linphone_account_creator_get_username(const LinphoneAccountCreator *creator); -LINPHONE_PUBLIC void linphone_account_creator_set_password(LinphoneAccountCreator *creator, const char *password); -LINPHONE_PUBLIC const char * linphone_account_creator_get_password(const LinphoneAccountCreator *creator); -LINPHONE_PUBLIC void linphone_account_creator_set_domain(LinphoneAccountCreator *creator, const char *domain); -LINPHONE_PUBLIC const char * linphone_account_creator_get_domain(const LinphoneAccountCreator *creator); -LINPHONE_PUBLIC void linphone_account_creator_set_route(LinphoneAccountCreator *creator, const char *route); -LINPHONE_PUBLIC const char * linphone_account_creator_get_route(const LinphoneAccountCreator *creator); -LINPHONE_PUBLIC void linphone_account_creator_set_email(LinphoneAccountCreator *creator, const char *email); -LINPHONE_PUBLIC const char * linphone_account_creator_get_email(const LinphoneAccountCreator *creator); -LINPHONE_PUBLIC void linphone_account_creator_set_subscribe(LinphoneAccountCreator *creator, int suscribre); -LINPHONE_PUBLIC int linphone_account_creator_get_subscribe(const LinphoneAccountCreator *creator); +/** + * Get the username. + * @param[in] creator LinphoneAccountCreator object + * @return The username of the LinphoneAccountCreator +**/ +LINPHONE_PUBLIC const char * linphone_account_creator_get_username(const LinphoneAccountCreator *creator); + +/** + * Set the password. + * @param[in] creator LinphoneAccountCreator object + * @param[in] password The password to set +**/ +LINPHONE_PUBLIC void linphone_account_creator_set_password(LinphoneAccountCreator *creator, const char *password); + +/** + * Get the password. + * @param[in] creator LinphoneAccountCreator object + * @return The password of the LinphoneAccountCreator +**/ +LINPHONE_PUBLIC const char * linphone_account_creator_get_password(const LinphoneAccountCreator *creator); + +/** + * Set the domain. + * @param[in] creator LinphoneAccountCreator object + * @param[in] domain The domain to set +**/ +LINPHONE_PUBLIC void linphone_account_creator_set_domain(LinphoneAccountCreator *creator, const char *domain); + +/** + * Get the domain. + * @param[in] creator LinphoneAccountCreator object + * @return The domain of the LinphoneAccountCreator +**/ +LINPHONE_PUBLIC const char * linphone_account_creator_get_domain(const LinphoneAccountCreator *creator); + +/** + * Set the route. + * @param[in] creator LinphoneAccountCreator object + * @param[in] route The route to set +**/ +LINPHONE_PUBLIC void linphone_account_creator_set_route(LinphoneAccountCreator *creator, const char *route); + +/** + * Get the route. + * @param[in] creator LinphoneAccountCreator object + * @return The route of the LinphoneAccountCreator +**/ +LINPHONE_PUBLIC const char * linphone_account_creator_get_route(const LinphoneAccountCreator *creator); + +/** + * Set the email. + * @param[in] creator LinphoneAccountCreator object + * @param[in] email The email to set +**/ +LINPHONE_PUBLIC void linphone_account_creator_set_email(LinphoneAccountCreator *creator, const char *email); + +/** + * Get the email. + * @param[in] creator LinphoneAccountCreator object + * @return The email of the LinphoneAccountCreator +**/ +LINPHONE_PUBLIC const char * linphone_account_creator_get_email(const LinphoneAccountCreator *creator); + +/** + * Set the subscribe (to the newsletter) field. + * @param[in] creator LinphoneAccountCreator object + * @param[in] subscribe A boolean telling whether to subscribe to the newsletter or not. +**/ +LINPHONE_PUBLIC void linphone_account_creator_set_subscribe(LinphoneAccountCreator *creator, bool_t subscribe); + +/** + * Get the subscribe (to the newsletter) field. + * @param[in] creator LinphoneAccountCreator object + * @return A boolean telling whether to subscribe to the newsletter or not. +**/ +LINPHONE_PUBLIC bool_t linphone_account_creator_get_subscribe(const LinphoneAccountCreator *creator); + +/** + * Set the callback called when the account existence test is finished. + * @param[in] creator LinphoneAccountCreator object + * @param[in] cb The callback called when the account existence test is finished + * @param[in] user_data The user data passed to the callback +**/ LINPHONE_PUBLIC void linphone_account_creator_set_test_existence_cb(LinphoneAccountCreator *creator, LinphoneAccountCreatorCb cb, void *user_data); + +/** + * Set the callback called when the account validation test is finished. + * @param[in] creator LinphoneAccountCreator object + * @param[in] cb The callback called when the account validation test is finished + * @param[in] user_data The user data passed to the callback +**/ LINPHONE_PUBLIC void linphone_account_creator_set_test_validation_cb(LinphoneAccountCreator *creator, LinphoneAccountCreatorCb cb, void *user_data); + +/** + * Set the callback called when the account creation is finished. + * @param[in] creator LinphoneAccountCreator object + * @param[in] cb The callback called when the account creation is finished + * @param[in] user_data The user data passed to the callback +**/ LINPHONE_PUBLIC void linphone_account_creator_set_validate_cb(LinphoneAccountCreator *creator, LinphoneAccountCreatorCb cb, void *user_data); +/** + * Send an XML-RPC request to test the existence of a Linphone account. + * @param[in] creator LinphoneAccountCreator object + * @return LinphoneAccountCreatorOk if the request has been sent, LinphoneAccountCreatorFailed otherwise +**/ LINPHONE_PUBLIC LinphoneAccountCreatorStatus linphone_account_creator_test_existence(LinphoneAccountCreator *creator); + +/** + * Send an XML-RPC request to test the validation of a Linphone account. + * @param[in] creator LinphoneAccountCreator object + * @return LinphoneAccountCreatorOk if the request has been sent, LinphoneAccountCreatorFailed otherwise +**/ LINPHONE_PUBLIC LinphoneAccountCreatorStatus linphone_account_creator_test_validation(LinphoneAccountCreator *creator); + +/** + * Send an XML-RPC request to create a Linphone account. + * @param[in] creator LinphoneAccountCreator object + * @return LinphoneAccountCreatorOk if the request has been sent, LinphoneAccountCreatorFailed otherwise +**/ LINPHONE_PUBLIC LinphoneAccountCreatorStatus linphone_account_creator_validate(LinphoneAccountCreator *creator); /** diff --git a/coreapi/xmlrpc.h b/coreapi/xmlrpc.h index de099b3fb..ce3dfe5bb 100644 --- a/coreapi/xmlrpc.h +++ b/coreapi/xmlrpc.h @@ -59,6 +59,11 @@ typedef struct _LinphoneXmlRpcRequest LinphoneXmlRpcRequest; **/ typedef struct _LinphoneXmlRpcSession LinphoneXmlRpcSession; +/** + * Callback used to notify the response to an XML-RPC request. + * @param[in] request LinphoneXmlRpcRequest object + * @param[in] user_data A user data given when setting the callback upon creation of the XML-RPC request. +**/ typedef void (*LinphoneXmlRpcResponseCb)(LinphoneXmlRpcRequest *request, void *user_data); diff --git a/gtk/setupwizard.c b/gtk/setupwizard.c index 0de93a957..a2ff13281 100644 --- a/gtk/setupwizard.c +++ b/gtk/setupwizard.c @@ -98,6 +98,7 @@ static void linphone_gtk_assistant_prepare(GtkWidget *assistant, GtkWidget *page linphone_proxy_config_set_route(cfg, linphone_account_creator_get_route(creator)); linphone_proxy_config_enable_publish(cfg, FALSE); linphone_proxy_config_enable_register(cfg, TRUE); + ms_free(identity_str); if (strcmp(linphone_account_creator_get_domain(creator), "sip.linphone.org") == 0) { linphone_proxy_config_enable_avpf(cfg,TRUE);