Changeset 797:204f2e97bc62 in mediastreamer2


Ignore:
Timestamp:
Dec 16, 2009 10:22:53 PM (3 years ago)
Author:
smorlat <smorlat@…>
Branch:
default
Message:

Add API docs for liblinphone.

git-svn-id: ​svn+ssh://svn.savannah.nongnu.org/linphone/trunk@785 3f6dc0c8-ddfe-455d-9043-3cd528dc4637

Location:
linphone/coreapi
Files:
8 edited

Legend:

Unmodified
Added
Removed

  • linphone/coreapi/authentication.c

    r774 r797  
    3131extern LinphoneProxyConfig *linphone_core_get_proxy_config_from_rid(LinphoneCore *lc, int rid); 
    3232 
     33/** 
     34 * @addtogroup authentication 
     35 * @{ 
     36**/ 
     37 
     38/** 
     39 * Create a LinphoneAuthInfo object with supplied information. 
     40 * 
     41 * The object can be created empty, that is with all arguments set to NULL. 
     42 * Username, userid, password and realm can be set later using specific methods. 
     43**/ 
    3344LinphoneAuthInfo *linphone_auth_info_new(const char *username, const char *userid, 
    3445                                                                                                                const char *passwd, const char *ha1,const char *realm) 
    … …  
    4556} 
    4657 
     58/** 
     59 * Sets the password. 
     60**/ 
    4761void linphone_auth_info_set_passwd(LinphoneAuthInfo *info, const char *passwd){ 
    4862        if (info->passwd!=NULL) { 
    … …  
    5367} 
    5468 
     69/** 
     70 * Sets the username. 
     71**/ 
    5572void linphone_auth_info_set_username(LinphoneAuthInfo *info, const char *username){ 
    5673        if (info->username){ 
    … …  
    6178} 
    6279 
     80/** 
     81 * Sets userid. 
     82**/ 
    6383void linphone_auth_info_set_userid(LinphoneAuthInfo *info, const char *userid){ 
    6484        if (info->userid){ 
    … …  
    6989} 
    7090 
     91/** 
     92 * Destroys a LinphoneAuthInfo object. 
     93**/ 
    7194void linphone_auth_info_destroy(LinphoneAuthInfo *obj){ 
    7295        if (obj->username!=NULL) ms_free(obj->username); 
    … …  
    155178} 
    156179 
    157  
     180/** 
     181 * Retrieves a LinphoneAuthInfo previously entered into the LinphoneCore. 
     182**/ 
    158183LinphoneAuthInfo *linphone_core_find_auth_info(LinphoneCore *lc, const char *realm, const char *username) 
    159184{ 
    … …  
    203228} 
    204229 
     230/** 
     231 * Adds authentication information to the LinphoneCore. 
     232 *  
     233 * This information will be used during all SIP transacations that require authentication. 
     234**/ 
    205235void linphone_core_add_auth_info(LinphoneCore *lc, LinphoneAuthInfo *info) 
    206236{ 
    … …  
    226256} 
    227257 
     258 
     259/** 
     260 * This method is used to abort a user authentication request initiated by LinphoneCore 
     261 * from the auth_info_requested callback of LinphoneCoreVTable. 
     262**/ 
    228263void linphone_core_abort_authentication(LinphoneCore *lc,  LinphoneAuthInfo *info){ 
    229264        if (lc->automatic_action>0) lc->automatic_action--; 
    230265} 
    231266 
     267/** 
     268 * Removes an authentication information object. 
     269**/ 
    232270void linphone_core_remove_auth_info(LinphoneCore *lc, LinphoneAuthInfo *info){ 
    233271        int len=ms_list_size(lc->auth_info); 
    … …  
    249287} 
    250288 
     289/** 
     290 * Returns an unmodifiable list of currently entered LinphoneAuthInfo. 
     291**/ 
    251292const MSList *linphone_core_get_auth_info_list(const LinphoneCore *lc){ 
    252293        return lc->auth_info; 
    253294} 
    254295 
     296/** 
     297 * Clear all authentication information. 
     298**/ 
    255299void linphone_core_clear_all_auth_info(LinphoneCore *lc){ 
    256300        MSList *elem; 
    … …  
    343387} 
    344388 
     389 
     390/** 
     391 * @} 
     392**/ 

  • linphone/coreapi/help/Makefile.am

    r795 r797  
    22EXTRA_DIST = Doxyfile.in doxygen.dox.in 
    33 
    4 SOURCES=$(top_srcdir)/coreapi/*.h  
     4SOURCES=$(top_srcdir)/coreapi/*.h $(top_srcdir)/coreapi/*.c 
    55 
    66 

  • linphone/coreapi/help/doxygen.dox.in

    r795 r797  
    3838 
    3939/** 
    40  * @defgroup misc Miscenalleous: logs, version strings 
     40 * @defgroup proxies Managing proxies 
    4141**/ 
     42 
     43/** 
     44 * @defgroup authentication Managing authentication: userid and passwords 
     45**/ 
     46 
     47/** 
     48 * @defgroup call_logs Managing call logs 
     49**/ 
     50 
     51/** 
     52 * @defgroup linphone_address SIP address parser API. 
     53 * This api is useful for manipulating SIP addresses ('from' or 'to' headers). 
     54**/ 
     55 
     56/** 
     57 * @defgroup misc Miscenalleous: logs, version strings, config storage 
     58**/ 

  • linphone/coreapi/linphonecore.c

    r795 r797  
    276276} 
    277277 
     278/** 
     279 * @addtogroup call_logs 
     280 * @{ 
     281**/ 
     282 
     283/** 
     284 * Returns a human readable string describing the call. 
     285 *  
     286 * @note: the returned char* must be freed by the application (use ms_free()). 
     287**/ 
    278288char * linphone_call_log_to_str(LinphoneCallLog *cl){ 
    279289        char *status; 
    … …  
    315325} 
    316326 
     327 
     328 
    317329/** 
    318330 * Associate a persistent reference key to the call log. 
    … …  
    341353        return cl->refkey; 
    342354} 
     355 
     356/** @} */ 
    343357 
    344358void linphone_call_log_destroy(LinphoneCallLog *cl){ 
    … …  
    25442558} 
    25452559 
     2560/** 
     2561 * Get the list of call logs (past calls). 
     2562 * 
     2563 * @ingroup call_logs 
     2564**/ 
    25462565const MSList * linphone_core_get_call_logs(LinphoneCore *lc){ 
    25472566        lc->missed_calls=0; 
    … …  
    25492568} 
    25502569 
     2570/** 
     2571 * Erase the call log. 
     2572 * 
     2573 * @ingroup call_logs 
     2574**/ 
    25512575void linphone_core_clear_call_logs(LinphoneCore *lc){ 
    25522576        lc->missed_calls=0; 
    … …  
    25732597} 
    25742598 
     2599/** 
     2600 * Enables video globally. 
     2601 * 
     2602 * @ingroup media_parameters 
     2603 * This function does not have any effect during calls. It just indicates LinphoneCore to 
     2604 * initiate future calls with video or not. The two boolean parameters indicate in which 
     2605 * direction video is enabled. Setting both to false disables video entirely. 
     2606 * 
     2607 * @param vcap_enabled indicates whether video capture is enabled 
     2608 * @param display_enabled indicates whether video display should be shown 
     2609 * 
     2610**/ 
    25752611void linphone_core_enable_video(LinphoneCore *lc, bool_t vcap_enabled, bool_t display_enabled){ 
    25762612#ifndef VIDEO_ENABLED 
    … …  
    25932629} 
    25942630 
     2631/** 
     2632 * Returns TRUE if video is enabled, FALSE otherwise. 
     2633 * @ingroup media_parameters 
     2634**/ 
    25952635bool_t linphone_core_video_enabled(LinphoneCore *lc){ 
    25962636        return (lc->video_conf.display || lc->video_conf.capture); 
    25972637} 
    25982638 
     2639/** 
     2640 * Controls video preview enablement. 
     2641 * 
     2642 * @ingroup media_parameters 
     2643 * Video preview refers to the action of displaying the local webcam image 
     2644 * to the user while not in call. 
     2645**/ 
    25992646void linphone_core_enable_video_preview(LinphoneCore *lc, bool_t val){ 
    26002647        lc->video_conf.show_local=val; 
    … …  
    26022649} 
    26032650 
     2651/** 
     2652 * Returns TRUE if video previewing is enabled. 
     2653 * @ingroup media_parameters 
     2654**/ 
    26042655bool_t linphone_core_video_preview_enabled(const LinphoneCore *lc){ 
    26052656        return lc->video_conf.show_local; 
    26062657} 
    26072658 
     2659/** 
     2660 * Enables or disable self view during calls. 
     2661 * 
     2662 * @ingroup media_parameters 
     2663 * Self-view refers to having local webcam image inserted in corner 
     2664 * of the video window during calls. 
     2665 * This function works at any time, including during calls. 
     2666**/ 
    26082667void linphone_core_enable_self_view(LinphoneCore *lc, bool_t val){ 
    26092668        lc->video_conf.selfview=val; 
    … …  
    26152674} 
    26162675 
     2676/** 
     2677 * Returns TRUE if self-view is enabled, FALSE otherwise. 
     2678 * 
     2679 * @ingroup media_parameters 
     2680 * 
     2681 * Refer to linphone_core_enable_self_view() for details. 
     2682**/ 
    26172683bool_t linphone_core_self_view_enabled(const LinphoneCore *lc){ 
    26182684        return lc->video_conf.selfview; 
    26192685} 
    26202686 
     2687/** 
     2688 * Sets the active video device. 
     2689 * 
     2690 * @ingroup media_parameters 
     2691 * @param id the name of the video device as returned by linphone_core_get_video_devices() 
     2692**/ 
    26212693int linphone_core_set_video_device(LinphoneCore *lc, const char *id){ 
    26222694        MSWebCam *olddev=lc->video_conf.device; 
    … …  
    26432715} 
    26442716 
     2717/** 
     2718 * Returns the name of the currently active video device. 
     2719 * 
     2720 * @ingroup media_parameters 
     2721**/ 
    26452722const char *linphone_core_get_video_device(const LinphoneCore *lc){ 
    26462723        if (lc->video_conf.device) return ms_web_cam_get_string_id(lc->video_conf.device); 
    … …  
    26482725} 
    26492726 
     2727/** 
     2728 * Returns the native window handle of the video window, casted as an unsigned long. 
     2729 * 
     2730 * @ingroup media_parameters 
     2731**/ 
    26502732unsigned long linphone_core_get_native_video_window_id(const LinphoneCore *lc){ 
    26512733#ifdef VIDEO_ENABLED 
    … …  
    26682750}; 
    26692751 
     2752/** 
     2753 * Returns the zero terminated table of supported video resolutions. 
     2754 * 
     2755 * @ingroup media_parameters 
     2756**/ 
    26702757const MSVideoSizeDef *linphone_core_get_supported_video_sizes(LinphoneCore *lc){ 
    26712758        return supported_resolutions; 
    … …  
    26832770} 
    26842771 
    2685 const char *video_size_get_name(MSVideoSize vsize){ 
     2772static const char *video_size_get_name(MSVideoSize vsize){ 
    26862773        MSVideoSizeDef *pdef=supported_resolutions; 
    26872774        for(;pdef->name!=NULL;pdef++){ 
    … …  
    26992786} 
    27002787 
    2701  
     2788/** 
     2789 * Sets the preferred video size. 
     2790 * 
     2791 * @ingroup media_parameters 
     2792 * This applies only to the stream that is captured and sent to the remote party, 
     2793 * since we accept all standart video size on the receive path. 
     2794**/ 
    27022795void linphone_core_set_preferred_video_size(LinphoneCore *lc, MSVideoSize vsize){ 
    27032796        if (video_size_supported(vsize)){ 
    … …  
    27132806} 
    27142807 
     2808/** 
     2809 * Sets the preferred video size by its name. 
     2810 * 
     2811 * @ingroup media_parameters 
     2812 * This is identical to linphone_core_set_preferred_video_size() except 
     2813 * that it takes the name of the video resolution as input. 
     2814 * Video resolution names are: qcif, svga, cif, vga, 4cif, svga ... 
     2815**/ 
    27152816void linphone_core_set_preferred_video_size_by_name(LinphoneCore *lc, const char *name){ 
    27162817        MSVideoSize vsize=video_size_get_by_name(name); 
    … …  
    27192820} 
    27202821 
     2822/** 
     2823 * Returns the current preferred video size for sending. 
     2824 * 
     2825 * @ingroup media_parameters 
     2826**/ 
    27212827MSVideoSize linphone_core_get_preferred_video_size(LinphoneCore *lc){ 
    27222828        return lc->video_conf.vsize; 
    … …  
    27512857} 
    27522858 
    2753  
     2859/** 
     2860 * Retrieves the user pointer that was given to linphone_core_new() 
     2861 * 
     2862 * @ingroup initializing 
     2863**/ 
    27542864void *linphone_core_get_user_data(LinphoneCore *lc){ 
    27552865        return lc->data; 
    … …  
    29373047} 
    29383048 
     3049/** 
     3050 * Returns the LpConfig object used to manage the storage (config) file. 
     3051 * 
     3052 * @ingroup misc 
     3053 * The application can use the LpConfig object to insert its own private  
     3054 * sections and pairs of key=value in the configuration file. 
     3055 *  
     3056**/ 
    29393057LpConfig *linphone_core_get_config(LinphoneCore *lc){ 
    29403058        return lc->config; 
    … …  
    29833101} 
    29843102 
     3103/** 
     3104 * Destroys a LinphoneCore 
     3105 * 
     3106 * @ingroup initializing 
     3107**/ 
    29853108void linphone_core_destroy(LinphoneCore *lc){ 
    29863109        linphone_core_uninit(lc); 
    … …  
    29883111} 
    29893112 
     3113/** 
     3114 * @addtogroup linphone_address 
     3115 * @{ 
     3116**/ 
     3117 
     3118/** 
     3119 * Constructs a LinphoneAddress object by parsing the user supplied address, 
     3120 * given as a string. 
     3121**/ 
    29903122LinphoneAddress * linphone_address_new(const char *uri){ 
    29913123        osip_from_t *from; 
    … …  
    29983130} 
    29993131 
     3132/** 
     3133 * Clones a LinphoneAddress object. 
     3134**/ 
    30003135LinphoneAddress * linphone_address_clone(const LinphoneAddress *uri){ 
    30013136        osip_from_t *ret=NULL; 
    … …  
    30063141#define null_if_empty(s) (((s)!=NULL && (s)[0]!='\0') ? (s) : NULL ) 
    30073142 
     3143/** 
     3144 * Returns the address scheme, normally "sip". 
     3145**/ 
    30083146const char *linphone_address_get_scheme(const LinphoneAddress *u){ 
    30093147        return null_if_empty(u->url->scheme); 
    30103148} 
    30113149 
     3150/** 
     3151 * Returns the display name. 
     3152**/ 
    30123153const char *linphone_address_get_display_name(const LinphoneAddress* u){ 
    30133154        return null_if_empty(u->displayname); 
    30143155} 
    30153156 
     3157/** 
     3158 * Returns the username. 
     3159**/ 
    30163160const char *linphone_address_get_username(const LinphoneAddress *u){ 
    30173161        return null_if_empty(u->url->username); 
    30183162} 
    30193163 
     3164/** 
     3165 * Returns the domain name. 
     3166**/ 
    30203167const char *linphone_address_get_domain(const LinphoneAddress *u){ 
    30213168        return null_if_empty(u->url->host); 
    30223169} 
    30233170 
     3171/** 
     3172 * Sets the display name. 
     3173**/ 
    30243174void linphone_address_set_display_name(LinphoneAddress *u, const char *display_name){ 
    30253175        if (u->displayname!=NULL){ 
    … …  
    30313181} 
    30323182 
     3183/** 
     3184 * Sets the username. 
     3185**/ 
    30333186void linphone_address_set_username(LinphoneAddress *uri, const char *username){ 
    30343187        if (uri->url->username!=NULL){ 
    … …  
    30403193} 
    30413194 
     3195/** 
     3196 * Sets the domain. 
     3197**/ 
    30423198void linphone_address_set_domain(LinphoneAddress *uri, const char *host){ 
    30433199        if (uri->url->host!=NULL){ 
    … …  
    30493205} 
    30503206 
     3207/** 
     3208 * Sets the port number. 
     3209**/ 
    30513210void linphone_address_set_port(LinphoneAddress *uri, const char *port){ 
    30523211        if (uri->url->port!=NULL){ 
    … …  
    30583217} 
    30593218 
     3219/** 
     3220 * Sets the port number. 
     3221**/ 
    30603222void linphone_address_set_port_int(LinphoneAddress *uri, int port){ 
    30613223        char tmp[12]; 
    … …  
    30693231} 
    30703232 
     3233/** 
     3234 * Removes address's tags and uri headers so that it is displayable to the user. 
     3235**/ 
    30713236void linphone_address_clean(LinphoneAddress *uri){ 
    30723237        osip_generic_param_freelist(&uri->gen_params); 
    30733238} 
    30743239 
     3240/** 
     3241 * Returns the address as a string. 
     3242 * The returned char * must be freed by the application. Use ms_free(). 
     3243**/ 
    30753244char *linphone_address_as_string(const LinphoneAddress *u){ 
    30763245        char *tmp,*ret; 
    … …  
    30813250} 
    30823251 
     3252/** 
     3253 * Returns the SIP uri only as a string, that is display name is removed. 
     3254 * The returned char * must be freed by the application. Use ms_free(). 
     3255**/ 
    30833256char *linphone_address_as_string_uri_only(const LinphoneAddress *u){ 
    30843257        char *tmp=NULL,*ret; 
    … …  
    30893262} 
    30903263 
     3264/** 
     3265 * Destroys a LinphoneAddress object. 
     3266**/ 
    30913267void linphone_address_destroy(LinphoneAddress *u){ 
    30923268        osip_from_free(u); 
    30933269} 
     3270 
     3271/** @} */ 

  • linphone/coreapi/linphonecore.h

    r795 r797  
    148148struct osip_from; 
    149149 
     150/** 
     151 * Object that represents a SIP address. 
     152 * 
     153 * The LinphoneAddress is an opaque object to represents SIP addresses, ie 
     154 * the content of SIP's 'from' and 'to' headers. 
     155 * A SIP address is made of display name, username, domain name, port, and various 
     156 * uri headers (such as tags). It looks like 'Alice <sip:alice@example.net>'. 
     157 * The LinphoneAddress has methods to extract and manipulate all parts of the address. 
     158 * When some part of the address (for example the username) is empty, the accessor methods 
     159 * return NULL. 
     160 *  
     161 * @ingroup linphone_address 
     162 * @var LinphoneAddress 
     163 */ 
    150164typedef struct osip_from LinphoneAddress; 
    151165 
    … …  
    172186struct _LinphoneCall; 
    173187 
    174  
    175 typedef enum _LinphoneCallDir {LinphoneCallOutgoing, LinphoneCallIncoming} LinphoneCallDir; 
    176  
    177  
     188/** 
     189 * Enum representing the direction of a call. 
     190 * @ingroup call_logs 
     191**/ 
     192enum _LinphoneCallDir { 
     193        LinphoneCallOutgoing, /**< outgoing calls*/ 
     194        LinphoneCallIncoming  /**< incoming calls*/ 
     195}; 
     196 
     197/** 
     198 * Typedef for enum 
     199 * @ingroup call_logs 
     200**/ 
     201typedef enum _LinphoneCallDir LinphoneCallDir; 
     202 
     203/** 
     204 * Enum representing the status of a call 
     205 * @ingroup call_logs 
     206**/ 
    178207typedef enum _LinphoneCallStatus {  
    179         LinphoneCallSuccess, 
    180         LinphoneCallAborted, 
    181         LinphoneCallMissed 
     208        LinphoneCallSuccess, /**< The call was sucessful*/ 
     209        LinphoneCallAborted, /**< The call was aborted */ 
     210        LinphoneCallMissed /**< The call was missed (unanswered)*/ 
    182211} LinphoneCallStatus; 
    183212 
     213/** 
     214 * Structure representing a call log. 
     215 * 
     216 * @ingroup call_logs 
     217 *  
     218**/ 
    184219typedef struct _LinphoneCallLog{ 
    185         LinphoneCallDir dir; 
    186         LinphoneCallStatus status; 
    187         LinphoneAddress *from; 
    188         LinphoneAddress *to; 
    189         char start_date[128]; 
    190         int duration; 
     220        LinphoneCallDir dir; /**< The direction of the call*/ 
     221        LinphoneCallStatus status; /**< The status of the call*/ 
     222        LinphoneAddress *from; /**<Originator of the call as a LinphoneAddress object*/ 
     223        LinphoneAddress *to; /**<Destination of the call as a LinphoneAddress object*/ 
     224        char start_date[128]; /**<Human readable string containg the start date*/ 
     225        int duration; /**<Duration of the call in seconds*/ 
    191226        char *refkey; 
    192227        void *user_pointer; 
    … …  
    265300#define linphone_friend_url(lf) ((lf)->url) 
    266301 
    267 void linphone_friend_write_to_config_file(struct _LpConfig *config, LinphoneFriend *lf, int index); 
    268 LinphoneFriend * linphone_friend_new_from_config_file(struct _LinphoneCore *lc, int index); 
    269  
     302/** 
     303 * @addtogroup proxies 
     304 * @{ 
     305**/ 
     306/** 
     307 * The LinphoneProxyConfig object represents a proxy configuration to be used 
     308 * by the LinphoneCore object. 
     309 * Its fields must not be used directly in favour of the accessors methods. 
     310 * Once created and filled properly the LinphoneProxyConfig can be given to 
     311 * LinphoneCore with linphone_core_add_proxy_config(). 
     312 * This will automatically triggers the registration, if enabled. 
     313 * 
     314 * The proxy configuration are persistent to restarts because they are saved 
     315 * in the configuration file. As a consequence, after linphone_core_new() there 
     316 * might already be a list of configured proxy that can be examined with 
     317 * linphone_core_get_proxy_config_list(). 
     318 * 
     319 * The default proxy (see linphone_core_set_default_proxy() ) is the one of the list 
     320 * that is used by default for calls. 
     321**/ 
    270322typedef struct _LinphoneProxyConfig 
    271323{ 
    … …  
    302354const char *linphone_proxy_config_get_domain(const LinphoneProxyConfig *cfg); 
    303355 
     356/** Returns the proxy configured identity as a const char * */ 
    304357#define linphone_proxy_config_get_route(obj)  ((obj)->reg_route) 
     358/** Returns the proxy configured identity as a const char * */ 
    305359#define linphone_proxy_config_get_identity(obj) ((obj)->reg_identity) 
    306360#define linphone_proxy_config_publish_enabled(obj) ((obj)->publish) 
     361/** Returns the proxy sip address as const char * */ 
    307362#define linphone_proxy_config_get_addr(obj) ((obj)->reg_proxy) 
     363/** Returns the 'expire' time of the registration */ 
    308364#define linphone_proxy_config_get_expires(obj)  ((obj)->expires) 
     365/** Returns TRUE if registration is enabled, FALSE otherwise */ 
    309366#define linphone_proxy_config_register_enabled(obj) ((obj)->reg_sendregister) 
    310367#define linphone_proxy_config_get_core(obj) ((obj)->lc) 
    311368/* destruction is called automatically when removing the proxy config */ 
    312369void linphone_proxy_config_destroy(LinphoneProxyConfig *cfg); 
    313 LinphoneProxyConfig *linphone_proxy_config_new_from_config_file(struct _LpConfig *config, int index); 
    314 void linphone_proxy_config_write_to_config_file(struct _LpConfig* config,LinphoneProxyConfig *obj, int index); 
    315370void linphone_proxy_config_set_sip_setup(LinphoneProxyConfig *cfg, const char *type); 
    316371SipSetupContext *linphone_proxy_config_get_sip_setup_context(LinphoneProxyConfig *cfg); 
    317372SipSetup *linphone_proxy_config_get_sip_setup(LinphoneProxyConfig *cfg); 
     373 
     374/** 
     375 * @} 
     376**/ 
    318377 
    319378typedef struct _LinphoneAccountCreator{ 
    … …  
    336395void linphone_account_creator_destroy(LinphoneAccountCreator *obj); 
    337396 
    338  
     397/** 
     398 * @ingroup authentication 
     399 * Object holding authentication information. 
     400 * 
     401 * @note The object's fields should not be accessed directly. Prefer using 
     402 * the accessor methods. 
     403 * 
     404 * In most case, authentication information consists of a username and password. 
     405 * Sometimes, a userid is required by proxy, and realm can be useful to discriminate 
     406 * different SIP domains. 
     407 * 
     408 * Once created and filled, a LinphoneAuthInfo must be added to the LinphoneCore in 
     409 * order to become known and used automatically when needed.  
     410 * Use linphone_core_add_auth_info() for that purpose. 
     411 * 
     412 * The LinphoneCore object can take the initiative to request authentication information 
     413 * when needed to the application through the auth_info_requested callback of the 
     414 * LinphoneCoreVTable structure. 
     415 * 
     416 * The application can respond to this information request later using  
     417 * linphone_core_add_auth_info(). This will unblock all pending authentication  
     418 * transactions and retry them with authentication headers. 
     419 * 
     420**/ 
    339421typedef struct _LinphoneAuthInfo 
    340422{ 
    … …  
    413495void gstate_initialize(struct _LinphoneCore *lc) ; 
    414496 
     497/** 
     498 * @addtogroup initializing 
     499 * @{ 
     500**/ 
     501 
     502/** Callback prototype */ 
    415503typedef void (*ShowInterfaceCb)(struct _LinphoneCore *lc); 
     504/** Callback prototype */ 
    416505typedef void (*InviteReceivedCb)(struct _LinphoneCore *lc, const char *from); 
     506/** Callback prototype */ 
    417507typedef void (*ByeReceivedCb)(struct _LinphoneCore *lc, const char *from); 
     508/** Callback prototype */ 
    418509typedef void (*DisplayStatusCb)(struct _LinphoneCore *lc, const char *message); 
     510/** Callback prototype */ 
    419511typedef void (*DisplayMessageCb)(struct _LinphoneCore *lc, const char *message); 
     512/** Callback prototype */ 
    420513typedef void (*DisplayUrlCb)(struct _LinphoneCore *lc, const char *message, const char *url); 
     514/** Callback prototype */ 
    421515typedef void (*DisplayQuestionCb)(struct _LinphoneCore *lc, const char *message); 
     516/** Callback prototype */ 
    422517typedef void (*LinphoneCoreCbFunc)(struct _LinphoneCore *lc,void * user_data); 
     518/** Callback prototype */ 
    423519typedef void (*NotifyReceivedCb)(struct _LinphoneCore *lc, LinphoneFriend * fid, const char *url, const char *status, const char *img); 
     520/** Callback prototype */ 
    424521typedef void (*NewUnknownSubscriberCb)(struct _LinphoneCore *lc, LinphoneFriend *lf, const char *url); 
     522/** Callback prototype */ 
    425523typedef void (*AuthInfoRequested)(struct _LinphoneCore *lc, const char *realm, const char *username); 
     524/** Callback prototype */ 
    426525typedef void (*CallLogUpdated)(struct _LinphoneCore *lc, struct _LinphoneCallLog *newcl); 
     526/** Callback prototype */ 
    427527typedef void (*TextMessageReceived)(struct _LinphoneCore *lc, LinphoneChatRoom *room, const char *from, const char *message); 
     528/** Callback prototype */ 
    428529typedef void (*GeneralStateChange)(struct _LinphoneCore *lc, LinphoneGeneralState *gstate); 
     530/** Callback prototype */ 
    429531typedef void (*DtmfReceived)(struct _LinphoneCore* lc, int dtmf); 
     532/** Callback prototype */ 
    430533typedef void (*ReferReceived)(struct _LinphoneCore *lc, const char *refer_to); 
     534/** Callback prototype */ 
    431535typedef void (*BuddyInfoUpdated)(struct _LinphoneCore *lc, LinphoneFriend *lf); 
    432536 
     537/** 
     538 * This structure holds all callbacks that the application should implement. 
     539 *  
     540**/ 
    433541typedef struct _LinphoneVTable 
    434542{ 
    435         ShowInterfaceCb show; 
    436         InviteReceivedCb inv_recv; 
    437         ByeReceivedCb bye_recv; 
    438         NotifyReceivedCb notify_recv; 
    439         NewUnknownSubscriberCb new_unknown_subscriber; 
    440         AuthInfoRequested auth_info_requested; 
    441         DisplayStatusCb display_status; 
    442         DisplayMessageCb display_message; 
     543        ShowInterfaceCb show; /**< Notifies the application that it should show up*/ 
     544        InviteReceivedCb inv_recv; /**< Notifies incoming calls */ 
     545        ByeReceivedCb bye_recv; /**< Notify calls terminated by far end*/ 
     546        NotifyReceivedCb notify_recv; /**< Notify received presence events*/ 
     547        NewUnknownSubscriberCb new_unknown_subscriber; /**< Notify about unknown subscriber */ 
     548        AuthInfoRequested auth_info_requested; /**< Ask the application some authentication information */ 
     549        DisplayStatusCb display_status; /**< Callback that notifies various events with human readable text.*/ 
     550        DisplayMessageCb display_message;/**< Callback to display a message to the user */ 
    443551#ifdef VINCENT_MAURY_RSVP 
    444552        /* the yes/no dialog box */ 
    445553        DisplayMessageCb display_yes_no; 
    446554#endif 
    447         DisplayMessageCb display_warning; 
     555        DisplayMessageCb display_warning;/** Callback to display a warning to the user */ 
    448556        DisplayUrlCb display_url; 
    449557        DisplayQuestionCb display_question; 
    450         CallLogUpdated call_log_updated; 
    451         TextMessageReceived text_received; 
    452         GeneralStateChange general_state; 
    453         DtmfReceived dtmf_received; 
    454         ReferReceived refer_received; 
    455         BuddyInfoUpdated buddy_info_updated; 
     558        CallLogUpdated call_log_updated; /**< Notifies that call log list has been updated */ 
     559        TextMessageReceived text_received; /**< A text message has been received */ 
     560        GeneralStateChange general_state; /**< State notification callback */ 
     561        DtmfReceived dtmf_received; /**< A dtmf has been received received */ 
     562        ReferReceived refer_received; /**< A refer was received */ 
     563        BuddyInfoUpdated buddy_info_updated; /**< a LinphoneFriend's BuddyInfo has changed*/ 
    456564} LinphoneCoreVTable; 
     565 
     566/** 
     567 * @} 
     568**/ 
    457569 
    458570typedef struct _LCCallbackObj 

  • linphone/coreapi/lpconfig.h

    r793 r797  
    2626#define LPCONFIG_H 
    2727 
     28/** 
     29 * The LpConfig object is used to manipulate a configuration file. 
     30 *  
     31 * @ingroup misc 
     32 * The format of the configuration file is a .ini like format: 
     33 * - sections are defined in [] 
     34 * - each section contains a sequence of key=value pairs. 
     35 * 
     36 * Example: 
     37 * @code 
     38 * [sound] 
     39 * echocanceler=1 
     40 * playback_dev=ALSA: Default device 
     41 * 
     42 * [video] 
     43 * enabled=1 
     44 * @endcode 
     45**/ 
    2846typedef struct _LpConfig LpConfig; 
    2947 
    … …  
    3452LpConfig * lp_config_new(const char *filename); 
    3553int lp_config_read_file(LpConfig *lpconfig, const char *filename); 
     54/** 
     55 * Retrieves a configuration item as a string, given its section, key, and default value. 
     56 *  
     57 * @ingroup misc 
     58 * The default value string is returned if the config item isn't found. 
     59**/ 
    3660const char *lp_config_get_string(LpConfig *lpconfig, const char *section, const char *key, const char *default_string); 
     61int lp_config_read_file(LpConfig *lpconfig, const char *filename); 
     62/** 
     63 * Retrieves a configuration item as an integer, given its section, key, and default value. 
     64 *  
     65 * @ingroup misc 
     66 * The default integer value is returned if the config item isn't found. 
     67**/ 
    3768int lp_config_get_int(LpConfig *lpconfig,const char *section, const char *key, int default_value); 
     69int lp_config_read_file(LpConfig *lpconfig, const char *filename); 
     70/** 
     71 * Retrieves a configuration item as a float, given its section, key, and default value. 
     72 *  
     73 * @ingroup misc 
     74 * The default float value is returned if the config item isn't found. 
     75**/ 
    3876float lp_config_get_float(LpConfig *lpconfig,const char *section, const char *key, float default_value); 
     77/** 
     78 * Sets a string config item  
     79 * 
     80 * @ingroup misc 
     81**/ 
    3982void lp_config_set_string(LpConfig *lpconfig,const char *section, const char *key, const char *value); 
     83/** 
     84 * Sets an integer config item 
     85 * 
     86 * @ingroup misc 
     87**/ 
    4088void lp_config_set_int(LpConfig *lpconfig,const char *section, const char *key, int value); 
     89/** 
     90 * Writes the config file to disk. 
     91 *  
     92 * @ingroup misc 
     93**/ 
    4194int lp_config_sync(LpConfig *lpconfig); 
     95/** 
     96 * Returns 1 if a given section is present in the configuration. 
     97 * 
     98 * @ingroup misc 
     99**/ 
    42100int lp_config_has_section(LpConfig *lpconfig, const char *section); 
     101/** 
     102 * Removes every pair of key,value in a section and remove the section. 
     103 * 
     104 * @ingroup misc 
     105**/ 
    43106void lp_config_clean_section(LpConfig *lpconfig, const char *section); 
    44107/*tells whether uncommited (with lp_config_sync()) modifications exist*/ 

  • linphone/coreapi/private.h

    r795 r797  
    186186 
    187187void linphone_core_write_friends_config(LinphoneCore* lc); 
     188void linphone_friend_write_to_config_file(struct _LpConfig *config, LinphoneFriend *lf, int index); 
     189LinphoneFriend * linphone_friend_new_from_config_file(struct _LinphoneCore *lc, int index); 
     190 
    188191void linphone_proxy_config_update(LinphoneProxyConfig *cfg); 
    189192void linphone_proxy_config_get_contact(LinphoneProxyConfig *cfg, const char **ip, int *port); 
    … …  
    191194int linphone_core_get_local_ip_for(const char *dest, char *result); 
    192195 
     196LinphoneProxyConfig *linphone_proxy_config_new_from_config_file(struct _LpConfig *config, int index); 
     197void linphone_proxy_config_write_to_config_file(struct _LpConfig* config,LinphoneProxyConfig *obj, int index); 
     198 
    193199#endif /* _PRIVATE_H */ 

  • linphone/coreapi/proxy.c

    r652 r797  
    4141} 
    4242 
     43/** 
     44 * @addtogroup proxies 
     45 * @{ 
     46**/ 
     47 
     48/** 
     49 * Creates an empty proxy config. 
     50**/ 
    4351LinphoneProxyConfig *linphone_proxy_config_new(){ 
    4452        LinphoneProxyConfig *obj=NULL; 
    … …  
    4856} 
    4957 
     58/** 
     59 * Destroys a proxy config. 
     60 *  
     61 * @note: LinphoneProxyConfig that have been removed from LinphoneCore with 
     62 * linphone_core_remove_proxy_config() must not be freed. 
     63**/ 
    5064void linphone_proxy_config_destroy(LinphoneProxyConfig *obj){ 
    5165        if (obj->reg_proxy!=NULL) ms_free(obj->reg_proxy); 
    … …  
    5872} 
    5973 
     74/** 
     75 * Returns a boolean indicating that the user is sucessfully registered on the proxy. 
     76**/ 
    6077bool_t linphone_proxy_config_is_registered(const LinphoneProxyConfig *obj){ 
    6178        return obj->registered; 
    … …  
    135152} 
    136153 
     154/** 
     155 * Sets the proxy address 
     156 * 
     157 * Examples of valid sip proxy address are: 
     158 * - IP address: sip:87.98.157.38 
     159 * - IP address with port: sip:87.98.157.38:5062 
     160 * - hostnames : sip:sip.example.net 
     161**/ 
    137162int linphone_proxy_config_set_server_addr(LinphoneProxyConfig *obj, const char *server_addr){ 
    138163        int err; 
    … …  
    153178} 
    154179 
     180/** 
     181 * Sets the user identity as a SIP address. 
     182 * 
     183 * This identity is normally formed with display name, username and domain, such  
     184 * as: 
     185 * Alice <sip:alice@example.net> 
     186 * The REGISTER messages will have from and to set to this identity. 
     187 * 
     188**/ 
    155189void linphone_proxy_config_set_identity(LinphoneProxyConfig *obj, const char *identity){ 
    156190        int err=0; 
    … …  
    183217} 
    184218 
     219/** 
     220 * Sets a SIP route. 
     221 * When a route is set, all outgoing calls will go to the route's destination if this proxy 
     222 * is the default one (see linphone_core_set_default_proxy() ). 
     223**/ 
    185224void linphone_proxy_config_set_route(LinphoneProxyConfig *obj, const char *route) 
    186225{ 
    … …  
    232271} 
    233272 
     273/** 
     274 * Indicates whether a REGISTER request must be sent to the proxy. 
     275**/ 
    234276void linphone_proxy_config_enableregister(LinphoneProxyConfig *obj, bool_t val){ 
    235277        obj->reg_sendregister=val; 
    236278} 
    237279 
     280/** 
     281 * Sets the registration expiration time in seconds. 
     282**/ 
    238283void linphone_proxy_config_expires(LinphoneProxyConfig *obj, int val){ 
    239284        if (val<=0) val=600; 
    … …  
    245290} 
    246291 
     292/** 
     293 * Starts editing a proxy configuration. 
     294 * 
     295 * Because proxy configuration must be consistent, applications MUST 
     296 * call linphone_proxy_config_edit() before doing any attempts to modify 
     297 * proxy configuration (such as identity, proxy address and so on). 
     298 * Once the modifications are done, then the application must call 
     299 * linphone_proxy_config_done() to commit the changes. 
     300**/ 
    247301void linphone_proxy_config_edit(LinphoneProxyConfig *obj){ 
    248302        obj->auth_failures=0; 
    … …  
    281335} 
    282336 
     337/** 
     338 * Commits modification made to the proxy configuration. 
     339**/ 
    283340int linphone_proxy_config_done(LinphoneProxyConfig *obj) 
    284341{ 
    … …  
    465522} 
    466523 
     524 
     525/** 
     526 * Add a proxy configuration. 
     527 * This will start registration on the proxy, if registration is enabled. 
     528**/ 
    467529int linphone_core_add_proxy_config(LinphoneCore *lc, LinphoneProxyConfig *cfg){ 
    468530        if (!linphone_proxy_config_check(lc,cfg)) return -1; 
    … …  
    474536extern void linphone_friend_check_for_removed_proxy(LinphoneFriend *lf, LinphoneProxyConfig *cfg); 
    475537 
     538/** 
     539 * Removes a proxy configuration. 
     540 * 
     541 * LinphoneCore will then automatically unregister and place the proxy configuration 
     542 * on a deleted list. For that reason, a removed proxy does NOT need to be freed. 
     543**/ 
    476544void linphone_core_remove_proxy_config(LinphoneCore *lc, LinphoneProxyConfig *cfg){ 
    477545        MSList *elem; 
    … …  
    491559} 
    492560 
     561/** 
     562 * Sets the default proxy. 
     563 * 
     564 * This default proxy must be part of the list of already entered LinphoneProxyConfig. 
     565 * Toggling it as default will make LinphoneCore use the identity associated with 
     566 * the proxy configuration in all incoming and outgoing calls. 
     567**/ 
    493568void linphone_core_set_default_proxy(LinphoneCore *lc, LinphoneProxyConfig *config){ 
    494569        /* check if this proxy is in our list */ 
    … …  
    509584} 
    510585 
     586/** 
     587 * Returns the default proxy configuration, that is the one used to determine the current identity. 
     588**/ 
    511589int linphone_core_get_default_proxy(LinphoneCore *lc, LinphoneProxyConfig **config){ 
    512590        int pos=-1; 
    … …  
    535613} 
    536614 
     615/** 
     616 * Returns an unmodifiable list of entered proxy configurations. 
     617**/ 
    537618const MSList *linphone_core_get_proxy_config_list(const LinphoneCore *lc){ 
    538619        return lc->sip_conf.proxies; 
    … …  
    682763} 
    683764 
     765/** 
     766 * @} 
     767**/ 
     768 
    684769LinphoneAccountCreator *linphone_account_creator_new(struct _LinphoneCore *core, const char *type){ 
    685770        LinphoneAccountCreator *obj; 
Note: See TracChangeset for help on using the changeset viewer.