write documentation of audio conferencing module.

coreapi/conference.c

@@ -28,6 +28,12 @@
 
 #include "mediastreamer2/msvolume.h"
 
+/**
+ * @addtogroup conferencing
+ * @{
+**/
+
+
 static int convert_conference_to_call(LinphoneCore *lc);
 
 static void conference_check_init(LinphoneConference *ctx, int samplerate){
@@ -131,6 +137,11 @@ static void add_local_endpoint(LinphoneConference *conf,LinphoneCore *lc){
 	
 }
 
+/**
+ * Returns the sound volume (mic input) of the local participant of the conference.
+ * @param lc the linphone core
+ * @returns the measured input volume expressed in dbm0.
+ **/
 float linphone_core_get_conference_local_input_volume(LinphoneCore *lc){
 	LinphoneConference *conf=&lc->conf_ctx;
 	AudioStream *st=conf->local_participant;
@@ -143,6 +154,16 @@ float linphone_core_get_conference_local_input_volume(LinphoneCore *lc){
 	return LINPHONE_VOLUME_DB_LOWEST;
 }
 
+/**
+ * Merge a call into a conference.
+ * @param lc the linphone core
+ * @param call an established call, either in LinphoneCallStreamsRunning or LinphoneCallPaused state.
+ * 
+ * If this is the first call that enters the conference, the virtual conference will be created automatically.
+ * If the local user was actively part of the call (ie not in paused state), then the local user is automatically entered into the conference.
+ * 
+ * @returns 0 if successful, -1 otherwise.
+**/
 int linphone_core_add_to_conference(LinphoneCore *lc, LinphoneCall *call){
 	LinphoneCallParams params;
 	LinphoneConference *conf=&lc->conf_ctx;
@@ -229,7 +250,18 @@ static int convert_conference_to_call(LinphoneCore *lc){
 	return err;
 }
 
-
+/**
+ * Remove a call from the conference.
+ * @param lc the linphone core
+ * @param call a call that has been previously merged into the conference.
+ * 
+ * After removing the remote participant belonging to the supplied call, the call becomes a normal call in paused state.
+ * If one single remote participant is left alone in the conference after the removal, then it is
+ * automatically removed from the conference and put into a simple call, like before entering the conference.
+ * The conference's resources are then automatically destroyed.
+ * 
+ * @returns 0 if successful, -1 otherwise.
+ **/
 int linphone_core_remove_from_conference(LinphoneCore *lc, LinphoneCall *call){
 	char * str=linphone_call_get_remote_address_as_string(call);
 	ms_message("Removing call %s from the conference", str);
@@ -249,10 +281,21 @@ int linphone_core_remove_from_conference(LinphoneCore *lc, LinphoneCall *call){
 	return err;
 }
 
+/**
+ * Indicates whether the local participant is part of the conference.
+ * @param lc the linphone core
+ * @returns TRUE if the local participant is in the conference, FALSE otherwise.
+**/
 bool_t linphone_core_is_in_conference(const LinphoneCore *lc){
 	return lc->conf_ctx.local_participant!=NULL;
 }
 
+/**
+ * Moves the local participant out of the conference.
+ * @param lc the linphone core
+ * When the local participant is out of the conference, the remote participants can continue to talk normally.
+ * @returns 0 if successful, -1 otherwise.
+**/
 int linphone_core_leave_conference(LinphoneCore *lc){
 	LinphoneConference *conf=&lc->conf_ctx;
 	if (linphone_core_is_in_conference(lc))
@@ -260,7 +303,17 @@ int linphone_core_leave_conference(LinphoneCore *lc){
 	return 0;
 }
 
-
+/**
+ * Moves the local participant inside the conference.
+ * @param lc the linphone core
+ * 
+ * Makes the local participant to join the conference. 
+ * Typically, the local participant is by default always part of the conference when joining an active call into a conference.
+ * However, by calling linphone_core_leave_conference() and linphone_core_enter_conference() the application can decide to temporarily
+ * move out and in the local participant from the conference.
+ * 
+ * @returns 0 if successful, -1 otherwise
+**/
 int linphone_core_enter_conference(LinphoneCore *lc){
 	if (linphone_core_sound_resources_locked(lc)) {
 		return -1;
@@ -273,6 +326,14 @@ int linphone_core_enter_conference(LinphoneCore *lc){
 	return 0;
 }
 
+/**
+ * Add all calls into a conference.
+ * @param lc the linphone core
+ * 
+ * Merge all established calls (either in LinphoneCallStreamsRunning or LinphoneCallPaused) into a conference.
+ * 
+ * @returns 0 if successful, -1 otherwise
+**/
 int linphone_core_add_all_to_conference(LinphoneCore *lc) {
 	MSList *calls=lc->calls;
 	while (calls) {
@@ -286,6 +347,14 @@ int linphone_core_add_all_to_conference(LinphoneCore *lc) {
 	return 0;
 }
 
+/**
+ * Terminates the conference and the calls associated with it.
+ * @param lc the linphone core
+ * 
+ * All the calls that were merged to the conference are terminated, and the conference resources are destroyed.
+ * 
+ * @returns 0 if successful, -1 otherwise
+**/
 int linphone_core_terminate_conference(LinphoneCore *lc) {
 	MSList *calls=lc->calls;
 	while (calls) {
@@ -298,9 +367,23 @@ int linphone_core_terminate_conference(LinphoneCore *lc) {
 	return 0;
 }
 
+/**
+ * Returns the number of participants to the conference, including the local participant.
+ * @param lc the linphone core
+ * 
+ * Typically, after merging two calls into the conference, there is total of 3 participants:
+ * the local participant (or local user), and two remote participants that were the destinations of the two previously establised calls.
+ * 
+ * @returns the number of participants to the conference
+**/
 int linphone_core_get_conference_size(LinphoneCore *lc) {
 	if (lc->conf_ctx.conf == NULL) {
 		return 0;
 	}
 	return ms_audio_conference_get_size(lc->conf_ctx.conf);
 }
+
+/**
+ * @}
+**/
+

coreapi/help/doxygen.dox

@@ -195,6 +195,27 @@ void text_received(LinphoneCore *lc, LinphoneChatRoom *room, const LinphoneAddre
  * This api is useful for manipulating SIP addresses ('from' or 'to' headers).
 **/
 
+/**
+ * @defgroup conferencing 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. 
+ * While initiating the second call, the first one is automatically paused.
+ * Then, once the second call is established, the application has the possibility to merge the two calls to form a conference where each participant
+ * (the local participant, the remote destination of the first call, the remote destination of the second call) can talk together.
+ * This must be done by adding the two calls to the conference using \link linphone_call_add_to_conference() \endlink
+ *
+ * Once merged into a conference the LinphoneCall objects representing the calls that were established remain unchanged, except that 
+ * they are tagged as part of the conference (see \link linphone_call_is_in_conference() \endlink ). The calls in a conference are in the LinphoneCallStreamsRunning state.
+ * 
+ * Only a single conference can be created: the purpose of this feature is to allow the local user to create, take part and manage the conference. 
+ * This API is not designed to create a conference server application.
+ *
+ * Up to 10 calls can be merged into the conference, however depending on the CPU usage required for doing the encoding/decoding of the streams of each participants,
+ * the effective limit can be lower.
+ * 
+**/
+
 /**
  * @defgroup misc Miscenalleous: logs, version strings, config storage
 **/

coreapi/linphonecall.c

@@ -2081,6 +2081,10 @@ void linphone_call_set_transfer_state(LinphoneCall* call, LinphoneCallState stat
 	}
 }
 
+/**
+ * Returns true if the call is part of the conference.
+ * @ingroup conferencing
+**/
 bool_t linphone_call_is_in_conference(const LinphoneCall *call) {
 	return call->params.in_conference;
 }

coreapi/linphonecore.h

@@ -663,13 +663,13 @@ const LinphoneAddress* linphone_chat_room_get_peer_address(LinphoneChatRoom *cr)
  */
 void linphone_chat_room_send_message(LinphoneChatRoom *cr, const char *msg);
 /**
- *LinphoneChatMessageStatus used to notify if message has been succesfully delivered or not
+ *LinphoneChatMessageState is used to notify if messages have been succesfully delivered or not.
  */
 typedef enum _LinphoneChatMessageStates {
-	LinphoneChatMessageStateIdle, /** initial state*/
-	LinphoneChatMessageStateInProgress, /*delivery in progress**/
-	LinphoneChatMessageStateDelivered, /** message succesffully delivered an acknoleged by remote end point*/
-	LinphoneChatMessageStateNotDelivered /** message was not delivered*/
+	LinphoneChatMessageStateIdle, /**<initial state*/
+	LinphoneChatMessageStateInProgress, /**<delivery in progress**/
+	LinphoneChatMessageStateDelivered, /**<message succesffully delivered an acknoleged by remote end point*/
+	LinphoneChatMessageStateNotDelivered /**<message was not delivered*/
 }LinphoneChatMessageState;
 
 	
@@ -679,20 +679,20 @@ typedef enum _LinphoneChatMessageStates {
 const char* linphone_chat_message_state_to_string(const LinphoneChatMessageState state);
 
 /**
- * clone a chat message 
+ * Clone a chat message 
  *@param message #LinphoneChatMessage obj
  *@return #LinphoneChatMessage
  */
 LinphoneChatMessage* linphone_chat_message_clone(const LinphoneChatMessage* message);
 /**
- * set origine of the message
+ * Set origin of the message
  *@param message #LinphoneChatMessage obj
  *@param from #LinphoneAddress origin of this message (copied)
  */
 void linphone_chat_message_set_from(LinphoneChatMessage* message, const LinphoneAddress* from);
 
 /**
- * get origine of the message 
+ * Get origin of the message 
  *@param message #LinphoneChatMessage obj
  *@return #LinphoneAddress
  */
@@ -701,21 +701,21 @@ LinphoneAddress* linphone_chat_message_get_from(const LinphoneChatMessage* messa
 /**
  * Linphone message can carry external body as defined by rfc2017
  * @param message #LinphoneChatMessage
- * @return return external body url null if not present.
+ * @return external body url or NULL if not present.
  */
 const char* linphone_chat_message_get_external_body_url(const LinphoneChatMessage* message);
 	
 /**
  * Linphone message can carry external body as defined by rfc2017
  * 
- * @param  #LinphoneChatMessage  
+ * @param message a LinphoneChatMessage  
  * @param url ex: access-type=URL; URL="http://www.foo.com/file"
  */
 void linphone_chat_message_set_external_body_url(LinphoneChatMessage* message,const char* url);
 
 /**
- * get text part of this message
- *@return text or NULL if no text.
+ * Get text part of this message
+ * @return text or NULL if no text.
  */
 const char * linphone_chat_message_get_text(const LinphoneChatMessage* message);	
 /**
@@ -731,15 +731,15 @@ void linphone_chat_message_set_user_data(LinphoneChatMessage* message,void*);
 /**
  * Call back used to notify message delivery status
  *@param msg #LinphoneChatMessage object
- *@param status #LinphoneChatMessageStatus
- *@param ud us user data
+ *@param status LinphoneChatMessageState
+ *@param ud application user data
  */
 typedef void (*LinphoneChatMessageStateChangeCb)(LinphoneChatMessage* msg,LinphoneChatMessageState state,void* ud);
 /**
  * send a message to peer member of this chat room.
  * @param cr #LinphoneChatRoom object
  * @param msg #LinphoneChatMessage message to be sent
- * @param status_cb #LinphoneChatMessageStatus status call back invoked when to message is delivered or not. May be NULL
+ * @param status_cb LinphoneChatMessageStateChangeCb status callback invoked when message is delivered or could not be delivered. May be NULL
  * @param ud user data for the status cb.
  */
 void linphone_chat_room_send_message2(LinphoneChatRoom *cr, LinphoneChatMessage* msg,LinphoneChatMessageStateChangeCb status_cb,void* ud);
@@ -1055,8 +1055,8 @@ int linphone_core_enable_payload_type(LinphoneCore *lc, PayloadType *pt, bool_t
  * This function searches in audio and video codecs for the given payload type name and clockrate.
  * @param lc #LinphoneCore object
  * @param type payload mime type (I.E SPEEX, PCMU, VP8)
- * @param rate, can be #LINPHONE_FIND_PAYLOAD_IGNORE_RATE
- * @param channels, number of channels, can be #LINPHONE_FIND_PAYLOAD_IGNORE_CHANNELS
+ * @param rate can be #LINPHONE_FIND_PAYLOAD_IGNORE_RATE
+ * @param channels  number of channels, can be #LINPHONE_FIND_PAYLOAD_IGNORE_CHANNELS
  * @return Returns NULL if not found.
  */	
 PayloadType* linphone_core_find_payload_type(LinphoneCore* lc, const char* type, int rate, int channels) ;