From 8276aa273d39399a5f8efb2c34a583f2ca1e445a Mon Sep 17 00:00:00 2001 From: smorlat Date: Wed, 16 Dec 2009 21:22:53 +0000 Subject: [PATCH] Add API docs for liblinphone. git-svn-id: svn+ssh://svn.savannah.nongnu.org/linphone/trunk@785 3f6dc0c8-ddfe-455d-9043-3cd528dc4637 --- linphone/coreapi/authentication.c | 50 +++++++- linphone/coreapi/help/Makefile.am | 4 +- linphone/coreapi/help/doxygen.dox.in | 19 ++- linphone/coreapi/linphonecore.c | 184 ++++++++++++++++++++++++++- linphone/coreapi/linphonecore.h | 176 ++++++++++++++++++++----- linphone/coreapi/lpconfig.h | 63 +++++++++ linphone/coreapi/private.h | 6 + linphone/coreapi/proxy.c | 85 +++++++++++++ 8 files changed, 548 insertions(+), 39 deletions(-) diff --git a/linphone/coreapi/authentication.c b/linphone/coreapi/authentication.c index a8c8c3a9c..59d8f43b3 100644 --- a/linphone/coreapi/authentication.c +++ b/linphone/coreapi/authentication.c @@ -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); } + +/** + * @} +**/ diff --git a/linphone/coreapi/help/Makefile.am b/linphone/coreapi/help/Makefile.am index 5c6733108..0b12592f4 100644 --- a/linphone/coreapi/help/Makefile.am +++ b/linphone/coreapi/help/Makefile.am @@ -1,7 +1,7 @@ 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 diff --git a/linphone/coreapi/help/doxygen.dox.in b/linphone/coreapi/help/doxygen.dox.in index df71d1a23..05808bb2c 100644 --- a/linphone/coreapi/help/doxygen.dox.in +++ b/linphone/coreapi/help/doxygen.dox.in @@ -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 **/ diff --git a/linphone/coreapi/linphonecore.c b/linphone/coreapi/linphonecore.c index 89fbb70fb..c3a4e3043 100644 --- a/linphone/coreapi/linphonecore.c +++ b/linphone/coreapi/linphonecore.c @@ -275,6 +275,16 @@ void linphone_call_log_completed(LinphoneCallLog *calllog, LinphoneCall *call){ call_logs_write_to_config_file(lc); } +/** + * @addtogroup call_logs + * @{ +**/ + +/** + * Returns a human readable string describing the call. + * + * @note: the returned char* must be freed by the application (use ms_free()). +**/ char * linphone_call_log_to_str(LinphoneCallLog *cl){ char *status; char *tmp; @@ -314,6 +324,8 @@ void *linphone_call_log_get_user_pointer(const LinphoneCallLog *cl){ return cl->user_pointer; } + + /** * Associate a persistent reference key to the call log. * @@ -341,6 +353,8 @@ const char *linphone_call_log_get_ref_key(const LinphoneCallLog *cl){ return cl->refkey; } +/** @} */ + void linphone_call_log_destroy(LinphoneCallLog *cl){ if (cl->from!=NULL) linphone_address_destroy(cl->from); if (cl->to!=NULL) linphone_address_destroy(cl->to); @@ -2543,11 +2557,21 @@ LinphoneFirewallPolicy linphone_core_get_firewall_policy(const LinphoneCore *lc) return lc->net_conf.firewall_policy; } +/** + * Get the list of call logs (past calls). + * + * @ingroup call_logs +**/ const MSList * linphone_core_get_call_logs(LinphoneCore *lc){ lc->missed_calls=0; return lc->call_logs; } +/** + * Erase the call log. + * + * @ingroup call_logs +**/ void linphone_core_clear_call_logs(LinphoneCore *lc){ lc->missed_calls=0; ms_list_for_each(lc->call_logs,(void (*)(void*))linphone_call_log_destroy); @@ -2572,6 +2596,18 @@ static void toggle_video_preview(LinphoneCore *lc, bool_t val){ #endif } +/** + * Enables video globally. + * + * @ingroup media_parameters + * This function does not have any effect during calls. It just indicates LinphoneCore to + * initiate future calls with video or not. The two boolean parameters indicate in which + * direction video is enabled. Setting both to false disables video entirely. + * + * @param vcap_enabled indicates whether video capture is enabled + * @param display_enabled indicates whether video display should be shown + * +**/ void linphone_core_enable_video(LinphoneCore *lc, bool_t vcap_enabled, bool_t display_enabled){ #ifndef VIDEO_ENABLED if (vcap_enabled || display_enabled) @@ -2592,19 +2628,42 @@ void linphone_core_enable_video(LinphoneCore *lc, bool_t vcap_enabled, bool_t di linphone_core_get_upload_bandwidth(lc)); } +/** + * Returns TRUE if video is enabled, FALSE otherwise. + * @ingroup media_parameters +**/ bool_t linphone_core_video_enabled(LinphoneCore *lc){ return (lc->video_conf.display || lc->video_conf.capture); } +/** + * Controls video preview enablement. + * + * @ingroup media_parameters + * Video preview refers to the action of displaying the local webcam image + * to the user while not in call. +**/ void linphone_core_enable_video_preview(LinphoneCore *lc, bool_t val){ lc->video_conf.show_local=val; if (lc->ready) lp_config_set_int(lc->config,"video","show_local",val); } +/** + * Returns TRUE if video previewing is enabled. + * @ingroup media_parameters +**/ bool_t linphone_core_video_preview_enabled(const LinphoneCore *lc){ return lc->video_conf.show_local; } +/** + * Enables or disable self view during calls. + * + * @ingroup media_parameters + * Self-view refers to having local webcam image inserted in corner + * of the video window during calls. + * This function works at any time, including during calls. +**/ void linphone_core_enable_self_view(LinphoneCore *lc, bool_t val){ lc->video_conf.selfview=val; #ifdef VIDEO_ENABLED @@ -2614,10 +2673,23 @@ void linphone_core_enable_self_view(LinphoneCore *lc, bool_t val){ #endif } +/** + * Returns TRUE if self-view is enabled, FALSE otherwise. + * + * @ingroup media_parameters + * + * Refer to linphone_core_enable_self_view() for details. +**/ bool_t linphone_core_self_view_enabled(const LinphoneCore *lc){ return lc->video_conf.selfview; } +/** + * Sets the active video device. + * + * @ingroup media_parameters + * @param id the name of the video device as returned by linphone_core_get_video_devices() +**/ int linphone_core_set_video_device(LinphoneCore *lc, const char *id){ MSWebCam *olddev=lc->video_conf.device; const char *vd; @@ -2642,11 +2714,21 @@ int linphone_core_set_video_device(LinphoneCore *lc, const char *id){ return 0; } +/** + * Returns the name of the currently active video device. + * + * @ingroup media_parameters +**/ const char *linphone_core_get_video_device(const LinphoneCore *lc){ if (lc->video_conf.device) return ms_web_cam_get_string_id(lc->video_conf.device); return NULL; } +/** + * Returns the native window handle of the video window, casted as an unsigned long. + * + * @ingroup media_parameters +**/ unsigned long linphone_core_get_native_video_window_id(const LinphoneCore *lc){ #ifdef VIDEO_ENABLED if (lc->videostream) @@ -2667,6 +2749,11 @@ static MSVideoSizeDef supported_resolutions[]={ { {0,0} , NULL } }; +/** + * Returns the zero terminated table of supported video resolutions. + * + * @ingroup media_parameters +**/ const MSVideoSizeDef *linphone_core_get_supported_video_sizes(LinphoneCore *lc){ return supported_resolutions; } @@ -2682,7 +2769,7 @@ static MSVideoSize video_size_get_by_name(const char *name){ return (MSVideoSize){0,0}; } -const char *video_size_get_name(MSVideoSize vsize){ +static const char *video_size_get_name(MSVideoSize vsize){ MSVideoSizeDef *pdef=supported_resolutions; for(;pdef->name!=NULL;pdef++){ if (pdef->vsize.width==vsize.width && pdef->vsize.height==vsize.height){ @@ -2698,7 +2785,13 @@ static bool_t video_size_supported(MSVideoSize vsize){ return FALSE; } - +/** + * Sets the preferred video size. + * + * @ingroup media_parameters + * This applies only to the stream that is captured and sent to the remote party, + * since we accept all standart video size on the receive path. +**/ void linphone_core_set_preferred_video_size(LinphoneCore *lc, MSVideoSize vsize){ if (video_size_supported(vsize)){ MSVideoSize oldvsize=lc->video_conf.vsize; @@ -2712,12 +2805,25 @@ void linphone_core_set_preferred_video_size(LinphoneCore *lc, MSVideoSize vsize) } } +/** + * Sets the preferred video size by its name. + * + * @ingroup media_parameters + * This is identical to linphone_core_set_preferred_video_size() except + * that it takes the name of the video resolution as input. + * Video resolution names are: qcif, svga, cif, vga, 4cif, svga ... +**/ void linphone_core_set_preferred_video_size_by_name(LinphoneCore *lc, const char *name){ MSVideoSize vsize=video_size_get_by_name(name); if (vsize.width!=0) linphone_core_set_preferred_video_size(lc,vsize); else linphone_core_set_preferred_video_size(lc,MS_VIDEO_SIZE_CIF); } +/** + * Returns the current preferred video size for sending. + * + * @ingroup media_parameters +**/ MSVideoSize linphone_core_get_preferred_video_size(LinphoneCore *lc){ return lc->video_conf.vsize; } @@ -2750,7 +2856,11 @@ void linphone_core_set_record_file(LinphoneCore *lc, const char *file){ } } - +/** + * Retrieves the user pointer that was given to linphone_core_new() + * + * @ingroup initializing +**/ void *linphone_core_get_user_data(LinphoneCore *lc){ return lc->data; } @@ -2936,6 +3046,14 @@ void ui_config_uninit(LinphoneCore* lc) } } +/** + * Returns the LpConfig object used to manage the storage (config) file. + * + * @ingroup misc + * The application can use the LpConfig object to insert its own private + * sections and pairs of key=value in the configuration file. + * +**/ LpConfig *linphone_core_get_config(LinphoneCore *lc){ return lc->config; } @@ -2982,11 +3100,25 @@ static void linphone_core_uninit(LinphoneCore *lc) gstate_new_state(lc, GSTATE_POWER_OFF, NULL); } +/** + * Destroys a LinphoneCore + * + * @ingroup initializing +**/ void linphone_core_destroy(LinphoneCore *lc){ linphone_core_uninit(lc); ms_free(lc); } +/** + * @addtogroup linphone_address + * @{ +**/ + +/** + * Constructs a LinphoneAddress object by parsing the user supplied address, + * given as a string. +**/ LinphoneAddress * linphone_address_new(const char *uri){ osip_from_t *from; osip_from_init(&from); @@ -2997,6 +3129,9 @@ LinphoneAddress * linphone_address_new(const char *uri){ return from; } +/** + * Clones a LinphoneAddress object. +**/ LinphoneAddress * linphone_address_clone(const LinphoneAddress *uri){ osip_from_t *ret=NULL; osip_from_clone(uri,&ret); @@ -3005,22 +3140,37 @@ LinphoneAddress * linphone_address_clone(const LinphoneAddress *uri){ #define null_if_empty(s) (((s)!=NULL && (s)[0]!='\0') ? (s) : NULL ) +/** + * Returns the address scheme, normally "sip". +**/ const char *linphone_address_get_scheme(const LinphoneAddress *u){ return null_if_empty(u->url->scheme); } +/** + * Returns the display name. +**/ const char *linphone_address_get_display_name(const LinphoneAddress* u){ return null_if_empty(u->displayname); } +/** + * Returns the username. +**/ const char *linphone_address_get_username(const LinphoneAddress *u){ return null_if_empty(u->url->username); } +/** + * Returns the domain name. +**/ const char *linphone_address_get_domain(const LinphoneAddress *u){ return null_if_empty(u->url->host); } +/** + * Sets the display name. +**/ void linphone_address_set_display_name(LinphoneAddress *u, const char *display_name){ if (u->displayname!=NULL){ osip_free(u->displayname); @@ -3030,6 +3180,9 @@ void linphone_address_set_display_name(LinphoneAddress *u, const char *display_n u->displayname=osip_strdup(display_name); } +/** + * Sets the username. +**/ void linphone_address_set_username(LinphoneAddress *uri, const char *username){ if (uri->url->username!=NULL){ osip_free(uri->url->username); @@ -3039,6 +3192,9 @@ void linphone_address_set_username(LinphoneAddress *uri, const char *username){ uri->url->username=osip_strdup(username); } +/** + * Sets the domain. +**/ void linphone_address_set_domain(LinphoneAddress *uri, const char *host){ if (uri->url->host!=NULL){ osip_free(uri->url->host); @@ -3048,6 +3204,9 @@ void linphone_address_set_domain(LinphoneAddress *uri, const char *host){ uri->url->host=osip_strdup(host); } +/** + * Sets the port number. +**/ void linphone_address_set_port(LinphoneAddress *uri, const char *port){ if (uri->url->port!=NULL){ osip_free(uri->url->port); @@ -3057,6 +3216,9 @@ void linphone_address_set_port(LinphoneAddress *uri, const char *port){ uri->url->port=osip_strdup(port); } +/** + * Sets the port number. +**/ void linphone_address_set_port_int(LinphoneAddress *uri, int port){ char tmp[12]; if (port==5060){ @@ -3068,10 +3230,17 @@ void linphone_address_set_port_int(LinphoneAddress *uri, int port){ linphone_address_set_port(uri,tmp); } +/** + * Removes address's tags and uri headers so that it is displayable to the user. +**/ void linphone_address_clean(LinphoneAddress *uri){ osip_generic_param_freelist(&uri->gen_params); } +/** + * Returns the address as a string. + * The returned char * must be freed by the application. Use ms_free(). +**/ char *linphone_address_as_string(const LinphoneAddress *u){ char *tmp,*ret; osip_from_to_str(u,&tmp); @@ -3080,6 +3249,10 @@ char *linphone_address_as_string(const LinphoneAddress *u){ return ret; } +/** + * Returns the SIP uri only as a string, that is display name is removed. + * The returned char * must be freed by the application. Use ms_free(). +**/ char *linphone_address_as_string_uri_only(const LinphoneAddress *u){ char *tmp=NULL,*ret; osip_uri_to_str(u->url,&tmp); @@ -3088,6 +3261,11 @@ char *linphone_address_as_string_uri_only(const LinphoneAddress *u){ return ret; } +/** + * Destroys a LinphoneAddress object. +**/ void linphone_address_destroy(LinphoneAddress *u){ osip_from_free(u); } + +/** @} */ diff --git a/linphone/coreapi/linphonecore.h b/linphone/coreapi/linphonecore.h index e5f164253..cc070cb91 100644 --- a/linphone/coreapi/linphonecore.h +++ b/linphone/coreapi/linphonecore.h @@ -147,6 +147,20 @@ typedef struct autoreplier_config struct osip_from; +/** + * Object that represents a SIP address. + * + * The LinphoneAddress is an opaque object to represents SIP addresses, ie + * the content of SIP's 'from' and 'to' headers. + * A SIP address is made of display name, username, domain name, port, and various + * uri headers (such as tags). It looks like 'Alice '. + * The LinphoneAddress has methods to extract and manipulate all parts of the address. + * When some part of the address (for example the username) is empty, the accessor methods + * return NULL. + * + * @ingroup linphone_address + * @var LinphoneAddress + */ typedef struct osip_from LinphoneAddress; LinphoneAddress * linphone_address_new(const char *uri); @@ -171,23 +185,44 @@ struct _sdp_context; struct _SipSetupContext; struct _LinphoneCall; +/** + * Enum representing the direction of a call. + * @ingroup call_logs +**/ +enum _LinphoneCallDir { + LinphoneCallOutgoing, /**< outgoing calls*/ + LinphoneCallIncoming /**< incoming calls*/ +}; -typedef enum _LinphoneCallDir {LinphoneCallOutgoing, LinphoneCallIncoming} LinphoneCallDir; - +/** + * Typedef for enum + * @ingroup call_logs +**/ +typedef enum _LinphoneCallDir LinphoneCallDir; +/** + * Enum representing the status of a call + * @ingroup call_logs +**/ typedef enum _LinphoneCallStatus { - LinphoneCallSuccess, - LinphoneCallAborted, - LinphoneCallMissed + LinphoneCallSuccess, /**< The call was sucessful*/ + LinphoneCallAborted, /**< The call was aborted */ + LinphoneCallMissed /**< The call was missed (unanswered)*/ } LinphoneCallStatus; +/** + * Structure representing a call log. + * + * @ingroup call_logs + * +**/ typedef struct _LinphoneCallLog{ - LinphoneCallDir dir; - LinphoneCallStatus status; - LinphoneAddress *from; - LinphoneAddress *to; - char start_date[128]; - int duration; + LinphoneCallDir dir; /**< The direction of the call*/ + LinphoneCallStatus status; /**< The status of the call*/ + LinphoneAddress *from; /**url) -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); - +/** + * @addtogroup proxies + * @{ +**/ +/** + * The LinphoneProxyConfig object represents a proxy configuration to be used + * by the LinphoneCore object. + * Its fields must not be used directly in favour of the accessors methods. + * Once created and filled properly the LinphoneProxyConfig can be given to + * LinphoneCore with linphone_core_add_proxy_config(). + * This will automatically triggers the registration, if enabled. + * + * The proxy configuration are persistent to restarts because they are saved + * in the configuration file. As a consequence, after linphone_core_new() there + * might already be a list of configured proxy that can be examined with + * linphone_core_get_proxy_config_list(). + * + * The default proxy (see linphone_core_set_default_proxy() ) is the one of the list + * that is used by default for calls. +**/ typedef struct _LinphoneProxyConfig { struct _LinphoneCore *lc; @@ -301,21 +353,28 @@ void linphone_proxy_config_enable_publish(LinphoneProxyConfig *obj, bool_t val); bool_t linphone_proxy_config_is_registered(const LinphoneProxyConfig *obj); const char *linphone_proxy_config_get_domain(const LinphoneProxyConfig *cfg); +/** Returns the proxy configured identity as a const char * */ #define linphone_proxy_config_get_route(obj) ((obj)->reg_route) +/** Returns the proxy configured identity as a const char * */ #define linphone_proxy_config_get_identity(obj) ((obj)->reg_identity) #define linphone_proxy_config_publish_enabled(obj) ((obj)->publish) +/** Returns the proxy sip address as const char * */ #define linphone_proxy_config_get_addr(obj) ((obj)->reg_proxy) +/** Returns the 'expire' time of the registration */ #define linphone_proxy_config_get_expires(obj) ((obj)->expires) +/** Returns TRUE if registration is enabled, FALSE otherwise */ #define linphone_proxy_config_register_enabled(obj) ((obj)->reg_sendregister) #define linphone_proxy_config_get_core(obj) ((obj)->lc) /* destruction is called automatically when removing the proxy config */ void linphone_proxy_config_destroy(LinphoneProxyConfig *cfg); -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); void linphone_proxy_config_set_sip_setup(LinphoneProxyConfig *cfg, const char *type); SipSetupContext *linphone_proxy_config_get_sip_setup_context(LinphoneProxyConfig *cfg); SipSetup *linphone_proxy_config_get_sip_setup(LinphoneProxyConfig *cfg); +/** + * @} +**/ + typedef struct _LinphoneAccountCreator{ struct _LinphoneCore *lc; struct _SipSetupContext *ssctx; @@ -335,7 +394,30 @@ int linphone_account_creator_test_existence(LinphoneAccountCreator *obj); LinphoneProxyConfig * linphone_account_creator_validate(LinphoneAccountCreator *obj); void linphone_account_creator_destroy(LinphoneAccountCreator *obj); - +/** + * @ingroup authentication + * Object holding authentication information. + * + * @note The object's fields should not be accessed directly. Prefer using + * the accessor methods. + * + * In most case, authentication information consists of a username and password. + * Sometimes, a userid is required by proxy, and realm can be useful to discriminate + * different SIP domains. + * + * Once created and filled, a LinphoneAuthInfo must be added to the LinphoneCore in + * order to become known and used automatically when needed. + * Use linphone_core_add_auth_info() for that purpose. + * + * The LinphoneCore object can take the initiative to request authentication information + * when needed to the application through the auth_info_requested callback of the + * LinphoneCoreVTable structure. + * + * The application can respond to this information request later using + * linphone_core_add_auth_info(). This will unblock all pending authentication + * transactions and retry them with authentication headers. + * +**/ typedef struct _LinphoneAuthInfo { char *username; @@ -412,49 +494,79 @@ void gstate_new_state(struct _LinphoneCore *lc, gstate_t new_state, const char * /*private*/ void gstate_initialize(struct _LinphoneCore *lc) ; +/** + * @addtogroup initializing + * @{ +**/ + +/** Callback prototype */ typedef void (*ShowInterfaceCb)(struct _LinphoneCore *lc); +/** Callback prototype */ typedef void (*InviteReceivedCb)(struct _LinphoneCore *lc, const char *from); +/** Callback prototype */ typedef void (*ByeReceivedCb)(struct _LinphoneCore *lc, const char *from); +/** Callback prototype */ typedef void (*DisplayStatusCb)(struct _LinphoneCore *lc, const char *message); +/** Callback prototype */ typedef void (*DisplayMessageCb)(struct _LinphoneCore *lc, const char *message); +/** Callback prototype */ typedef void (*DisplayUrlCb)(struct _LinphoneCore *lc, const char *message, const char *url); +/** Callback prototype */ typedef void (*DisplayQuestionCb)(struct _LinphoneCore *lc, const char *message); +/** Callback prototype */ typedef void (*LinphoneCoreCbFunc)(struct _LinphoneCore *lc,void * user_data); +/** Callback prototype */ typedef void (*NotifyReceivedCb)(struct _LinphoneCore *lc, LinphoneFriend * fid, const char *url, const char *status, const char *img); +/** Callback prototype */ typedef void (*NewUnknownSubscriberCb)(struct _LinphoneCore *lc, LinphoneFriend *lf, const char *url); +/** Callback prototype */ typedef void (*AuthInfoRequested)(struct _LinphoneCore *lc, const char *realm, const char *username); +/** Callback prototype */ typedef void (*CallLogUpdated)(struct _LinphoneCore *lc, struct _LinphoneCallLog *newcl); +/** Callback prototype */ typedef void (*TextMessageReceived)(struct _LinphoneCore *lc, LinphoneChatRoom *room, const char *from, const char *message); +/** Callback prototype */ typedef void (*GeneralStateChange)(struct _LinphoneCore *lc, LinphoneGeneralState *gstate); +/** Callback prototype */ typedef void (*DtmfReceived)(struct _LinphoneCore* lc, int dtmf); +/** Callback prototype */ typedef void (*ReferReceived)(struct _LinphoneCore *lc, const char *refer_to); +/** Callback prototype */ typedef void (*BuddyInfoUpdated)(struct _LinphoneCore *lc, LinphoneFriend *lf); +/** + * This structure holds all callbacks that the application should implement. + * +**/ typedef struct _LinphoneVTable { - ShowInterfaceCb show; - InviteReceivedCb inv_recv; - ByeReceivedCb bye_recv; - NotifyReceivedCb notify_recv; - NewUnknownSubscriberCb new_unknown_subscriber; - AuthInfoRequested auth_info_requested; - DisplayStatusCb display_status; - DisplayMessageCb display_message; + ShowInterfaceCb show; /**< Notifies the application that it should show up*/ + InviteReceivedCb inv_recv; /**< Notifies incoming calls */ + ByeReceivedCb bye_recv; /**< Notify calls terminated by far end*/ + NotifyReceivedCb notify_recv; /**< Notify received presence events*/ + NewUnknownSubscriberCb new_unknown_subscriber; /**< Notify about unknown subscriber */ + AuthInfoRequested auth_info_requested; /**< Ask the application some authentication information */ + DisplayStatusCb display_status; /**< Callback that notifies various events with human readable text.*/ + DisplayMessageCb display_message;/**< Callback to display a message to the user */ #ifdef VINCENT_MAURY_RSVP /* the yes/no dialog box */ DisplayMessageCb display_yes_no; #endif - DisplayMessageCb display_warning; + DisplayMessageCb display_warning;/** Callback to display a warning to the user */ DisplayUrlCb display_url; DisplayQuestionCb display_question; - CallLogUpdated call_log_updated; - TextMessageReceived text_received; - GeneralStateChange general_state; - DtmfReceived dtmf_received; - ReferReceived refer_received; - BuddyInfoUpdated buddy_info_updated; + CallLogUpdated call_log_updated; /**< Notifies that call log list has been updated */ + TextMessageReceived text_received; /**< A text message has been received */ + GeneralStateChange general_state; /**< State notification callback */ + DtmfReceived dtmf_received; /**< A dtmf has been received received */ + ReferReceived refer_received; /**< A refer was received */ + BuddyInfoUpdated buddy_info_updated; /**< a LinphoneFriend's BuddyInfo has changed*/ } LinphoneCoreVTable; +/** + * @} +**/ + typedef struct _LCCallbackObj { LinphoneCoreCbFunc _func; diff --git a/linphone/coreapi/lpconfig.h b/linphone/coreapi/lpconfig.h index 17707d375..bb731acbc 100644 --- a/linphone/coreapi/lpconfig.h +++ b/linphone/coreapi/lpconfig.h @@ -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); diff --git a/linphone/coreapi/private.h b/linphone/coreapi/private.h index 94fc7764a..b7d083672 100644 --- a/linphone/coreapi/private.h +++ b/linphone/coreapi/private.h @@ -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 */ diff --git a/linphone/coreapi/proxy.c b/linphone/coreapi/proxy.c index c5fccf4bd..28975b223 100644 --- a/linphone/coreapi/proxy.c +++ b/linphone/coreapi/proxy.c @@ -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 + * 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;