/*
 * Copyright (c) 2010-2019 Belledonne Communications SARL.
 *
 * This file is part of mediastreamer2.
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program. If not, see <http://www.gnu.org/licenses/>.
 */

/*
 * Convenient API to create and manage audio conferences.
 */

#ifndef msconference_h
#define msconference_h

#include "mediastreamer2/mediastream.h"

/**
 * @addtogroup mediastreamer2_audio_conference
 * @{
 */

struct _MSAudioConference;
struct _MSAudioEndpoint;

typedef void (*MSAudioConferenceNotifyActiveTalker)(struct _MSAudioConference *, struct _MSAudioEndpoint *ep);

/**
 * Structure that holds audio conference parameters
**/
struct _MSAudioConferenceParams{
	int samplerate; /**< Conference audio sampling rate in Hz: 8000, 16000 ...*/
	MSAudioConferenceNotifyActiveTalker active_talker_callback;
	void *user_data;
};

/**
 * Typedef to structure that holds conference parameters
**/
typedef struct _MSAudioConferenceParams MSAudioConferenceParams;

/**
 * The MSAudioConference is the object representing an audio conference.
 *
 * First, the conference has to be created with ms_audio_conference_new(), with parameters supplied.
 * Then, participants to the conference can be added with ms_audio_conference_add_member().
 * The MSAudioConference takes in charge the mixing and dispatching of the audio to the participants.
 * If participants (MSAudioEndpoint) are using sampling rate different from the conference, then sample rate converters are automatically added
 * and configured.
 * Participants can be removed from the conference with ms_audio_conference_remove_member().
 * The conference processing is performed in a new thread run by a MSTicker object, which is owned by the conference.
 * When all participants are removed, the MSAudioConference object can then be safely destroyed with ms_audio_conference_destroy().
**/
typedef struct _MSAudioConference MSAudioConference;


/**
 * The MSAudioEndpoint represents a participant in the conference.
 * It can be constructed from an existing AudioStream object with
 * ms_audio_endpoint_get_from_stream().
**/
typedef struct _MSAudioEndpoint MSAudioEndpoint;



#ifdef __cplusplus
extern "C" {
#endif

/**
 * Creates a conference.
 * @param params a MSAudioConferenceParams structure, containing conference parameters.
 * @param factory a MSFactory structure, containing filters parameters
 * @return a MSAudioConference object.
**/
MS2_PUBLIC MSAudioConference * ms_audio_conference_new(const MSAudioConferenceParams *params, MSFactory *factory);

/**
 * Gets conference's current parameters.
 * @param obj the conference.
 * @return a read-only pointer to the conference parameters.
**/
MS2_PUBLIC const MSAudioConferenceParams *ms_audio_conference_get_params(MSAudioConference *obj);

/**
 * Adds a participant to the conference.
 * @param obj the conference
 * @param ep the participant, represented as a MSAudioEndpoint object
**/
MS2_PUBLIC void ms_audio_conference_add_member(MSAudioConference *obj, MSAudioEndpoint *ep);

/**
 * Removes a participant from the conference.
 * @param obj the conference
 * @param ep the participant, represented as a MSAudioEndpoint object
**/
MS2_PUBLIC void ms_audio_conference_remove_member(MSAudioConference *obj, MSAudioEndpoint *ep);


/**
 * Process events of the audio conference.
 * Calling this method periodically (for example every 50 ms), is necessary
 * to receive the active talker notifications to the callback set in the MSAudioConferenceParams.
 * @param obj the conference
**/
MS2_PUBLIC void ms_audio_conference_process_events(MSAudioConference *obj);
/**
 * Mutes or unmutes a participant.
 * 
 * @param obj the conference
 * @param ep the participant, represented as a MSAudioEndpoint object
 * @param muted true to mute the participant, false to unmute.
 *
 * By default all participants are unmuted.
**/
MS2_PUBLIC void ms_audio_conference_mute_member(MSAudioConference *obj, MSAudioEndpoint *ep, bool_t muted);

/**
 * Returns the size (ie the number of participants) of a conference.
 * @param obj the conference
**/
MS2_PUBLIC int ms_audio_conference_get_size(MSAudioConference *obj);

/**
 * Destroys a conference.
 * @param obj the conference
 * All participants must have been removed before destroying the conference.
**/
MS2_PUBLIC void ms_audio_conference_destroy(MSAudioConference *obj);

/**
 * Creates an MSAudioEndpoint from an existing AudioStream.
 *
 * In order to create graphs for audio processing of each participant, the AudioStream object is used, because
 * this object already handles all the processing for volume control, encoding, decoding, etc...
 *
 * The construction of the participants depends whether it is a remote participant, that is somebody in the network
 * sending and receiving audio through RTP, or a local participant, that is somebody using the local soundcard to capture
 * and play audio.
 *
 * To create a remote participant, first create and start an AudioStream for the participant with audio_stream_new() and
 * audio_stream_start_with_files(), given NULL arguments as input and output files.
 * This participant does not interact with soundcards, this is why we suggest to use audio_stream_start_full() to avoid 
 * holding any reference to the sound system.
 * Then, create a MSAudioEndpoint representing this participant by calling ms_audio_endpoint_get_from_stream() with
 * is_remote=TRUE.
 *
 * To create a local participant, first create and start an AudioStream with audio_stream_new() and audio_stream_start_full(), 
 * with real soundcard arguments.
 * Arguments controlling RTP should be filled with placeholders value and will not be used for conferencing.
 * Then, create a MSAudioEndpoint representing this local participant by calling ms_audio_endpoint_get_from_stream() 
 * with the audiostream and is_remote=FALSE.<br>
 * For example:<br>
 * <PRE>
 * AudioStream *st=audio_stream_new(65000,65001,FALSE);
 * audio_stream_start_full(st, conf->local_dummy_profile,
 *				"127.0.0.1",
 *				65000,
 *				"127.0.0.1",
 *				65001,
 *				0,
 *				40,
 *				NULL,
 *				NULL,
 *				playcard,
 *				captcard,
 *				needs_echocancellation,
 *				);
 * MSAudioEndpoint *local_endpoint=ms_audio_endpoint_get_from_stream(st,FALSE);
 * </PRE>
**/
MS2_PUBLIC MSAudioEndpoint * ms_audio_endpoint_get_from_stream(AudioStream *st, bool_t is_remote);

/**
 * Associate a user pointer to the endpoint.
 * @param ep the endpoint
 * @param user_data the user data
 */
MS2_PUBLIC void ms_audio_endpoint_set_user_data(MSAudioEndpoint *ep, void *user_data);

/**
 * Get the user pointer associated to the endpoint.
 * @param ep the endpoint
 * @return the user data
 */
MS2_PUBLIC void * ms_audio_endpoint_get_user_data(const MSAudioEndpoint *ep);


/**
 * Destroys a MSAudioEndpoint that was created from an AudioStream with ms_audio_endpoint_get_from_stream().
 * The AudioStream can then be destroyed if needed.
**/
MS2_PUBLIC void ms_audio_endpoint_release_from_stream(MSAudioEndpoint *obj);

/**
 * Creates an audio endpoint (or virtual participant) to record the conference into a wav file.
 * @param factory The factory used by the linphone core.
**/
MS2_PUBLIC MSAudioEndpoint * ms_audio_endpoint_new_recorder(MSFactory* factory);

/**
 * Start audio recording.
 * The endpoint must have been created by ms_audio_endpoint_new_recorder().
 * @param ep the endpoint
 * @param path path for the wav file where to record samples.
 * @return 0 if successful, -1 if the path is invalid.
**/
MS2_PUBLIC int ms_audio_recorder_endpoint_start(MSAudioEndpoint *ep, const char *path);

/**
 * Stop audio recording.
 * The endpoint must have been created by ms_audio_endpoint_new_recorder().
 * @param ep the endpoint
 * @return 0 if successful, -1 if the record wasn't started.
**/
MS2_PUBLIC int ms_audio_recorder_endpoint_stop(MSAudioEndpoint *ep);

/**
 * Destroy an audio endpoint.
 * @note Endpoints created by ms_audio_endpoint_get_from_stream() must be released by ms_audio_endpoint_release_from_stream().
**/
MS2_PUBLIC void ms_audio_endpoint_destroy(MSAudioEndpoint *ep);

#ifdef __cplusplus
}
#endif

/**
 * @}
 */

/**
 * @addtogroup mediastreamer2_video_conference
 * @{
 */

/**
 * Structure that holds audio conference parameters
**/
struct _MSVideoConferenceParams{
	int min_switch_interval;
	const char *codec_mime_type;
};

/**
 * Typedef to structure that holds conference parameters
**/
typedef struct _MSVideoConferenceParams MSVideoConferenceParams;

/**
 * The MSVideoConference is the object representing a video conference.
 *
 * First, the conference has to be created with ms_video_conference_new(), with parameters supplied.
 * Then, participants to the conference can be added with ms_video_conference_add_member().
 * Participants can be removed from the conference with ms_video_conference_remove_member().
 * The conference processing is performed in a new thread run by a MSTicker object, which is owned by the conference.
 * When all participants are removed, the MSVideoConference object can then be safely destroyed with ms_video_conference_destroy().
**/
typedef struct _MSVideoConference MSVideoConference;


/**
 * The MSVideoEndpoint represents a participant in the conference.
 * It can be constructed from an existing VideoStream object with
 * ms_video_endpoint_get_from_stream().
**/
typedef struct _MSVideoEndpoint MSVideoEndpoint;




#ifdef __cplusplus
extern "C" {
#endif

/**
 * Creates a conference.
 * @param params a MSVideoConferenceParams structure, containing conference parameters.
 * @returns a MSVideoConference object.
**/
MS2_PUBLIC MSVideoConference * ms_video_conference_new(MSFactory *factory, const MSVideoConferenceParams *params);

/**
 * Gets conference's current parameters.
 * @param obj the conference.
 * @returns a read-only pointer to the conference parameters.
**/
MS2_PUBLIC const MSVideoConferenceParams *ms_video_conference_get_params(MSVideoConference *obj);

/**
 * Adds a participant to the conference.
 * @param obj the conference
 * @param ep the participant, represented as a MSVideoEndpoint object
**/
MS2_PUBLIC void ms_video_conference_add_member(MSVideoConference *obj, MSVideoEndpoint *ep);

/**
 * Removes a participant from the conference.
 * @param obj the conference
 * @param ep the participant, represented as a MSVideoEndpoint object
**/
MS2_PUBLIC void ms_video_conference_remove_member(MSVideoConference *obj, MSVideoEndpoint *ep);


/**
 * Switch the focus of the video conf on a given member.
 * @param obj the conference
 * @param ep the participant, represented as a MSVideoEndpoint object
 */
MS2_PUBLIC void ms_video_conference_set_focus(MSVideoConference *obj, MSVideoEndpoint *ep);

/**
* Get the video placeholder member, as MSVideoEndpoint.
* @param obj the conference
* @return a MSVideoEndpoint object.
*/
MS2_PUBLIC MSVideoEndpoint *ms_video_conference_get_video_placeholder_member(const MSVideoConference *obj);

/**
 * Get the list of members, as MSVideoEndpoints.
 * @param obj the conference
 * @return a list of MSVideoEndpoint objects.
 */
MS2_PUBLIC const bctbx_list_t* ms_video_conference_get_members(const MSVideoConference *obj);

/**
 * Put an audio conference and a video conference in relationship.
 * The audio conference will monitor the active speaker, and notify the video conference.
 * @param obj the video conference
 * @param obj the audio conference
 */
MS2_PUBLIC void ms_video_conference_set_audio_conference(MSVideoConference *obj, MSAudioConference *audioconf);

/**
 * Returns the size (ie the number of participants) of a conference.
 * @param obj the conference
**/
MS2_PUBLIC int ms_video_conference_get_size(MSVideoConference *obj);

/**
 * Destroys a conference.
 * @param obj the conference
 * All participants must have been removed before destroying the conference.
**/
MS2_PUBLIC void ms_video_conference_destroy(MSVideoConference *obj);

/**
 * Creates an MSVideoEndpoint from an existing VideoStream.
 *
 * In order to create graphs for video processing of each participant, the VideoStream object is used, because
 * this object already handles all the processing for encoding, decoding, etc...
 *
 * The construction of the participants depends whether it is a remote participant, that is somebody in the network
 * sending and receiving video through RTP, or a local participant, that is somebody using the local camera to capture
 * and local screen to display video.
 *
 * To create a remote participant, first create and start a VideoStream for the participant with video_stream_new() and
 * video_stream_start() with NULL MSWebCam argument.
 * Then, create a MSVideoEndpoint representing this participant by calling ms_video_endpoint_get_from_stream() with
 * is_remote=TRUE.
 *
 * To create a local participant, first create and start a VideoStream with video_stream_new() and video_stream_start(), 
 * with the correct MSWebCam to use.
 * Arguments controlling RTP should be filled with placeholders value and will not be used for conferencing.
 * Then, create a MSVideoEndpoint representing this local participant by calling ms_video_endpoint_get_from_stream() 
 * with the video stream and is_remote=FALSE.<br>
 * For example:<br>
 * <PRE>
 * VideoStream *st=video_stream_new(65000,65001,FALSE);
 * video_stream_start(st, conf->local_dummy_profile,
 *				"127.0.0.1",
 *				65000,
 *				"127.0.0.1",
 *				65001,
 *				0,
 *				40,
 *				webcam
 *				);
 * MSVideoEndpoint *local_endpoint=ms_video_endpoint_get_from_stream(st,FALSE);
 * </PRE>
**/
MS2_PUBLIC MSVideoEndpoint * ms_video_endpoint_get_from_stream(VideoStream *st, bool_t is_remote);


/**
 * Associate a user pointer to the endpoint.
 * @param ep the endpoint
 * @param user_data the user data
 */
MS2_PUBLIC void ms_video_endpoint_set_user_data(MSVideoEndpoint *ep, void *user_data);

/**
 * Get the user pointer associated to the endpoint.
 * @param ep the endpoint
 * @return the user data
 */
MS2_PUBLIC void * ms_video_endpoint_get_user_data(const MSVideoEndpoint *ep);


/**
 * Destroys a MSVideoEndpoint that was created from a VideoStream with ms_video_endpoint_get_from_stream().
 * The VideoStream can then be destroyed if needed.
**/
MS2_PUBLIC void ms_video_endpoint_release_from_stream(MSVideoEndpoint *obj);


#ifdef __cplusplus
}
#endif

/**
 * @}
 */

#endif