Commit 96dc7aac authored by Simon Morlat's avatar Simon Morlat

write documentation of audio conferencing module.

parent 527ca0f4
......@@ -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);
}
/**
* @}
**/
......@@ -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
**/
......
......@@ -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;
}
......
......@@ -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) ;
......
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