Commit 18678159 authored by François Grisez's avatar François Grisez
Browse files

Add a brief to each documentation group

parent cc244afc
......@@ -30,11 +30,13 @@
*/
/**
* @defgroup initializing Initializing liblinphone
* @defgroup initializing Initializing
* @brief Initializing liblinphone.
**/
/**
* @defgroup call_control Placing and receiving calls
* @defgroup call_control Call control
* @brief Placing and receiving calls.
*
* The #LinphoneCall object represents an incoming or outgoing call managed by the #LinphoneCore.
* Outgoing calls can be created using linphone_core_invite() or linphone_core_invite_address(), while incoming calls are notified to the application
......@@ -45,32 +47,40 @@
**/
/**
* @defgroup call_misc Obtaining information about a running call: sound volumes, quality indicators
* @defgroup call_misc Call misc
* @brief Obtaining information about a running call: sound volumes, quality indicators.
*
* When a call is running, it is possible to retrieve in real time current measured volumes and quality indicator.
*
**/
/**
* @defgroup media_parameters Controlling media parameters
*<b> Multicast </b>
*<br> Call using rtp multicast addresses are supported for both audio and video with some limitations. Limitations are, no stun, no ice, no encryption.
*<br><ul><li> Incoming call with multicast address are automatically accepted. The called party switches in a media receive only mode.</li>
*<br><li> Outgoing call willing to send media to a multicast address can activate multicast using \link linphone_core_enable_video_multicast\endlink or
*\link linphone_core_enable_audio_multicast\endlink . The calling party switches in a media listen send only mode.</li>
*</ul>
* @defgroup media_parameters Media parameters
* @brief Controlling media parameters.
*
* <b>Multicast</b>
*
* Call using rtp multicast addresses are supported for both audio and video with some limitations. Limitations are, no stun, no ice, no encryption.
* - Incoming call with multicast address are automatically accepted. The called party switches in a media receive only mode.
* - Outgoing call willing to send media to a multicast address can activate multicast using linphone_core_enable_video_multicast()
* or linphone_core_enable_audio_multicast(). The calling party switches in a media listen send only mode.
**/
/**
* @defgroup proxies Managing proxies
*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.
*<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 LinphoneCoreRegistrationStateChangedCb.
*<br>
*<br> This pseudo code demonstrates basic registration operations:
*<br> \code
* @defgroup proxies Proxies
* @brief Managing proxies.
*
* 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.
* <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 LinphoneCoreRegistrationStateChangedCb.
* <br>
* <br> This pseudo code demonstrates basic registration operations:
* <br> \code
*
* LinphoneProxyConfig* proxy_cfg;
* /*create proxy config*/
......@@ -119,90 +129,102 @@
**/
/**
* @defgroup network_parameters Controlling network parameters (ports, mtu...)
* @defgroup network_parameters Network parameters
* @brief Controlling network parameters (ports, mtu...).
**/
/**
* @defgroup authentication Managing authentication: userid and passwords
* @defgroup authentication Authentication
* @brief Managing authentication: userid and passwords.
**/
/**
* @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().
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.
<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*/
linphone_friend_set_inc_subscribe_policy(my_friend,LinphoneSPAccept); /* accept Incoming subscription request for this friend*/
\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>
Any subsequente modifications to #LinphoneFriend must be first started by a call to function linphone_friend_edit() and validated by function linphone_friend_done()
\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>
<br>Local presence status can be changed using function linphone_core_set_presence_model() .New status is propagated to all friends \link linphone_core_add_friend() previously added \endlink to #LinphoneCore.
<b>Handling incoming subscription request</b>
<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.
<br> A complete tutorial can be found at : \ref buddy_tutorials "Registration tutorial"
* @defgroup buddy_list Buddy list
* @brief 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().
* 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.
* <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*/
* linphone_friend_set_inc_subscribe_policy(my_friend,LinphoneSPAccept); /* accept Incoming subscription request for this friend*/
* \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>
* Any subsequente modifications to #LinphoneFriend must be first started by a call to function linphone_friend_edit() and validated by function linphone_friend_done()
* \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>
* <br>Local presence status can be changed using function linphone_core_set_presence_model() .New status is propagated to all friends \link linphone_core_add_friend() previously added \endlink to #LinphoneCore.
*
* <b>Handling incoming subscription request</b>
* <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.
*
* <br> A complete tutorial can be found at : \ref buddy_tutorials "Registration tutorial"
*
*
**/
/**
* @defgroup chatroom Chat room and Messaging
<b> Exchanging text messages</b>
<br> Messages are sent using #LinphoneChatRoom object. First step is to create a \link linphone_core_get_chat_room() chat room \endlink
from a peer sip uri.
\code
LinphoneChatRoom* chat_room = linphone_core_get_chat_room(lc,"sip:joe@sip.linphone.org");
\endcode
<br>Once created, messages are sent using function linphone_chat_room_send_message().
\code
linphone_chat_room_send_message(chat_room,"Hello world"); /*sending message*/
\endcode
<br>Incoming message are received from call back LinphoneCoreVTable.text_received
\code
void text_received(LinphoneCore *lc, LinphoneChatRoom *room, const LinphoneAddress *from, const char *message) {
printf(" Message [%s] received from [%s] \n",message,linphone_address_as_string (from));
}
\endcode
<br> A complete tutorial can be found at : \ref chatroom_tuto "Chat room tutorial"
* @defgroup chatroom Chatroom
* @brief Chat room and Messaging.
*
* <b> Exchanging text messages</b>
* <br> Messages are sent using #LinphoneChatRoom object. First step is to create a \link linphone_core_get_chat_room() chat room \endlink
* from a peer sip uri.
* \code
* LinphoneChatRoom* chat_room = linphone_core_get_chat_room(lc,"sip:joe@sip.linphone.org");
* \endcode
*
* <br>Once created, messages are sent using function linphone_chat_room_send_message().
* \code
* linphone_chat_room_send_message(chat_room,"Hello world"); /*sending message*/
* \endcode
* <br>Incoming message are received from call back LinphoneCoreVTable.text_received
* \code
* void text_received(LinphoneCore *lc, LinphoneChatRoom *room, const LinphoneAddress *from, const char *message) {
* printf(" Message [%s] received from [%s] \n",message,linphone_address_as_string (from));
* }
* \endcode
* <br> A complete tutorial can be found at : \ref chatroom_tuto "Chat room tutorial"
**/
/**
* @defgroup call_logs Managing call logs
* @defgroup call_logs Call logs
* @brief Managing call logs.
**/
/**
* @defgroup linphone_address SIP address parser API.
* @defgroup linphone_address Linphone address
* @brief SIP address parser API.
* This api is useful for manipulating SIP addresses ('from' or 'to' headers).
**/
/**
* @defgroup conferencing Making an audio conference.
* @defgroup conferencing Conferencing
* @brief Making an audio conference.
*
* This API allows to create a conference entirely managed by the client. No server capabilities are required.
* The way such conference is created is by doing the following:<br>
* The application shall makes "normal" calls to several destinations (using linphone_core_invite() ), one after another.
......@@ -224,12 +246,15 @@ void text_received(LinphoneCore *lc, LinphoneChatRoom *room, const LinphoneAddre
/**
* @defgroup event_api Managing generic subscriptions and publishes
* @defgroup event_api Event api
* @brief Managing generic subscriptions and publishes.
*
* The LinphoneEvent api allows application to control subscriptions, receive notifications and make publish to peers, in a generic manner.
*/
/**
* @defgroup misc Miscenalleous: logs, version strings, config storage
* @defgroup misc Misc
* @brief Miscenalleous: logs, version strings, config storage.
**/
/**
......@@ -244,6 +269,7 @@ void text_received(LinphoneCore *lc, LinphoneChatRoom *room, const LinphoneAddre
/**
* @defgroup IOS IOS
* @ingroup port
*
*<br>
<b>Multitasking</b>
<br> Liblinphone for IOS natively supports multitasking assuming application follows multitasking guides provided by Apple. First step is to declare application as multitasked. It means adding background mode for both audio and voip to Info.plist file.
......@@ -464,7 +490,9 @@ I/lib/Could not find decoder for SILK
*/
/**
* @defgroup wrapper Wrapper utilities
* @defgroup wrapper
* @brief Wrapper utilities.
*
* These functions are used by automatic API wrapper generators and should not
* be used by C API users.
*/
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment