sjero.net Git - linphone/blob - coreapi/help/doxygen.dox

   1 /**
   2  * @mainpage
   3  *
   4  * @see http://www.linphone.org
   5  *
   6  * @section what_is_it What is liblinphone
   7  *
   8  * Liblinphone is a high level library for bringing SIP video call functionnality
   9  * into an application. It aims at making easy the integration of the SIP
  10  * video calls into any applications. All variants of linphone are directly based
  11  * on it:
  12  * - linphone (gtk interface)
  13  *
  14  * - linphonec (console interface)
  15  *
  16  * Liblinphone is GPL (see COPYING file). Please understand the licencing details
  17  * before using it!
  18  *
  19  * For any use of this library beyond the rights granted to you by the
  20  * GPL license, please contact Belledonne Communications
  21  * (contact@belledonne-communications.com)
  22  *
  23  *
  24 **/
  25
  26 /**
  27  * @page liblinphone_license COPYING
  28  * @verbinclude COPYING
  29  */
  30
  31 /**
  32  * @defgroup initializing Initializing liblinphone
  33 **/
  34
  35 /**
  36  * @defgroup call_control Placing and receiving calls
  37  *
  38  * The #LinphoneCall object represents an incoming or outgoing call managed by the #LinphoneCore.
  39  * Outgoing calls can be created using linphone_core_invite() or linphone_core_invite_address(), while incoming calls are notified to the application
  40  * through the LinphoneCoreVTable::call_state_changed callback.
  41  *
  42  * See the basic call \ref basic_call_tutorials "tutorial".
  43  *
  44 **/
  45
  46 /**
  47  * @defgroup media_parameters Controlling media parameters
  48 **/
  49
  50 /**
  51  * @defgroup proxies Managing proxies
  52  *User registration is controled by  #LinphoneProxyConfig settings.<br> Each #LinphoneProxyConfig object can be configured with registration informations
  53  *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.
  54  *<br> A created proxy config using linphone_proxy_config_new(), once configured, must be added to #LinphoneCore using function linphone_core_add_proxy_config().
  55  *<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.
  56  *<br> Registration status is reported by #LinphoneRegistrationStateCb.
  57  *<br>
  58  *<br> This pseudo code demonstrates basic registration operations:
  59  *<br> \code
  60  *
  61  *      LinphoneProxyConfig* proxy_cfg;
  62  *      /*create proxy config*/
  63  *      proxy_cfg = linphone_proxy_config_new();
  64  *      /*parse identity*/
  65  *      LinphoneAddress *from = linphone_address_new("sip:toto@sip.titi.com");
  66  *      LinphoneAuthInfo *info;
  67  *      if (password!=NULL){
  68  *              info=linphone_auth_info_new(linphone_address_get_username(from),NULL,"secret",NULL,NULL); /*create authentication structure from identity*/
  69  *              linphone_core_add_auth_info(lc,info); /*add authentication info to LinphoneCore*/
  70  *      }
  71  *      // configure proxy entries
  72  *      linphone_proxy_config_set_identity(proxy_cfg,identity); /*set identity with user name and domain*/
  73  *      const char* server_addr = linphone_address_get_domain(from); /*extract domain address from identity*/
  74  *      linphone_proxy_config_set_server_addr(proxy_cfg,server_addr); /* we assume domain = proxy server address*/
  75  *      linphone_proxy_config_enable_register(proxy_cfg,TRUE); /*activate registration for this proxy config*/
  76  *      linphone_address_destroy(from); /*release resource*/
  77  *
  78  *      linphone_core_add_proxy_config(lc,proxy_cfg); /*add proxy config to linphone core*/
  79  *      linphone_core_set_default_proxy(lc,proxy_cfg); /*set to default proxy*/ \endcode
  80  *<br>
  81  * Registration sate call back:
  82  \code
  83  static void registration_state_changed(struct _LinphoneCore *lc, LinphoneProxyConfig *cfg, LinphoneRegistrationState cstate, const char *message){
  84                 printf("New registration state %s for user id [%s] at proxy [%s]\n"
  85                                 ,linphone_registration_state_to_string(cstate)
  86                                 ,linphone_proxy_config_get_identity(cfg)
  87                                 ,linphone_proxy_config_get_addr(cfg));
  88 }
  89  \endcode
  90  *<br><b>Authentication:</b>
  91  *<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 .
  92  *<br>
  93  *<br><b>Unregistration:</b>
  94  *<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()
  95  *<br> This pseudo code shows how to unregister a user associated to a #LinphoneProxyConfig
  96  *\code
  97         LinphoneProxyConfig* proxy_cfg;
  98         linphone_core_get_default_proxy(lc,&proxy_cfg); /* get default proxy config*/
  99         linphone_proxy_config_edit(proxy_cfg); /*start editing proxy configuration*/
 100         linphone_proxy_config_enable_register(proxy_cfg,FALSE); /*de-activate registration for this proxy config*/
 101         linphone_proxy_config_done(proxy_cfg); /*initiate REGISTER with expire = 0*/
 102 \endcode
 103         <br>
 104         A complete tutorial can be found at : \ref registration_tutorials "Registration tutorial"
 105 **/
 106
 107 /**
 108  * @defgroup network_parameters Controlling network parameters (ports, mtu...)
 109 **/
 110
 111 /**
 112  * @defgroup authentication Managing authentication: userid and passwords
 113 **/
 114
 115 /**
 116 * @defgroup buddy_list Managing Buddies and buddy list and presence
 117 <b>Buddies and buddy list</b>
 118 <br>Each buddy is represented by a #LinphoneFriend object created by function linphone_friend_new().
 119 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.
 120 <br>Here under a typical buddy creation:
 121 <br>
 122 \code
 123 LinphoneFriend* my_friend=linphone_friend_new_with_addr("sip:joe@sip.linphone.org"); /*creates friend object for buddy joe*/
 124 linphone_friend_enable_subscribes(my_friend,TRUE); /*configure this friend to emit SUBSCRIBE message after being added to LinphoneCore*/
 125 linphone_friend_set_inc_subscribe_policy(my_friend,LinphoneSPAccept); /* accept Incoming subscription request for this friend*/
 126 \endcode
 127 \link #LinphoneFriend  friends \endlink status changes are reported by callback LinphoneCoreVTable.notify_presence_recv
 128 \code
 129 static void notify_presence_recv_updated (struct _LinphoneCore *lc,  LinphoneFriend *friend) {
 130         const LinphoneAddress* friend_address = linphone_friend_get_address(friend);
 131         printf("New state state [%s] for user id [%s] \n"
 132                                 ,linphone_online_status_to_string(linphone_friend_get_status(friend))
 133                                 ,linphone_address_as_string (friend_address));
 134 }
 135 \endcode
 136 <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
 137 <br>
 138 Any subsequente modifications to #LinphoneFriend must be first started by a call to function linphone_friend_edit() and validated by  function linphone_friend_done()
 139 \code
 140 linphone_friend_edit(my_friend); /* start editing friend */
 141 linphone_friend_enable_subscribes(my_friend,FALSE); /*disable subscription for this friend*/
 142 linphone_friend_done(my_friend); /*commit changes triggering an UNSUBSCRIBE message*/
 143 \endcode
 144
 145
 146 <b> Publishing presence status </b>
 147 <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.
 148
 149 <b>Handling incoming subscription request</b>
 150 <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
 151 <br> For incoming request comming from an unknown buddy, the call back  LinphoneCoreVTable.new_subscription_request is invoked.
 152
 153 <br> A complete tutorial can be found at : \ref buddy_tutorials "Registration tutorial"
 154
 155
 156 **/
 157
 158 /**
 159 * @defgroup chatroom Chat room and Messaging
 160 <b> Exchanging text messages</b>
 161 <br> Messages are sent using #LinphoneChatRoom object. First step is to create a \link linphone_core_create_chat_room() chat room \endlink
 162 from a peer sip uri.
 163 \code
 164 LinphoneChatRoom* chat_room = linphone_core_create_chat_room(lc,"sip:joe@sip.linphone.org");
 165 \endcode
 166
 167 <br>Once created, messages are sent using function linphone_chat_room_send_message()  .
 168 \code
 169 linphone_chat_room_send_message(chat_room,"Hello world"); /*sending message*/
 170 \endcode
 171 <br>Incoming message are received from call back LinphoneCoreVTable.text_received
 172 \code
 173 void text_received(LinphoneCore *lc, LinphoneChatRoom *room, const LinphoneAddress *from, const char *message) {
 174         printf(" Message [%s] received from [%s] \n",message,linphone_address_as_string (from));
 175 }
 176 \endcode
 177 <br> A complete tutorial can be found at : \ref chatroom_tuto "Chat room tutorial"
 178 **/
 179
 180 /**
 181  * @defgroup call_logs Managing call logs
 182 **/
 183
 184
 185 /**
 186  * @defgroup linphone_address SIP address parser API.
 187  * This api is useful for manipulating SIP addresses ('from' or 'to' headers).
 188 **/
 189
 190 /**
 191  * @defgroup misc Miscenalleous: logs, version strings, config storage
 192 **/
 193
 194 /**
 195  * @defgroup tutorials Tutorials:
 196  *
 197 **/
 198
 199
 200