diff --git a/coreapi/conference.c b/coreapi/conference.c index 5ca465254..9f1538f42 100644 --- a/coreapi/conference.c +++ b/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); } + +/** + * @} +**/ + diff --git a/coreapi/help/doxygen.dox b/coreapi/help/doxygen.dox index 87229f276..8b2e6b7b9 100644 --- a/coreapi/help/doxygen.dox +++ b/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:
+ * 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 **/ diff --git a/coreapi/linphonecall.c b/coreapi/linphonecall.c index d8fdd8803..aa5075ddf 100644 --- a/coreapi/linphonecall.c +++ b/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; } diff --git a/coreapi/linphonecore.h b/coreapi/linphonecore.h index 306f6b70b..f3aa76253 100644 --- a/coreapi/linphonecore.h +++ b/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, /**