Commit 8276aa27 authored by smorlat's avatar smorlat

Add API docs for liblinphone.

git-svn-id: svn+ssh://svn.savannah.nongnu.org/linphone/trunk@785 3f6dc0c8-ddfe-455d-9043-3cd528dc4637
parent 27b8fa41
......@@ -30,6 +30,17 @@
extern LinphoneProxyConfig *linphone_core_get_proxy_config_from_rid(LinphoneCore *lc, int rid);
/**
* @addtogroup authentication
* @{
**/
/**
* Create a LinphoneAuthInfo object with supplied information.
*
* The object can be created empty, that is with all arguments set to NULL.
* Username, userid, password and realm can be set later using specific methods.
**/
LinphoneAuthInfo *linphone_auth_info_new(const char *username, const char *userid,
const char *passwd, const char *ha1,const char *realm)
{
......@@ -44,6 +55,9 @@ LinphoneAuthInfo *linphone_auth_info_new(const char *username, const char *useri
return obj;
}
/**
* Sets the password.
**/
void linphone_auth_info_set_passwd(LinphoneAuthInfo *info, const char *passwd){
if (info->passwd!=NULL) {
ms_free(info->passwd);
......@@ -52,6 +66,9 @@ void linphone_auth_info_set_passwd(LinphoneAuthInfo *info, const char *passwd){
if (passwd!=NULL && (strlen(passwd)>0)) info->passwd=ms_strdup(passwd);
}
/**
* Sets the username.
**/
void linphone_auth_info_set_username(LinphoneAuthInfo *info, const char *username){
if (info->username){
ms_free(info->username);
......@@ -60,6 +77,9 @@ void linphone_auth_info_set_username(LinphoneAuthInfo *info, const char *usernam
if (username && strlen(username)>0) info->username=ms_strdup(username);
}
/**
* Sets userid.
**/
void linphone_auth_info_set_userid(LinphoneAuthInfo *info, const char *userid){
if (info->userid){
ms_free(info->userid);
......@@ -68,6 +88,9 @@ void linphone_auth_info_set_userid(LinphoneAuthInfo *info, const char *userid){
if (userid && strlen(userid)>0) info->userid=ms_strdup(userid);
}
/**
* Destroys a LinphoneAuthInfo object.
**/
void linphone_auth_info_destroy(LinphoneAuthInfo *obj){
if (obj->username!=NULL) ms_free(obj->username);
if (obj->userid!=NULL) ms_free(obj->userid);
......@@ -154,7 +177,9 @@ static int realm_match(const char *realm1, const char *realm2){
return FALSE;
}
/**
* Retrieves a LinphoneAuthInfo previously entered into the LinphoneCore.
**/
LinphoneAuthInfo *linphone_core_find_auth_info(LinphoneCore *lc, const char *realm, const char *username)
{
MSList *elem;
......@@ -202,6 +227,11 @@ static void refresh_exosip_auth_info(LinphoneCore *lc){
eXosip_unlock();
}
/**
* Adds authentication information to the LinphoneCore.
*
* This information will be used during all SIP transacations that require authentication.
**/
void linphone_core_add_auth_info(LinphoneCore *lc, LinphoneAuthInfo *info)
{
MSList *elem;
......@@ -225,10 +255,18 @@ void linphone_core_add_auth_info(LinphoneCore *lc, LinphoneAuthInfo *info)
if (lc->automatic_action>0) lc->automatic_action--;
}
/**
* This method is used to abort a user authentication request initiated by LinphoneCore
* from the auth_info_requested callback of LinphoneCoreVTable.
**/
void linphone_core_abort_authentication(LinphoneCore *lc, LinphoneAuthInfo *info){
if (lc->automatic_action>0) lc->automatic_action--;
}
/**
* Removes an authentication information object.
**/
void linphone_core_remove_auth_info(LinphoneCore *lc, LinphoneAuthInfo *info){
int len=ms_list_size(lc->auth_info);
int newlen;
......@@ -248,10 +286,16 @@ void linphone_core_remove_auth_info(LinphoneCore *lc, LinphoneAuthInfo *info){
}
/**
* Returns an unmodifiable list of currently entered LinphoneAuthInfo.
**/
const MSList *linphone_core_get_auth_info_list(const LinphoneCore *lc){
return lc->auth_info;
}
/**
* Clear all authentication information.
**/
void linphone_core_clear_all_auth_info(LinphoneCore *lc){
MSList *elem;
int i;
......@@ -342,3 +386,7 @@ void linphone_process_authentication(LinphoneCore *lc, eXosip_event_t *ev)
linphone_core_find_or_ask_for_auth_info(lc,username,www_realm,ev->tid);
}
/**
* @}
**/
EXTRA_DIST = Doxyfile.in doxygen.dox.in
SOURCES=$(top_srcdir)/coreapi/*.h
SOURCES=$(top_srcdir)/coreapi/*.h $(top_srcdir)/coreapi/*.c
#html doc
......@@ -30,4 +30,4 @@ uninstall-hook:
endif
clean-local:
rm -rf doc
\ No newline at end of file
rm -rf doc
......@@ -37,5 +37,22 @@
**/
/**
* @defgroup misc Miscenalleous: logs, version strings
* @defgroup proxies Managing proxies
**/
/**
* @defgroup authentication Managing authentication: userid and passwords
**/
/**
* @defgroup call_logs Managing call logs
**/
/**
* @defgroup linphone_address SIP address parser API.
* This api is useful for manipulating SIP addresses ('from' or 'to' headers).
**/
/**
* @defgroup misc Miscenalleous: logs, version strings, config storage
**/
This diff is collapsed.
This diff is collapsed.
......@@ -25,6 +25,24 @@
#ifndef LPCONFIG_H
#define LPCONFIG_H
/**
* The LpConfig object is used to manipulate a configuration file.
*
* @ingroup misc
* The format of the configuration file is a .ini like format:
* - sections are defined in []
* - each section contains a sequence of key=value pairs.
*
* Example:
* @code
* [sound]
* echocanceler=1
* playback_dev=ALSA: Default device
*
* [video]
* enabled=1
* @endcode
**/
typedef struct _LpConfig LpConfig;
#ifdef __cplusplus
......@@ -33,13 +51,58 @@ extern "C" {
LpConfig * lp_config_new(const char *filename);
int lp_config_read_file(LpConfig *lpconfig, const char *filename);
/**
* Retrieves a configuration item as a string, given its section, key, and default value.
*
* @ingroup misc
* The default value string is returned if the config item isn't found.
**/
const char *lp_config_get_string(LpConfig *lpconfig, const char *section, const char *key, const char *default_string);
int lp_config_read_file(LpConfig *lpconfig, const char *filename);
/**
* Retrieves a configuration item as an integer, given its section, key, and default value.
*
* @ingroup misc
* The default integer value is returned if the config item isn't found.
**/
int lp_config_get_int(LpConfig *lpconfig,const char *section, const char *key, int default_value);
int lp_config_read_file(LpConfig *lpconfig, const char *filename);
/**
* Retrieves a configuration item as a float, given its section, key, and default value.
*
* @ingroup misc
* The default float value is returned if the config item isn't found.
**/
float lp_config_get_float(LpConfig *lpconfig,const char *section, const char *key, float default_value);
/**
* Sets a string config item
*
* @ingroup misc
**/
void lp_config_set_string(LpConfig *lpconfig,const char *section, const char *key, const char *value);
/**
* Sets an integer config item
*
* @ingroup misc
**/
void lp_config_set_int(LpConfig *lpconfig,const char *section, const char *key, int value);
/**
* Writes the config file to disk.
*
* @ingroup misc
**/
int lp_config_sync(LpConfig *lpconfig);
/**
* Returns 1 if a given section is present in the configuration.
*
* @ingroup misc
**/
int lp_config_has_section(LpConfig *lpconfig, const char *section);
/**
* Removes every pair of key,value in a section and remove the section.
*
* @ingroup misc
**/
void lp_config_clean_section(LpConfig *lpconfig, const char *section);
/*tells whether uncommited (with lp_config_sync()) modifications exist*/
int lp_config_needs_commit(const LpConfig *lpconfig);
......
......@@ -185,9 +185,15 @@ void linphone_core_update_allocated_audio_bandwidth_in_call(LinphoneCore *lc, co
void linphone_core_run_stun_tests(LinphoneCore *lc, LinphoneCall *call);
void linphone_core_write_friends_config(LinphoneCore* lc);
void linphone_friend_write_to_config_file(struct _LpConfig *config, LinphoneFriend *lf, int index);
LinphoneFriend * linphone_friend_new_from_config_file(struct _LinphoneCore *lc, int index);
void linphone_proxy_config_update(LinphoneProxyConfig *cfg);
void linphone_proxy_config_get_contact(LinphoneProxyConfig *cfg, const char **ip, int *port);
LinphoneProxyConfig * linphone_core_lookup_known_proxy(LinphoneCore *lc, const LinphoneAddress *uri);
int linphone_core_get_local_ip_for(const char *dest, char *result);
LinphoneProxyConfig *linphone_proxy_config_new_from_config_file(struct _LpConfig *config, int index);
void linphone_proxy_config_write_to_config_file(struct _LpConfig* config,LinphoneProxyConfig *obj, int index);
#endif /* _PRIVATE_H */
......@@ -40,6 +40,14 @@ void linphone_proxy_config_init(LinphoneProxyConfig *obj){
obj->expires=3600;
}
/**
* @addtogroup proxies
* @{
**/
/**
* Creates an empty proxy config.
**/
LinphoneProxyConfig *linphone_proxy_config_new(){
LinphoneProxyConfig *obj=NULL;
obj=ms_new(LinphoneProxyConfig,1);
......@@ -47,6 +55,12 @@ LinphoneProxyConfig *linphone_proxy_config_new(){
return obj;
}
/**
* Destroys a proxy config.
*
* @note: LinphoneProxyConfig that have been removed from LinphoneCore with
* linphone_core_remove_proxy_config() must not be freed.
**/
void linphone_proxy_config_destroy(LinphoneProxyConfig *obj){
if (obj->reg_proxy!=NULL) ms_free(obj->reg_proxy);
if (obj->reg_identity!=NULL) ms_free(obj->reg_identity);
......@@ -57,6 +71,9 @@ void linphone_proxy_config_destroy(LinphoneProxyConfig *obj){
if (obj->contact_addr!=NULL) ms_free(obj->contact_addr);
}
/**
* Returns a boolean indicating that the user is sucessfully registered on the proxy.
**/
bool_t linphone_proxy_config_is_registered(const LinphoneProxyConfig *obj){
return obj->registered;
}
......@@ -134,6 +151,14 @@ bool_t linphone_proxy_config_register_again_with_updated_contact(LinphoneProxyCo
return TRUE;
}
/**
* Sets the proxy address
*
* Examples of valid sip proxy address are:
* - IP address: sip:87.98.157.38
* - IP address with port: sip:87.98.157.38:5062
* - hostnames : sip:sip.example.net
**/
int linphone_proxy_config_set_server_addr(LinphoneProxyConfig *obj, const char *server_addr){
int err;
osip_from_t *url;
......@@ -152,6 +177,15 @@ int linphone_proxy_config_set_server_addr(LinphoneProxyConfig *obj, const char *
return 0;
}
/**
* Sets the user identity as a SIP address.
*
* This identity is normally formed with display name, username and domain, such
* as:
* Alice <sip:alice@example.net>
* The REGISTER messages will have from and to set to this identity.
*
**/
void linphone_proxy_config_set_identity(LinphoneProxyConfig *obj, const char *identity){
int err=0;
osip_from_t *url=NULL;
......@@ -182,6 +216,11 @@ const char *linphone_proxy_config_get_domain(const LinphoneProxyConfig *cfg){
return cfg->realm;
}
/**
* Sets a SIP route.
* When a route is set, all outgoing calls will go to the route's destination if this proxy
* is the default one (see linphone_core_set_default_proxy() ).
**/
void linphone_proxy_config_set_route(LinphoneProxyConfig *obj, const char *route)
{
int err;
......@@ -231,10 +270,16 @@ bool_t linphone_proxy_config_check(LinphoneCore *lc, LinphoneProxyConfig *obj){
return TRUE;
}
/**
* Indicates whether a REGISTER request must be sent to the proxy.
**/
void linphone_proxy_config_enableregister(LinphoneProxyConfig *obj, bool_t val){
obj->reg_sendregister=val;
}
/**
* Sets the registration expiration time in seconds.
**/
void linphone_proxy_config_expires(LinphoneProxyConfig *obj, int val){
if (val<=0) val=600;
obj->expires=val;
......@@ -244,6 +289,15 @@ void linphone_proxy_config_enable_publish(LinphoneProxyConfig *obj, bool_t val){
obj->publish=val;
}
/**
* Starts editing a proxy configuration.
*
* Because proxy configuration must be consistent, applications MUST
* call linphone_proxy_config_edit() before doing any attempts to modify
* proxy configuration (such as identity, proxy address and so on).
* Once the modifications are done, then the application must call
* linphone_proxy_config_done() to commit the changes.
**/
void linphone_proxy_config_edit(LinphoneProxyConfig *obj){
obj->auth_failures=0;
if (obj->reg_sendregister){
......@@ -280,6 +334,9 @@ static void linphone_proxy_config_register(LinphoneProxyConfig *obj){
}
}
/**
* Commits modification made to the proxy configuration.
**/
int linphone_proxy_config_done(LinphoneProxyConfig *obj)
{
if (!linphone_proxy_config_check(obj->lc,obj)) return -1;
......@@ -464,6 +521,11 @@ entity=\"%s\">\n%s",
return 0;
}
/**
* Add a proxy configuration.
* This will start registration on the proxy, if registration is enabled.
**/
int linphone_core_add_proxy_config(LinphoneCore *lc, LinphoneProxyConfig *cfg){
if (!linphone_proxy_config_check(lc,cfg)) return -1;
lc->sip_conf.proxies=ms_list_append(lc->sip_conf.proxies,(void *)cfg);
......@@ -473,6 +535,12 @@ int linphone_core_add_proxy_config(LinphoneCore *lc, LinphoneProxyConfig *cfg){
extern void linphone_friend_check_for_removed_proxy(LinphoneFriend *lf, LinphoneProxyConfig *cfg);
/**
* Removes a proxy configuration.
*
* LinphoneCore will then automatically unregister and place the proxy configuration
* on a deleted list. For that reason, a removed proxy does NOT need to be freed.
**/
void linphone_core_remove_proxy_config(LinphoneCore *lc, LinphoneProxyConfig *cfg){
MSList *elem;
lc->sip_conf.proxies=ms_list_remove(lc->sip_conf.proxies,(void *)cfg);
......@@ -490,6 +558,13 @@ void linphone_core_remove_proxy_config(LinphoneCore *lc, LinphoneProxyConfig *cf
}
/**
* Sets the default proxy.
*
* This default proxy must be part of the list of already entered LinphoneProxyConfig.
* Toggling it as default will make LinphoneCore use the identity associated with
* the proxy configuration in all incoming and outgoing calls.
**/
void linphone_core_set_default_proxy(LinphoneCore *lc, LinphoneProxyConfig *config){
/* check if this proxy is in our list */
if (config!=NULL){
......@@ -508,6 +583,9 @@ void linphone_core_set_default_proxy_index(LinphoneCore *lc, int index){
else linphone_core_set_default_proxy(lc,ms_list_nth_data(lc->sip_conf.proxies,index));
}
/**
* Returns the default proxy configuration, that is the one used to determine the current identity.
**/
int linphone_core_get_default_proxy(LinphoneCore *lc, LinphoneProxyConfig **config){
int pos=-1;
if (config!=NULL) *config=lc->default_proxy;
......@@ -534,6 +612,9 @@ LinphoneProxyConfig *linphone_core_get_proxy_config_from_rid(LinphoneCore *lc, i
else return (LinphoneProxyConfig*)elem->data;
}
/**
* Returns an unmodifiable list of entered proxy configurations.
**/
const MSList *linphone_core_get_proxy_config_list(const LinphoneCore *lc){
return lc->sip_conf.proxies;
}
......@@ -681,6 +762,10 @@ SipSetupContext *linphone_proxy_config_get_sip_setup_context(LinphoneProxyConfig
return cfg->ssctx;
}
/**
* @}
**/
LinphoneAccountCreator *linphone_account_creator_new(struct _LinphoneCore *core, const char *type){
LinphoneAccountCreator *obj;
LinphoneProxyConfig *cfg;
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment