doxygen.dox 7.94 KB
Newer Older
jehan's avatar
jehan committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44
/**
 * @mainpage
 *
 * @see http://www.linphone.org
 *
 * @section what_is_it What is liblinphone
 *
 * Liblinphone is a high level library for bringing SIP video call functionnality
 * into an application. It aims at making easy the integration of the SIP
 * video calls into any applications. All variants of linphone are directly based
 * on it:
 * - linphone (gtk interface)
 *
 * - linphonec (console interface)
 *
 * Liblinphone is GPL (see COPYING file). Please understand the licencing details
 * before using it!
 * 
 * For any use of this library beyond the rights granted to you by the
 * GPL license, please contact Belledonne Communications 
 * (contact@belledonne-communications.com)
 * 
 *
**/

/**
 * @page liblinphone_license COPYING 
 * @verbinclude COPYING
 */

/**
 * @defgroup initializing Initializing liblinphone
**/

/**
 * @defgroup call_control Placing and receiving calls
**/

/**
 * @defgroup media_parameters Controlling media parameters
**/

/**
 * @defgroup proxies Managing proxies
45 46
 *User registration is controled by  #LinphoneProxyConfig settings.<br> Each #LinphoneProxyConfig object can be configured with registration informations 
 *like \link linphone_proxy_config_set_server_addr() proxy address \endlink , \link linphone_proxy_config_set_identity() user id \endlink, \link linphone_proxy_config_expires() refresh period \endlink, and so on. 
jehan's avatar
jehan committed
47 48 49 50
 *<br> A created proxy config using linphone_proxy_config_new(), once configured, must be added to #LinphoneCore using function linphone_core_add_proxy_config().
 *<br> It is recommended to set a default \link #LinphoneProxyConfig proxy config \endlink using function linphone_core_set_default_proxy(). Once done, if \link #LinphoneProxyConfig a proxy config \endlink has been configured with attribute \link linphone_proxy_config_enable_register() enable register \endlink  , next call to linphone_core_iterate() triggers a SIP register.  
 *<br> Registration status is reported by #LinphoneRegistrationStateCb.
 *<br>
51
 *<br> This pseudo code demonstrates basic registration operations:
jehan's avatar
jehan committed
52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86
 *<br> \code
 *	
 *	LinphoneProxyConfig* proxy_cfg;
 *	/*create proxy config*/
 *	proxy_cfg = linphone_proxy_config_new();
 *	/*parse identity*/
 *	LinphoneAddress *from = linphone_address_new("sip:toto@sip.titi.com");
 *	LinphoneAuthInfo *info;
 *	if (password!=NULL){
 * 		info=linphone_auth_info_new(linphone_address_get_username(from),NULL,"secret",NULL,NULL); /*create authentication structure from identity*/
 *		linphone_core_add_auth_info(lc,info); /*add authentication info to LinphoneCore*/
 *	}	
 *	// configure proxy entries
 *	linphone_proxy_config_set_identity(proxy_cfg,identity); /*set identity with user name and domain*/
 *	const char* server_addr = linphone_address_get_domain(from); /*extract domain address from identity*/
 *	linphone_proxy_config_set_server_addr(proxy_cfg,server_addr); /* we assume domain = proxy server address*/
 *	linphone_proxy_config_enable_register(proxy_cfg,TRUE); /*activate registration for this proxy config*/
 *	linphone_address_destroy(from); /*release resource*/
 *	
 *	linphone_core_add_proxy_config(lc,proxy_cfg); /*add proxy config to linphone core*/
 *	linphone_core_set_default_proxy(lc,proxy_cfg); /*set to default proxy*/ \endcode
 *<br>
 * Registration sate call back:
 \code
 static void registration_state_changed(struct _LinphoneCore *lc, LinphoneProxyConfig *cfg, LinphoneRegistrationState cstate, const char *message){
		printf("New registration state %s for user id [%s] at proxy [%s]\n"
				,linphone_registration_state_to_string(cstate)
				,linphone_proxy_config_get_identity(cfg)
				,linphone_proxy_config_get_addr(cfg));
}
 \endcode
 *<br><b>Authentication:</b>
 *<br>Most of the time, registration requires \ref authentication "authentication" to succed. #LinphoneAuthInfo info must be either added to #LinphoneCore  using function linphone_core_add_auth_info() before #LinphoneProxyConfig is added to Linphone core, or on demand from call back #AuthInfoRequested .    
 *<br>
 *<br><b>Unregistration:</b>
87 88
 *<br> Unregistration or any changes to #LinphoneProxyConfig must be first started by a call to function linphone_proxy_config_edit() and validated by  function linphone_proxy_config_done()
 *<br> This pseudo code shows how to unregister a user associated to a #LinphoneProxyConfig
jehan's avatar
jehan committed
89 90 91 92 93 94
 *\code
 	LinphoneProxyConfig* proxy_cfg;
 	linphone_core_get_default_proxy(lc,&proxy_cfg); /* get default proxy config*/
	linphone_proxy_config_edit(proxy_cfg); /*start editing proxy configuration*/
	linphone_proxy_config_enable_register(proxy_cfg,FALSE); /*de-activate registration for this proxy config*/
	linphone_proxy_config_done(proxy_cfg); /*initiate REGISTER with expire = 0*/
jehan's avatar
jehan committed
95
\endcode
jehan's avatar
jehan committed
96
	<br>
jehan's avatar
jehan committed
97
	A complete tutorial can be found at : \ref registration_tutorials "Registration tutorial" 
jehan's avatar
jehan committed
98 99 100 101 102 103 104 105 106 107
**/

/**
 * @defgroup network_parameters Controlling network parameters (ports, mtu...)
**/

/**
 * @defgroup authentication Managing authentication: userid and passwords
**/

jehan's avatar
jehan committed
108
/**
jehan's avatar
jehan committed
109 110 111
* @defgroup buddy_list Managing Buddies and buddy list and presence 
<b>Buddies and buddy list</b>
<br>Each buddy is represented by a #LinphoneFriend object created by function linphone_friend_new(). 
jehan's avatar
jehan committed
112
Buddy configuration parameters like \link linphone_friend_set_addr() sip uri \endlink or  \link linphone_friend_set_inc_subscribe_policy() status publication \endlink policy for this \link #LinphoneFriend friend \endlink  are configurable for each buddy.
jehan's avatar
jehan committed
113 114 115 116 117
<br>Here under a typical buddy creation:
<br>
\code
LinphoneFriend* my_friend=linphone_friend_new_with_addr("sip:joe@sip.linphone.org"); /*creates friend object for buddy joe*/
linphone_friend_enable_subscribes(my_friend,TRUE); /*configure this friend to emit SUBSCRIBE message after being added to LinphoneCore*/
jehan's avatar
jehan committed
118
linphone_friend_set_inc_subscribe_policy(my_friend,LinphoneSPAccept); /* accept Incoming subscription request for this friend*/
jehan's avatar
jehan committed
119 120 121 122 123 124 125 126 127 128 129 130
\endcode
\link #LinphoneFriend  friends \endlink status changes are reported by callback LinphoneCoreVTable.notify_presence_recv
\code
static void notify_presence_recv_updated (struct _LinphoneCore *lc,  LinphoneFriend *friend) {
	const LinphoneAddress* friend_address = linphone_friend_get_address(friend);
	printf("New state state [%s] for user id [%s] \n"
				,linphone_online_status_to_string(linphone_friend_get_status(friend))
				,linphone_address_as_string (friend_address));
}
\endcode
<br>Once created a buddy can be added to the buddy list using function linphone_core_add_friend() . Added friends will be notified about \link linphone_core_set_presence_info() local status changes \endlink
<br>
jehan's avatar
jehan committed
131
Any subsequente modifications to #LinphoneFriend must be first started by a call to function linphone_friend_edit() and validated by  function linphone_friend_done()
jehan's avatar
jehan committed
132 133 134 135 136 137 138 139
\code
linphone_friend_edit(my_friend); /* start editing friend */
linphone_friend_enable_subscribes(my_friend,FALSE); /*disable subscription for this friend*/
linphone_friend_done(my_friend); /*commit changes triggering an UNSUBSCRIBE message*/
\endcode


<b> Publishing presence status </b>
jehan's avatar
jehan committed
140
<br>Local presence status can be changed using function linphone_core_set_presence_info() .New status is propagated to all friends \link linphone_core_add_friend() previously added \endlink to #LinphoneCore. 
jehan's avatar
jehan committed
141 142

<b>Handling incoming subscription request</b>
jehan's avatar
jehan committed
143 144
<br> New incoming subscription requests are process according to \link linphone_friend_set_inc_subscribe_policy() the incoming subscription policy state \endlink for subscription initiated by \link linphone_core_add_friend() members of the buddy list. \endlink
<br> For incoming request comming from an unknown buddy, the call back  LinphoneCoreVTable.new_subscription_request is invoked.
jehan's avatar
jehan committed
145 146 147 148

<br> A complete tutorial can be found at : \ref buddy_tutorials "Registration tutorial" 


jehan's avatar
jehan committed
149 150 151
*/


jehan's avatar
jehan committed
152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172
/**
 * @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
**/

/**
 * @defgroup tutorials Tutorials: 
 *
**/