/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

/**
 *  @mainpage Portable SIP Stack API
 *
 *  @section intro_sec Introduction
 *  The portable SIP stack is used in multiple SIP endpoints. This document
 *  describes the API's provided by the portable SIP stack that third party
 *  vendors must implement to use the stack.
 *
 *
 *  @section sub_sec Functionality
 *  The SIP stack can be viewed as composed of different components each
 *  dealing with a specific functionality.
 *  functional modules in SIP stack
 *
 *  @subsection Management  Management
 *    This section covers the API that deals with managing the sip stack
 *    initialization, shutdown and state management.
 *    @li cc_types.h @par
 *      Type definitions used by SIP stack
 *    @li cc_constants.h @par
 *      Constant definitions used by call control
 *    @li cc_config.h @par
 *      This section covers API to set config data for the SIP stack
 *    @li cc_service.h @par
 *      Commands to initialize, restart, shutdown sipstack
 *    @li cc_service_listener.h @par
 *      Callbacks from SIP stack for SIP stack and registration status updates
 *
 *  @subsection cf Call Features
 *    Call Control features and calls related APIs
 *    @li cc_call_feature.h @par
 *      APIs to create/terminate calls and invoke call features on them
 *    @li cc_call_listener.h @par
 *      Callbacks for call states and call related data updates
 *    @li cc_info.h @par
 *      API to send a SIP INFO info Message in the context of a call
 *    @li cc_info_listener.h @par
 *      Callback on receipt of SIP INFO Message in the context of a call
 *
 *  @subsection df Device Features
 *    Device based features related APIs
 *    @li cc_device_feature.h @par
 *      APIs to invoke device specific features
 *    @li cc_device_listener.h @par
 *      Callbacks for device specific feature/data updates
 *
 *  @subsection blf BLF APIs
 *    This covers Busy Lamp Field subscription and state notifications
 *    @li cc_blf.h @par
 *      BLF subscription and unsubscription APIs
 *    @li cc_blf_listener.h @par
 *      BLF state change notification call backs
 *
 *  @subsection vcm  Media APIs
 *    Media related APIs
 *    @li vcm.h @par
 *      This file contains API that interface to the media layer on the platform.
 *      The following APIs need to be implemented to have the sip stack interact
 *      and issue commands to the media layer.
 *    @li ccsdp.h @par
 *      Contains helper methods to peek and set video SDP attributes as the SDP negotiation for m lines needs
 *      to be confirmed by the application after examining the SDP attributes. See vcmCheckAttribs and
 *      vcmPopulateAttribs methods in vcm.h
 *
 *  @subsection xml XML
 *    This section covers the XML Parser API that are invoked by the SIP stack to parse  and encode XML bodies
 *    @li xml_parser.h @par
 *      Methods to be implemented by platform for XML enoced and decode operations
 *    @li xml_parser_defines.h @par
 *      Type definitons and data structures used by the XML APIs
 *
 *  @subsection util Utilities
 *    Misc utilities
 *    @li sll_lite.h @par
 *      Simple linked list implementation bundled with SIP stack to be used in xml_parser apis
 *    @li dns_util.h @par
 *      DNS query methods to be implemented by the platform code
 *    @li plat_api.h  @par
 *      APIs that must be implemented by the platform for platform specific functionality
 *
 */

#ifndef _CC_CALL_FEATURE_H_
#define _CC_CALL_FEATURE_H_

#include "cc_constants.h"

/***********************************Basic Call Feature Control Methods************************************
 * This section defines all the call related methods that an upper layer can use to control
 * a call in progress.
 */

/**
 * Used to create any outgoing call regular call. The incoming/reverting/consultation call will be
 * created by the stack. It creates a call place holder and initialize the memory for a call. An user needs
 * other methods to start the call, such as the method OriginateCall, etc
 * @param line line number that is invoked and is assigned
 * @return call handle wich includes the assigned line and call id
 */
cc_call_handle_t CC_createCall(cc_lineid_t line);

/**
 * Start the call that was created.
 * @param call_handle the call handle
 * @param video_pref the sdp direction
 * @return SUCCESS or FAILURE
 */
 /*move it up...*/
cc_return_t CC_CallFeature_originateCall(cc_call_handle_t call_handle, cc_sdp_direction_t video_pref);

/**
 * Terminate or end a normal call.
 * @param call_handle call handle
 * @return SUCCESS or FAILURE
 */
cc_return_t CC_CallFeature_terminateCall(cc_call_handle_t call_handle);

/**
 * Answer an incoming or reverting call.
 * @param call_handle call handle
 * @param video_pref the sdp direction
 * @return SUCCESS or FAILURE
 */
cc_return_t CC_CallFeature_answerCall(cc_call_handle_t call_handle, cc_sdp_direction_t video_pref);

/**
 * Send a keypress to a call, it could be a single digit.
 * @param call_handle call handle
 * @param cc_digit digit pressed
 * @return SUCCESS or FAILURE
 */
cc_return_t CC_CallFeature_sendDigit(cc_call_handle_t call_handle, cc_digit_t cc_digit);

/**
 * Send a backspace action.
 * @param call_handle call handle
 * @return SUCCESS or FAILURE
 */
cc_return_t CC_CallFeature_backSpace(cc_call_handle_t call_handle);

/**
 * Send a dial digit string on an active call, e.g."9191234567".
 * @param call_handle call handle
 * @param video_pref the sdp direction
 * @param numbers dialed string
 * @return SUCCESS or FAILURE
 */
cc_return_t CC_CallFeature_dial(cc_call_handle_t call_handle, cc_sdp_direction_t video_pref, const cc_string_t numbers);

cc_return_t CC_CallFeature_CreateOffer(cc_call_handle_t call_handle, const cc_media_constraints_t *constraints);

cc_return_t CC_CallFeature_CreateAnswer(cc_call_handle_t call_handle, const cc_media_constraints_t *constraints);

cc_return_t CC_CallFeature_SetLocalDescription(cc_call_handle_t call_handle, cc_jsep_action_t action, const char* sdp);

cc_return_t CC_CallFeature_SetRemoteDescription(cc_call_handle_t call_handle, cc_jsep_action_t action, const char* sdp);

cc_return_t CC_CallFeature_SetPeerConnection(cc_call_handle_t call_handle, cc_peerconnection_t pc);

cc_return_t CC_CallFeature_AddStream(cc_call_handle_t call_handle, cc_media_stream_id_t stream_id, cc_media_track_id_t id, cc_media_type_t media_type);

cc_return_t CC_CallFeature_RemoveStream(cc_call_handle_t call_handle, cc_media_stream_id_t stream_id, cc_media_track_id_t id, cc_media_type_t media_type);

cc_return_t CC_CallFeature_AddICECandidate(cc_call_handle_t call_handle, const char* candidate, const char *mid, cc_level_t level);

/**
 * Initiate a speed dial.
 * @param call_handle call handle
 * @param speed_dial_number speed dial number to be dialed.
 * @param video_pref the sdp direction
 * @return SUCCESS or FAILURE
 */
cc_return_t CC_CallFeature_speedDial(cc_call_handle_t call_handle, cc_sdp_direction_t video_pref, const cc_string_t speed_dial_number);

/**
 * Initiate a BLF call pickup.
 * @param call_handle call handle
 * @param speed_dial_number speed dial number configured.
 * @param video_pref the sdp direction
 * @return SUCCESS or FAILURE
 */
cc_return_t CC_CallFeature_blfCallPickup(cc_call_handle_t call_handle, cc_sdp_direction_t video_pref, const cc_string_t speed_dial_number);

/**
 * Redial the last dial numbers.
 * @param call_handle call handle
 * @param video_pref the sdp direction
 * @return SUCCESS or FAILURE
 * @note: if there is no active dial made, this method should not be called.
 */
cc_return_t CC_CallFeature_redial(cc_call_handle_t call_handle, cc_sdp_direction_t video_pref);

/**
 * Update a video media capability for a call. To be used to escalate deescalate video on a specified call
 * @return SUCCESS or FAILURE
 */
cc_return_t CC_CallFeature_updateCallMediaCapability(cc_call_handle_t call_handle, cc_sdp_direction_t video_pref);

/**
 * Make a call forward all on the line identified by the call_handle.
 * @param call_handle call handle
 * @return SUCCESS or FAILURE
 */
cc_return_t CC_CallFeature_callForwardAll(cc_call_handle_t call_handle);

/**
 * Resume a held call.
 * @param call_handle call handle
 * @param video_pref the sdp direction
 * @return SUCCESS or FAILURE
 */
cc_return_t CC_CallFeature_resume(cc_call_handle_t call_handle, cc_sdp_direction_t video_pref);

/**
 * End a consultation call.
 * @param call_handle call handle
 * @return SUCCESS or FAILURE
 */
cc_return_t CC_CallFeature_endConsultativeCall(cc_call_handle_t call_handle);

/**
 * Initiate a conference. Steps to make a conference or transfer:
 * @li Step1 Create a call handle, e.g. chandle1.
 * @li Step2 Start the call on this call handle.
 * @li Step3 When the call is answered, invoke:
 *        CC_CallFeature_conference(chandle1, FALSE, CC_EMPTY_CALL_HANDLE) to start a conference operation.
 * @li Step4 Upon receiving the consultative call (cHandle2) created from pSipcc system,
 *    invoke:
 *        CC_CallFeature_dial(cHandle2)
 * 	  to dial the consultative call.
 * @li Step5 When the consultative call is in ringout or connected state, invoke:
 *        CC_CallFeature_conference(cHandle2, FALSE, CC_EMPTY_CALL_HANDLE) to
 *    finish the conference.
 * Note: @li in the step 4, a user could kill the consultative call and pickup a hold call (not the parent call that
 *    initiated the conference). In this scenario, a parent call handle should be supplied.
 *    For instance,
 *        CC_CallFeature_conference(cHandle2, FALSE, cHandle1)
 *       @li If it's a B2bConf, substitute the "FALSE" with "TRUE"
 *
 * @param call_handle the call handle for
 * 	@li the original connected call.
 * 	@li the consultative call or a held call besides the parent call initiated the transfer. This is used
 * 	   on the second time to finish the transfer.
 * @param is_local Local conference or not. If it's a local conference, it's a b2bconf.
 * @param parent_call_handle if supplied, it will be the targeted parent call handle, which initiated the conference.
 * @param video_pref the sdp direction
 * @return SUCCESS or FAILURE
 */
cc_return_t CC_CallFeature_conference(cc_call_handle_t call_handle, cc_boolean is_local,
		cc_call_handle_t parent_call_handle, cc_sdp_direction_t video_pref);

/**
 * Initiate a call transfer. Please refer to Conference feature.
 * @param call_handle the call handle for
 * 	@li the original connected call.
 * 	@li the consultative call or a held call besides the parent call initiated the transfer. This is used
 * 	   on the second time to finish the transfer.
 * @param parent_call_handle if supplied, it will be the parent call handle, which initiated the transfer.
 * @param video_pref video preference for the consult call as specified by direction
 * @return SUCCESS or FAILURE
 */
cc_return_t CC_CallFeature_transfer(cc_call_handle_t call_handle, cc_call_handle_t parent_call_handle, cc_sdp_direction_t video_pref);


/**
 * Initiate a direct transfer
 * @param call_handle the call handle for the call to initialize a transfer
 * @param target_call_handle the call handle for the target transfer call.
 * @retrun SUCCESS or FAILURE. If the target call handle is empty, a FAILURE will be returned.
 */
cc_return_t CC_CallFeature_directTransfer(cc_call_handle_t call_handle, cc_call_handle_t target_call_handle);

/**
 * Initiate a join across line
 * @param call_handle the call handle for the call that initializes a join across line (conference).
 * @param target_call_handle the call handle for the call will be joined.
 */
cc_return_t CC_CallFeature_joinAcrossLine(cc_call_handle_t call_handle, cc_call_handle_t target_call_handle);

/**
 * Put a connected call on hold.
 * @param call_handle call handle
 * @param reason the reason to hold. The following values should be used.
 * 	  CC_HOLD_REASON_NONE,
 *    CC_HOLD_REASON_XFER, //Hold for transfer
 *    CC_HOLD_REASON_CONF, //Hold for conference
 * @return SUCCESS or FAILURE
 */
cc_return_t CC_CallFeature_holdCall(cc_call_handle_t call_handle, cc_hold_reason_t reason);

/********************************End of basic call feature methods******************************************/

/*************************************Additional call feature methods***************************************
 *
 */
/** @todo if needed
 * Direct transfer a call.
 * @param call_handle call handle
 * @return SUCCESS or FAILURE
 */
//cc_return_t CC_CallFeature_directTransfer(cc_call_handle_t call_handle);

/**
 * Select or locked a call.
 * @param call_handle call handle
 * @return SUCCESS or FAILURE
 */
cc_return_t CC_CallFeature_select(cc_call_handle_t call_handle);

/**
 * Cancel a call feature, e.g. when the consultative call is connected and the
 * user wishes not to make the conference, thie method can be invoked.
 * @param call_handle call handle
 * @return SUCCESS or FAILURE
 */
cc_return_t CC_CallFeature_cancelXfrerCnf(cc_call_handle_t call_handle);

/**
 * Indicate the mute state on the device
 * Used to send a mute state across over CAST to the PC
 */
void CC_CallFeature_mute(cc_boolean mute);

/**
 * Indicate the speaker state on the device
 * Used to send a speaker state across over CAST to the PC
 */
void CC_CallFeature_speaker(cc_boolean mute);

/**
 * Returns the call id of the connected call
 */

cc_call_handle_t CC_CallFeature_getConnectedCall();

#endif /* _CC_CALL_FEATURE_H_ */