/*
* Copyright (C) 2012-2013 Teluu Inc. (http://www.teluu.com)
*
* 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 2 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, write to the Free Software
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
*/
#ifndef __PJSUA2_CALL_HPP__
#define __PJSUA2_CALL_HPP__
/**
* @file pjsua2/call.hpp
* @brief PJSUA2 Call manipulation
*/
#include <pjsua-lib/pjsua.h>
#include <pjsua2/media.hpp>
/** PJSUA2 API is inside pj namespace */
namespace pj
{
/**
* @defgroup PJSUA2_CALL Call
* @ingroup PJSUA2_Ref
*/
/**
* @defgroup PJSUA2_Call_Data_Structure Call Related Types
* @ingroup PJSUA2_DS
* @{
*/
using std::string;
using std::vector;
//////////////////////////////////////////////////////////////////////////////
/**
* Media stream, corresponds to pjmedia_stream
*/
typedef void *MediaStream;
/**
* Media transport, corresponds to pjmedia_transport
*/
typedef void *MediaTransport;
/**
* This structure describes statistics state.
*/
struct MathStat
{
int n; /**< number of samples */
int max; /**< maximum value */
int min; /**< minimum value */
int last; /**< last value */
int mean; /**< mean */
public:
/**
* Default constructor
*/
MathStat();
/**
* Convert from pjsip
*/
void fromPj(const pj_math_stat &prm);
};
/**
* Types of loss detected.
*/
struct LossType
{
unsigned burst; /**< Burst/sequential packet lost detected */
unsigned random; /**< Random packet lost detected. */
};
/**
* Unidirectional RTP stream statistics.
*/
struct RtcpStreamStat
{
TimeVal update; /**< Time of last update. */
unsigned updateCount;/**< Number of updates (to calculate avg) */
unsigned pkt; /**< Total number of packets */
unsigned bytes; /**< Total number of payload/bytes */
unsigned discard; /**< Total number of discarded packets. */
unsigned loss; /**< Total number of packets lost */
unsigned reorder; /**< Total number of out of order packets */
unsigned dup; /**< Total number of duplicates packets */
MathStat lossPeriodUsec; /**< Loss period statistics */
LossType lossType; /**< Types of loss detected. */
MathStat jitterUsec; /**< Jitter statistics */
public:
/**
* Convert from pjsip
*/
void fromPj(const pjmedia_rtcp_stream_stat &prm);
};
/**
* RTCP SDES structure.
*/
struct RtcpSdes
{
string cname; /**< RTCP SDES type CNAME. */
string name; /**< RTCP SDES type NAME. */
string email; /**< RTCP SDES type EMAIL. */
string phone; /**< RTCP SDES type PHONE. */
string loc; /**< RTCP SDES type LOC. */
string tool; /**< RTCP SDES type TOOL. */
string note; /**< RTCP SDES type NOTE. */
public:
/**
* Convert from pjsip
*/
void fromPj(const pjmedia_rtcp_sdes &prm);
};
/**
* Bidirectional RTP stream statistics.
*/
struct RtcpStat
{
TimeVal start; /**< Time when session was created */
RtcpStreamStat txStat; /**< Encoder stream statistics. */
RtcpStreamStat rxStat; /**< Decoder stream statistics. */
MathStat rttUsec; /**< Round trip delay statistic. */
pj_uint32_t rtpTxLastTs; /**< Last TX RTP timestamp. */
pj_uint16_t rtpTxLastSeq; /**< Last TX RTP sequence. */
MathStat rxIpdvUsec; /**< Statistics of IP packet delay
variation in receiving
direction. It is only used when
PJMEDIA_RTCP_STAT_HAS_IPDV is
set to non-zero. */
MathStat rxRawJitterUsec;/**< Statistic of raw jitter in
receiving direction. It is only
used when
PJMEDIA_RTCP_STAT_HAS_RAW_JITTER
is set to non-zero. */
RtcpSdes peerSdes; /**< Peer SDES. */
public:
/**
* Convert from pjsip
*/
void fromPj(const pjmedia_rtcp_stat &prm);
};
/**
* This structure describes jitter buffer state.
*/
struct JbufState
{
/* Setting */
unsigned frameSize; /**< Individual frame size, in bytes. */
unsigned minPrefetch; /**< Minimum allowed prefetch, in frms. */
unsigned maxPrefetch; /**< Maximum allowed prefetch, in frms. */
/* Status */
unsigned burst; /**< Current burst level, in frames */
unsigned prefetch; /**< Current prefetch value, in frames */
unsigned size; /**< Current buffer size, in frames. */
/* Statistic */
unsigned avgDelayMsec; /**< Average delay, in ms. */
unsigned minDelayMsec; /**< Minimum delay, in ms. */
unsigned maxDelayMsec; /**< Maximum delay, in ms. */
unsigned devDelayMsec; /**< Standard deviation of delay, in ms.*/
unsigned avgBurst; /**< Average burst, in frames. */
unsigned lost; /**< Number of lost frames. */
unsigned discard; /**< Number of discarded frames. */
unsigned empty; /**< Number of empty on GET events. */
public:
/**
* Convert from pjsip
*/
void fromPj(const pjmedia_jb_state &prm);
};
/**
* This structure describes SDP session description. It corresponds to the
* pjmedia_sdp_session structure.
*/
struct SdpSession
{
/**
* The whole SDP as a string.
*/
string wholeSdp;
/**
* Pointer to its original pjmedia_sdp_session. Only valid when the struct
* is converted from PJSIP's pjmedia_sdp_session.
*/
void *pjSdpSession;
public:
/**
* Convert from pjsip
*/
void fromPj(const pjmedia_sdp_session &sdp);
};
/**
* This structure describes media transport informations. It corresponds to the
* pjmedia_transport_info structure. The address name field can be empty string
* if the address in the pjmedia_transport_info is invalid.
*/
struct MediaTransportInfo
{
/**
* Address to be advertised as the local address for the RTP socket,
* which does not need to be equal as the bound address (for example,
* this address can be the address resolved with STUN).
*/
SocketAddress localRtpName;
/**
* Address to be advertised as the local address for the RTCP socket,
* which does not need to be equal as the bound address (for example,
* this address can be the address resolved with STUN).
*/
SocketAddress localRtcpName;
/**
* Remote address where RTP originated from. This can be empty string if
* no data is received from the remote.
*/
SocketAddress srcRtpName;
/**
* Remote address where RTCP originated from. This can be empty string if
* no data is recevied from the remote.
*/
SocketAddress srcRtcpName;
public:
/**
* Convert from pjsip
*/
void fromPj(const pjmedia_transport_info &info);
};
//////////////////////////////////////////////////////////////////////////////
/** Array of media direction */
typedef IntVector MediaDirVector;
/**
* Call settings.
*/
struct CallSetting
{
/**
* Bitmask of pjsua_call_flag constants.
*
* Default: PJSUA_CALL_INCLUDE_DISABLED_MEDIA
*/
unsigned flag;
/**
* This flag controls what methods to request keyframe are allowed on
* the call. Value is bitmask of pjsua_vid_req_keyframe_method.
*
* Default: PJSUA_VID_REQ_KEYFRAME_SIP_INFO |
* PJSUA_VID_REQ_KEYFRAME_RTCP_PLI
*/
unsigned reqKeyframeMethod;
/**
* Number of simultaneous active audio streams for this call. Setting
* this to zero will disable audio in this call.
*
* Default: 1
*/
unsigned audioCount;
/**
* Number of simultaneous active video streams for this call. Setting
* this to zero will disable video in this call.
*
* Default: 1 (if video feature is enabled, otherwise it is zero)
*/
unsigned videoCount;
/**
* Media direction. This setting will only be used if the flag
* PJSUA_CALL_SET_MEDIA_DIR is set, and it will persist for subsequent
* offers or answers.
* For example, a media that is set as PJMEDIA_DIR_ENCODING can only
* mark the stream in the SDP as sendonly or inactive, but will not
* become sendrecv in subsequent offers and answers.
* Application can update the media direction in any API or callback
* that accepts CallSetting as a parameter, such as via
* Call::reinvite/update() or in onCallRxOffer/Reinvite()
* callback.
*
* The index of the media dir will correspond to the provisional media
* in CallInfo.provMedia.
* For offers that involve adding new medias (such as initial offer),
* the index will correspond to all new audio media first, then video.
* For example, for a new call with 2 audios and 1 video, mediaDir[0]
* and mediaDir[1] will be for the audios, and mediaDir[2] video.
*
* Default: empty vector
*/
MediaDirVector mediaDir;
/**
* User defined Call-ID to be sent out with outgoing INVITE.
*
* Note: It is up to the developer to verify uniqueness of the
* Call-ID as there will be no verification. The developer must
* change the Call-ID between calls creating a unique id for each
* outgoing call.
*
* This setting will only be used when creating a new outgoing call
* via Call::makeCall().
*/
string customCallId;
public:
/**
* Default constructor initializes with empty or default values.
*/
CallSetting(bool useDefaultValues = false);
/**
* Check if the settings are set with empty values.
*
* @return True if the settings are empty.
*/
bool isEmpty() const;
/**
* Convert from pjsip
*/
void fromPj(const pjsua_call_setting &prm);
/**
* Convert to pjsip
*/
pjsua_call_setting toPj() const;
};
/**
* Call media information.
*
* Application can query conference bridge port of this media using
* Call::getAudioMedia() if the media type is audio,
* or Call::getEncodingVideoMedia() / Call::getDecodingVideoMedia()
* if the media type is video.
*/
struct CallMediaInfo
{
/**
* Media index in SDP.
*/
unsigned index;
/**
* Media type.
*/
pjmedia_type type;
/**
* Media direction.
*/
pjmedia_dir dir;
/**
* Call media status.
*/
pjsua_call_media_status status;
/**
* Warning: this is deprecated, application can query conference bridge
* port of this media using Call::getAudioMedia().
*
* The conference port number for the call. Only valid if the media type
* is audio.
*/
int audioConfSlot;
/**
* The window id for incoming video, if any, or
* PJSUA_INVALID_ID. Only valid if the media type is video.
*/
pjsua_vid_win_id videoIncomingWindowId;
/**
* The video window instance for incoming video. Only valid if
* videoIncomingWindowId is not PJSUA_INVALID_ID and
* the media type is video.
*/
VideoWindow videoWindow;
/**
* The video capture device for outgoing transmission, if any,
* or PJMEDIA_VID_INVALID_DEV. Only valid if the media type is video.
*/
pjmedia_vid_dev_index videoCapDev;
public:
/**
* Default constructor
*/
CallMediaInfo();
/**
* Convert from pjsip
*/
void fromPj(const pjsua_call_media_info &prm);
};
/** Array of call media info */
typedef std::vector<CallMediaInfo> CallMediaInfoVector;
/**
* Call information. Application can query the call information
* by calling Call::getInfo().
*/
struct CallInfo
{
/**
* Call identification.
*/
pjsua_call_id id;
/**
* Initial call role (UAC == caller)
*/
pjsip_role_e role;
/**
* The account ID where this call belongs.
*/
pjsua_acc_id accId;
/**
* Local URI
*/
string localUri;
/**
* Local Contact
*/
string localContact;
/**
* Remote URI
*/
string remoteUri;
/**
* Remote contact
*/
string remoteContact;
/**
* Dialog Call-ID string.
*/
string callIdString;
/**
* Call setting
*/
CallSetting setting;
/**
* Call state
*/
pjsip_inv_state state;
/**
* Text describing the state
*/
string stateText;
/**
* Last status code heard, which can be used as cause code
*/
pjsip_status_code lastStatusCode;
/**
* The reason phrase describing the last status.
*/
string lastReason;
/**
* Array of active media information.
*/
CallMediaInfoVector media;
/**
* Array of provisional media information. This contains the media info
* in the provisioning state, that is when the media session is being
* created/updated (SDP offer/answer is on progress).
*/
CallMediaInfoVector provMedia;
/**
* Up-to-date call connected duration (zero when call is not
* established)
*/
TimeVal connectDuration;
/**
* Total call duration, including set-up time
*/
TimeVal totalDuration;
/**
* Flag if remote was SDP offerer
*/
bool remOfferer;
/**
* Number of audio streams offered by remote
*/
unsigned remAudioCount;
/**
* Number of video streams offered by remote
*/
unsigned remVideoCount;
public:
/**
* Default constructor
*/
CallInfo() : id(PJSUA_INVALID_ID),
role(PJSIP_ROLE_UAC),
accId(PJSUA_INVALID_ID),
state(PJSIP_INV_STATE_NULL),
lastStatusCode(PJSIP_SC_NULL),
remOfferer(false),
remAudioCount(0),
remVideoCount(0)
{}
/**
* Convert from pjsip
*/
void fromPj(const pjsua_call_info &pci);
};
/**
* Media stream info.
*/
struct StreamInfo
{
/**
* Media type of this stream.
*/
pjmedia_type type;
/**
* Transport protocol (RTP/AVP, etc.)
*/
pjmedia_tp_proto proto;
/**
* Media direction.
*/
pjmedia_dir dir;
/**
* Remote RTP address
*/
SocketAddress remoteRtpAddress;
/**
* Optional remote RTCP address
*/
SocketAddress remoteRtcpAddress;
/**
* Outgoing codec payload type.
*/
unsigned txPt;
/**
* Incoming codec payload type.
*/
unsigned rxPt;
/**
* Outgoing pt for audio telephone-events.
*/
int audTxEventPt;
/**
* Incoming pt for audio telephone-events.
*/
int audRxEventPt;
/**
* Codec name.
*/
string codecName;
/**
* Codec clock rate.
*/
unsigned codecClockRate;
/**
* Optional audio codec param.
*/
CodecParam audCodecParam;
/**
* Optional video codec param.
*/
VidCodecParam vidCodecParam;
/**
* Jitter buffer init delay in msec.
*/
int jbInit;
/**
* Jitter buffer minimum prefetch delay in msec.
*/
int jbMinPre;
/**
* Jitter buffer maximum prefetch delay in msec.
*/
int jbMaxPre;
/**
* Jitter buffer max delay in msec.
*/
int jbMax;
/**
* Jitter buffer discard algorithm.
*/
pjmedia_jb_discard_algo jbDiscardAlgo;
#if defined(PJMEDIA_STREAM_ENABLE_KA) && PJMEDIA_STREAM_ENABLE_KA!=0
/**
* Stream keep-alive and NAT hole punch (see #PJMEDIA_STREAM_ENABLE_KA) is
* enabled?
*/
bool useKa;
#endif
/**
* Disable automatic sending of RTCP SDES and BYE.
*/
bool rtcpSdesByeDisabled;
public:
/**
* Default constructor
*/
StreamInfo()
: type(PJMEDIA_TYPE_NONE),
proto(PJMEDIA_TP_PROTO_NONE),
dir(PJMEDIA_DIR_NONE),
txPt(0),
rxPt(0),
audTxEventPt(0),
audRxEventPt(0),
codecClockRate(0),
jbInit(-1),
jbMinPre(-1),
jbMaxPre(-1),
jbMax(-1),
jbDiscardAlgo(PJMEDIA_JB_DISCARD_NONE),
#if defined(PJMEDIA_STREAM_ENABLE_KA) && PJMEDIA_STREAM_ENABLE_KA!=0
useKa(false),
#endif
rtcpSdesByeDisabled(false)
{}
/**
* Convert from pjsip
*/
void fromPj(const pjsua_stream_info &info);
};
/**
* Media stream statistic.
*/
struct StreamStat
{
/**
* RTCP statistic.
*/
RtcpStat rtcp;
/**
* Jitter buffer statistic.
*/
JbufState jbuf;
public:
/**
* Convert from pjsip
*/
void fromPj(const pjsua_stream_stat &prm);
};
/**
* This structure contains parameters for Call::onCallState() callback.
*/
struct OnCallStateParam
{
/**
* Event which causes the call state to change.
*/
SipEvent e;
};
/**
* This structure contains parameters for Call::onCallTsxState() callback.
*/
struct OnCallTsxStateParam
{
/**
* Transaction event that caused the state change.
*/
SipEvent e;
};
/**
* This structure contains parameters for Call::onCallMediaState() callback.
*/
struct OnCallMediaStateParam
{
};
/**
* This structure contains parameters for Call::onCallSdpCreated() callback.
*/
struct OnCallSdpCreatedParam
{
/**
* The SDP has just been created.
*/
SdpSession sdp;
/**
* The remote SDP, will be empty if local is SDP offerer.
*/
SdpSession remSdp;
};
/**
* This structure contains parameters for Call::onStreamPreCreate()
* callback.
*/
struct OnStreamPreCreateParam
{
/**
* Stream index in the media session, read-only.
*/
unsigned streamIdx;
/**
* Parameters that the stream will be created from.
*/
StreamInfo streamInfo;
};
/**
* This structure contains parameters for Call::onStreamCreated()
* callback.
*/
struct OnStreamCreatedParam
{
/**
* Audio media stream, read-only.
*/
MediaStream stream;
/**
* Stream index in the audio media session, read-only.
*/
unsigned streamIdx;
/**
* Specify if PJSUA2 should take ownership of the port returned in
* the pPort parameter below. If set to true,
* pjmedia_port_destroy() will be called on the port when it is
* no longer needed.
*
* Default: false
*/
bool destroyPort;
/**
* On input, it specifies the audio media port of the stream. Application
* may modify this pointer to point to different media port to be
* registered to the conference bridge.
*/
MediaPort pPort;
};
/**
* This structure contains parameters for Call::onStreamDestroyed()
* callback.
*/
struct OnStreamDestroyedParam
{
/**
* Audio media stream.
*/
MediaStream stream;
/**
* Stream index in the audio media session.
*/
unsigned streamIdx;
};
/**
* This structure contains parameters for Call::onDtmfDigit()
* callback.
*/
struct OnDtmfDigitParam
{
/**
* DTMF sending method.
*/
pjsua_dtmf_method method;
/**
* DTMF ASCII digit.
*/
string digit;
/**
* DTMF signal duration. If the duration is unknown, this value is set to
* PJSUA_UNKNOWN_DTMF_DURATION.
*/
unsigned duration;
};
/**
* This structure contains parameters for Call::onDtmfEvent()
* callback.
*/
struct OnDtmfEventParam
{
/**
* DTMF sending method.
*/
pjsua_dtmf_method method;
/**
* The timestamp identifying the begin of the event. Timestamp units are
* expressed in milliseconds.
* Note that this value should only be used to compare multiple events
* received via the same method relatively to each other, as the time-base
* is randomized.
*/
unsigned timestamp;
/**
* DTMF ASCII digit.
*/
string digit;
/**
* DTMF signal duration in milliseconds. Interpretation of the duration
* depends on the flag PJMEDIA_STREAM_DTMF_IS_END.
* depends on the method.
* If the method is PJSUA_DTMF_METHOD_SIP_INFO, this contains the total
* duration of the DTMF signal or PJSUA_UNKNOWN_DTMF_DURATION if no signal
* duration was indicated.
* If the method is PJSUA_DTMF_METHOD_RFC2833, this contains the total
* duration of the DTMF signal received up to this point in time.
*/
unsigned duration;
/**
* Flags indicating additional information about the DTMF event.
* If PJMEDIA_STREAM_DTMF_IS_UPDATE is set, the event was already
* indicated earlier. The new indication contains an updated event
* duration.
* If PJMEDIA_STREAM_DTMF_IS_END is set, the event has ended and this
* indication contains the final event duration. Note that end
* indications might get lost. Hence it is not guaranteed to receive
* an event with PJMEDIA_STREAM_DTMF_IS_END for every event.
*/
unsigned flags;
};
/**
* This structure contains parameters for Call::onCallTransferRequest()
* callback.
*/
struct OnCallTransferRequestParam
{
/**
* The destination where the call will be transferred to.
*/
string dstUri;
/**
* Status code to be returned for the call transfer request. On input,
* it contains status code 202.
*/
pjsip_status_code statusCode;
/**
* The current call setting, application can update this setting
* for the call being transferred.
*/
CallSetting opt;
/**
* New Call derived object instantiated by application when the call
* transfer is about to be accepted.
*/
Call *newCall;
};
/**
* This structure contains parameters for Call::onCallTransferStatus()
* callback.
*/
struct OnCallTransferStatusParam
{
/**
* Status progress of the transfer request.
*/
pjsip_status_code statusCode;
/**
* Status progress reason.
*/
string reason;
/**
* If true, no further notification will be reported. The statusCode
* specified in this callback is the final status.
*/
bool finalNotify;
/**
* Initially will be set to true, application can set this to false
* if it no longer wants to receive further notification (for example,
* after it hangs up the call).
*/
bool cont;
};
/**
* This structure contains parameters for Call::onCallReplaceRequest()
* callback.
*/
struct OnCallReplaceRequestParam
{
/**
* The incoming INVITE request to replace the call.
*/
SipRxData rdata;
/**
* Status code to be set by application. Application should only
* return a final status (>= PJSIP_SC_OK (200))
*/
pjsip_status_code statusCode;
/**
* Optional status text to be set by application.
*/
string reason;
/**
* The current call setting, application can update this setting for
* the call being replaced.
*/
CallSetting opt;
/**
* New Call derived object instantiated by application.
*/
Call *newCall;
};
/**
* This structure contains parameters for Call::onCallReplaced() callback.
*/
struct OnCallReplacedParam
{
/**
* The new call id.
*/
pjsua_call_id newCallId;
/**
* New Call derived object instantiated by application.
*/
Call *newCall;
};
/**
* This structure contains parameters for Call::onCallRxOffer() callback.
*/
struct OnCallRxOfferParam
{
/**
* The new offer received.
*/
SdpSession offer;
/**
* Status code to be returned for answering the offer. On input,
* it contains status code PJSIP_SC_OK (200). Currently, valid values are only
* PJSIP_SC_OK (200) and PJSIP_SC_NOT_ACCEPTABLE_HERE (488).
*/
pjsip_status_code statusCode;
/**
* The current call setting, application can update this setting for
* answering the offer.
*/
CallSetting opt;
};
/**
* This structure contains parameters for Call::onCallRxReinvite() callback.
*/
struct OnCallRxReinviteParam
{
/**
* The new offer received.
*/
SdpSession offer;
/**
* The incoming re-INVITE.
*/
SipRxData rdata;
/**
* On input, it is false. Set to true if app wants to manually answer
* the re-INVITE.
*/
bool isAsync;
/**
* Status code to be returned for answering the offer. On input,
* it contains status code PJSIP_SC_OK (200). Currently, valid values are only
* PJSIP_SC_OK (200) and PJSIP_SC_NOT_ACCEPTABLE_HERE (488).
*/
pjsip_status_code statusCode;
/**
* The current call setting, application can update this setting for
* answering the offer.
*/
CallSetting opt;
};
/**
* This structure contains parameters for Call::onCallTxOffer() callback.
*/
struct OnCallTxOfferParam
{
/**
* The current call setting, application can update this setting for
* generating the offer. Note that application should maintain any
* active media to avoid the need for the peer to reject the offer.
*/
CallSetting opt;
};
/**
* This structure contains parameters for Call::onCallRedirected() callback.
*/
struct OnCallRedirectedParam
{
/**
* The current target to be tried.
*/
string targetUri;
/**
* The event that caused this callback to be called.
* This could be the receipt of 3xx response, or 4xx/5xx response
* received for the INVITE sent to subsequent targets, or empty
* (e.type == PJSIP_EVENT_UNKNOWN) if this callback is called from
* within Call::processRedirect() context.
*/
SipEvent e;
};
/**
* This structure contains parameters for Call::onCallMediaEvent() callback.
*/
struct OnCallMediaEventParam
{
/**
* The media stream index.
*/
unsigned medIdx;
/**
* The media event.
*/
MediaEvent ev;
};
/**
* This structure contains parameters for Call::onCallMediaTransportState()
* callback.
*/
struct OnCallMediaTransportStateParam
{
/**
* The media index.
*/
unsigned medIdx;
/**
* The media transport state
*/
pjsua_med_tp_st state;
/**
* The last error code related to the media transport state.
*/
pj_status_t status;
/**
* Optional SIP error code.
*/
int sipErrorCode;
};
/**
* This structure contains parameters for Call::onCreateMediaTransport()
* callback.
*/
struct OnCreateMediaTransportParam
{
/**
* The media index in the SDP for which this media transport will be used.
*/
unsigned mediaIdx;
/**
* The media transport which otherwise will be used by the call has this
* callback not been implemented. Application can change this to its own
* instance of media transport to be used by the call.
*/
MediaTransport mediaTp;
/**
* Bitmask from pjsua_create_media_transport_flag.
*/
unsigned flags;
};
/**
* This structure contains parameters for Call::onCreateMediaTransportSrtp()
* callback.
*/
struct OnCreateMediaTransportSrtpParam
{
/**
* The media index in the SDP for which the SRTP media transport
* will be used.
*/
unsigned mediaIdx;
/**
* Specify whether secure media transport should be used. Application
* can modify this only for initial INVITE.
* Valid values are PJMEDIA_SRTP_DISABLED, PJMEDIA_SRTP_OPTIONAL, and
* PJMEDIA_SRTP_MANDATORY.
*/
pjmedia_srtp_use srtpUse;
/**
* Application can modify this to specify the cryptos and keys
* which are going to be used.
*/
SrtpCryptoVector cryptos;
};
/**
* @} // PJSUA2_Call_Data_Structure
*/
/**
* @addtogroup PJSUA2_CALL
* @{
*/
/**
* This structure contains parameters for Call::answer(), Call::hangup(),
* Call::reinvite(), Call::update(), Call::xfer(), Call::xferReplaces(),
* Call::setHold().
*/
struct CallOpParam
{
/**
* The call setting.
*/
CallSetting opt;
/**
* Status code.
*/
pjsip_status_code statusCode;
/**
* Reason phrase.
*/
string reason;
/**
* Options.
*/
unsigned options;
/**
* List of headers etc to be added to outgoing response message.
* Note that this message data will be persistent in all next
* answers/responses for this INVITE request.
*/
SipTxOption txOption;
/**
* SDP answer. Currently only used for Call::answer().
*/
SdpSession sdp;
public:
/**
* Default constructor initializes with zero/empty values.
* Setting useDefaultCallSetting to true will initialize opt with default
* call setting values.
*/
CallOpParam(bool useDefaultCallSetting = false);
};
/**
* This structure contains parameters for Call::sendRequest()
*/
struct CallSendRequestParam
{
/**
* SIP method of the request.
*/
string method;
/**
* Message body and/or list of headers etc to be included in
* outgoing request.
*/
SipTxOption txOption;
public:
/**
* Default constructor initializes with zero/empty values.
*/
CallSendRequestParam();
};
/**
* This structure contains parameters for Call::vidSetStream()
*/
struct CallVidSetStreamParam
{
/**
* Specify the media stream index. This can be set to -1 to denote
* the default video stream in the call, which is the first active
* video stream or any first video stream if none is active.
*
* This field is valid for all video stream operations, except
* PJSUA_CALL_VID_STRM_ADD.
*
* Default: -1 (first active video stream, or any first video stream
* if none is active)
*/
int medIdx;
/**
* Specify the media stream direction.
*
* This field is valid for the following video stream operations:
* PJSUA_CALL_VID_STRM_ADD and PJSUA_CALL_VID_STRM_CHANGE_DIR.
*
* Default: PJMEDIA_DIR_ENCODING_DECODING
*/
pjmedia_dir dir;
/**
* Specify the video capture device ID. This can be set to
* PJMEDIA_VID_DEFAULT_CAPTURE_DEV to specify the default capture
* device as configured in the account.
*
* This field is valid for the following video stream operations:
* PJSUA_CALL_VID_STRM_ADD and PJSUA_CALL_VID_STRM_CHANGE_CAP_DEV.
*
* Default: PJMEDIA_VID_DEFAULT_CAPTURE_DEV.
*/
pjmedia_vid_dev_index capDev;
public:
/**
* Default constructor
*/
CallVidSetStreamParam();
};
/**
* This structure contains parameters for Call::sendDtmf()
*/
struct CallSendDtmfParam
{
/**
* The method used to send DTMF.
*
* Default: PJSUA_DTMF_METHOD_RFC2833
*/
pjsua_dtmf_method method;
/**
* The signal duration used for the DTMF.
*
* Default: PJSUA_CALL_SEND_DTMF_DURATION_DEFAULT
*/
unsigned duration;
/**
* The DTMF digits to be sent.
*/
string digits;
public:
/**
* Default constructor initialize with default value.
*/
CallSendDtmfParam();
/**
* Convert to pjsip.
*/
pjsua_call_send_dtmf_param toPj() const;
/**
* Convert from pjsip.
*/
void fromPj(const pjsua_call_send_dtmf_param ¶m);
};
/**
* Call.
*/
class Call
{
public:
/**
* Constructor.
*/
Call(Account& acc, int call_id = PJSUA_INVALID_ID);
/**
* Destructor.
*/
virtual ~Call();
/**
* Obtain detail information about this call.
*
* @return Call info.
*/
CallInfo getInfo() const PJSUA2_THROW(Error);
/**
* Check if this call has active INVITE session and the INVITE
* session has not been disconnected.
*
* @return True if call is active.
*/
bool isActive() const;
/**
* Get PJSUA-LIB call ID or index associated with this call.
*
* @return Integer greater than or equal to zero.
*/
int getId() const;
/**
* Get the Call class for the specified call Id.
*
* @param call_id The call ID to lookup
*
* @return The Call instance or NULL if not found.
*/
static Call *lookup(int call_id);
/**
* Check if call has an active media session.
*
* @return True if yes.
*/
bool hasMedia() const;
/**
* Warning: deprecated, use getAudioMedia() instead. This function is not
* safe in multithreaded environment.
*
* Get media for the specified media index.
*
* @param med_idx Media index.
*
* @return The media or NULL if invalid or inactive.
*/
Media *getMedia(unsigned med_idx) const;
/**
* Get audio media for the specified media index. If the specified media
* index is not audio or invalid or inactive, exception will be thrown.
*
* @param med_idx Media index, or -1 to specify any first audio
* media registered in the conference bridge.
*
* @return The audio media.
*/
AudioMedia getAudioMedia(int med_idx) const PJSUA2_THROW(Error);
/**
* Get video media in encoding direction for the specified media index.
* If the specified media index is not video or invalid or the direction
* is receive only, exception will be thrown.
*
* @param med_idx Media index, or -1 to specify any first video
* media with encoding direction registered in the
* conference bridge.
*
* @return The video media.
*/
VideoMedia getEncodingVideoMedia(int med_idx) const PJSUA2_THROW(Error);
/**
* Get video media in decoding direction for the specified media index.
* If the specified media index is not video or invalid or the direction
* is send only, exception will be thrown.
*
* @param med_idx Media index, or -1 to specify any first video
* media with decoding direction registered in the
* conference bridge.
*
* @return The video media.
*/
VideoMedia getDecodingVideoMedia(int med_idx) const PJSUA2_THROW(Error);
/**
* Check if remote peer support the specified capability.
*
* @param htype The header type (pjsip_hdr_e) to be checked, which
* value may be:
* - PJSIP_H_ACCEPT
* - PJSIP_H_ALLOW
* - PJSIP_H_SUPPORTED
* @param hname If htype specifies PJSIP_H_OTHER, then the header
* name must be supplied in this argument. Otherwise
* the value must be set to empty string ("").
* @param token The capability token to check. For example, if \a
* htype is PJSIP_H_ALLOW, then \a token specifies the
* method names; if \a htype is PJSIP_H_SUPPORTED, then
* \a token specifies the extension names such as
* "100rel".
*
* @return PJSIP_DIALOG_CAP_SUPPORTED if the specified
* capability is explicitly supported, see
* pjsip_dialog_cap_status for more info.
*/
pjsip_dialog_cap_status remoteHasCap(int htype,
const string &hname,
const string &token) const;
/**
* Attach application specific data to the call. Application can then
* inspect this data by calling getUserData().
*
* @param user_data Arbitrary data to be attached to the call.
*/
void setUserData(Token user_data);
/**
* Get user data attached to the call, which has been previously set with
* setUserData().
*
* @return The user data.
*/
Token getUserData() const;
/**
* Get the NAT type of remote's endpoint. This is a proprietary feature
* of PJSUA-LIB which sends its NAT type in the SDP when \a natTypeInSdp
* is set in UaConfig.
*
* This function can only be called after SDP has been received from remote,
* which means for incoming call, this function can be called as soon as
* call is received as long as incoming call contains SDP, and for outgoing
* call, this function can be called only after SDP is received (normally in
* PJSIP_SC_OK (200) response to INVITE). As a general case, application
* should call this function after or in \a onCallMediaState() callback.
*
* @return The NAT type.
*
* @see Endpoint::natGetType(), natTypeInSdp
*/
pj_stun_nat_type getRemNatType() PJSUA2_THROW(Error);
/**
* Make outgoing call to the specified URI.
*
* @param dst_uri URI to be put in the To header (normally is the same
* as the target URI).
* @param prm.opt Optional call setting.
* @param prm.txOption Optional headers etc to be added to outgoing INVITE
* request.
*/
void makeCall(const string &dst_uri, const CallOpParam &prm)
PJSUA2_THROW(Error);
/**
* Send response to incoming INVITE request with call setting param.
* Depending on the status code specified as parameter, this function may
* send provisional response, establish the call, or terminate the call.
* Notes about call setting:
* - if call setting is changed in the subsequent call to this function,
* only the first call setting supplied will applied. So normally
* application will not supply call setting before getting confirmation
* from the user.
* - if no call setting is supplied when SDP has to be sent, i.e: answer
* with status code 183 or 2xx, the default call setting will be used,
* check CallSetting for its default values.
*
* @param prm.opt Optional call setting.
* @param prm.statusCode Status code, (>= PJSIP_SC_TRYING (100)).
* @param prm.reason Optional reason phrase. If empty, default text
* will be used.
* @param prm.txOption Optional list of headers etc to be added to outgoing
* response message. Note that this message data will
* be persistent in all next answers/responses for this
* INVITE request.
*/
void answer(const CallOpParam &prm) PJSUA2_THROW(Error);
/**
* Hangup call by using method that is appropriate according to the
* call state. This function is different than answering the call with
* 3xx-6xx response (with answer()), in that this function
* will hangup the call regardless of the state and role of the call,
* while answer() only works with incoming calls on EARLY
* state.
*
* @param prm.statusCode
* Optional status code to be sent when we're rejecting
* incoming call. If the value is zero, "603/Decline"
* will be sent.
* @param prm.reason Optional reason phrase to be sent when we're
* rejecting incoming call. If empty, default text
* will be used.
* @param prm.txOption Optional list of headers etc to be added to outgoing
* request/response message.
*/
void hangup(const CallOpParam &prm) PJSUA2_THROW(Error);
/**
* Put the specified call on hold. This will send re-INVITE with the
* appropriate SDP to inform remote that the call is being put on hold.
* The final status of the request itself will be reported on the
* \a onCallMediaState() callback, which inform the application that
* the media state of the call has changed.
*
* @param prm.options Bitmask of pjsua_call_flag constants. Currently,
* only the flag PJSUA_CALL_UPDATE_CONTACT can be used.
* @param prm.txOption Optional message components to be sent with
* the request.
*/
void setHold(const CallOpParam &prm) PJSUA2_THROW(Error);
/**
* Send re-INVITE.
* The final status of the request itself will be reported on the
* \a onCallMediaState() callback, which inform the application that
* the media state of the call has changed.
*
* @param prm.opt Optional call setting, if empty, the current call
* setting will remain unchanged.
* @param prm.opt.flag Bitmask of pjsua_call_flag constants. Specifying
* PJSUA_CALL_UNHOLD here will release call hold.
* @param prm.txOption Optional message components to be sent with
* the request.
*/
void reinvite(const CallOpParam &prm) PJSUA2_THROW(Error);
/**
* Send UPDATE request.
*
* @param prm.opt Optional call setting, if empty, the current call
* setting will remain unchanged.
* @param prm.txOption Optional message components to be sent with
* the request.
*/
void update(const CallOpParam &prm) PJSUA2_THROW(Error);
/**
* Initiate call transfer to the specified address. This function will send
* REFER request to instruct remote call party to initiate a new INVITE
* session to the specified destination/target.
*
* If application is interested to monitor the successfulness and
* the progress of the transfer request, it can implement
* \a onCallTransferStatus() callback which will report the progress
* of the call transfer request.
*
* @param dest URI of new target to be contacted. The URI may be
* in name address or addr-spec format.
* @param prm.txOption Optional message components to be sent with
* the request.
*/
void xfer(const string &dest, const CallOpParam &prm) PJSUA2_THROW(Error);
/**
* Initiate attended call transfer. This function will send REFER request
* to instruct remote call party to initiate new INVITE session to the URL
* of \a destCall. The party at \a dest_call then should "replace"
* the call with us with the new call from the REFER recipient.
*
* @param dest_call The call to be replaced.
* @param prm.options Application may specify
* PJSUA_XFER_NO_REQUIRE_REPLACES to suppress the
* inclusion of "Require: replaces" in
* the outgoing INVITE request created by the REFER
* request.
* @param prm.txOption Optional message components to be sent with
* the request.
*/
void xferReplaces(const Call& dest_call,
const CallOpParam &prm) PJSUA2_THROW(Error);
/**
* Accept or reject redirection response. Application MUST call this
* function after it signaled PJSIP_REDIRECT_PENDING in the
* \a onCallRedirected() callback,
* to notify the call whether to accept or reject the redirection
* to the current target. Application can use the combination of
* PJSIP_REDIRECT_PENDING command in \a onCallRedirected() callback and
* this function to ask for user permission before redirecting the call.
*
* Note that if the application chooses to reject or stop redirection (by
* using PJSIP_REDIRECT_REJECT or PJSIP_REDIRECT_STOP respectively), the
* call disconnection callback will be called before this function returns.
* And if the application rejects the target, the \a onCallRedirected()
* callback may also be called before this function returns if there is
* another target to try.
*
* @param cmd Redirection operation to be applied to the current
* target. The semantic of this argument is similar
* to the description in the \a onCallRedirected()
* callback, except that the PJSIP_REDIRECT_PENDING is
* not accepted here.
*/
void processRedirect(pjsip_redirect_op cmd) PJSUA2_THROW(Error);
/**
* Send DTMF digits to remote using RFC 2833 payload formats.
*
* @param digits DTMF string digits to be sent.
*/
void dialDtmf(const string &digits) PJSUA2_THROW(Error);
/**
* Send DTMF digits to remote.
*
* @param param The send DTMF parameter.
*/
void sendDtmf(const CallSendDtmfParam ¶m) PJSUA2_THROW(Error);
/**
* Send instant messaging inside INVITE session.
*
* @param prm.contentType
* MIME type.
* @param prm.content The message content.
* @param prm.txOption Optional list of headers etc to be included in
* outgoing request. The body descriptor in the
* txOption is ignored.
* @param prm.userData Optional user data, which will be given back when
* the IM callback is called.
*/
void sendInstantMessage(const SendInstantMessageParam& prm)
PJSUA2_THROW(Error);
/**
* Send IM typing indication inside INVITE session.
*
* @param prm.isTyping True to indicate to remote that local person is
* currently typing an IM.
* @param prm.txOption Optional list of headers etc to be included in
* outgoing request.
*/
void sendTypingIndication(const SendTypingIndicationParam &prm)
PJSUA2_THROW(Error);
/**
* Send arbitrary request with the call. This is useful for example to send
* INFO request. Note that application should not use this function to send
* requests which would change the invite session's state, such as
* re-INVITE, UPDATE, PRACK, and BYE.
*
* @param prm.method SIP method of the request.
* @param prm.txOption Optional message body and/or list of headers to be
* included in outgoing request.
*/
void sendRequest(const CallSendRequestParam &prm) PJSUA2_THROW(Error);
/**
* Dump call and media statistics to string.
*
* @param with_media True to include media information too.
* @param indent Spaces for left indentation.
*
* @return Call dump and media statistics string.
*/
string dump(bool with_media, const string indent) PJSUA2_THROW(Error);
/**
* Get the media stream index of the default video stream in the call.
* Typically this will just retrieve the stream index of the first
* activated video stream in the call. If none is active, it will return
* the first inactive video stream.
*
* @return The media stream index or -1 if no video stream
* is present in the call.
*/
int vidGetStreamIdx() const;
/**
* Determine if video stream for the specified call is currently running
* (i.e. has been created, started, and not being paused) for the specified
* direction.
*
* @param med_idx Media stream index, or -1 to specify default video
* media.
* @param dir The direction to be checked.
*
* @return True if stream is currently running for the
* specified direction.
*/
bool vidStreamIsRunning(int med_idx, pjmedia_dir dir) const;
/**
* Add, remove, modify, and/or manipulate video media stream for the
* specified call. This may trigger a re-INVITE or UPDATE to be sent
* for the call.
*
* @param op The video stream operation to be performed,
* possible values are pjsua_call_vid_strm_op.
* @param param The parameters for the video stream operation
* (see CallVidSetStreamParam).
*/
void vidSetStream(pjsua_call_vid_strm_op op,
const CallVidSetStreamParam ¶m) PJSUA2_THROW(Error);
/**
* Modify the video stream's codec parameter after the codec is opened.
* Note that not all codec backends support modifying parameters during
* runtime and only certain parameters can be changed.
*
* Currently, only Video Toolbox and OpenH264 backends support runtime
* adjustment of encoding bitrate (avg_bps and max_bps).
*
* @param med_idx Video stream index.
* @param param The new codec parameter.
*
* @return PJ_SUCCESS on success.
*/
void vidStreamModifyCodecParam(int med_idx, const VidCodecParam ¶m)
PJSUA2_THROW(Error);
/**
* Modify the audio stream's codec parameter after the codec is opened.
* Note that not all codec parameters can be modified during run-time.
* Currently, only Opus codec supports changing key codec parameters
* such as bitrate and bandwidth, while other codecs may only be able to
* modify minor settings such as VAD or PLC.
*
* @param med_idx Media stream index, or -1 to specify default audio
* media.
* @param param The new codec parameter.
*
* @return PJ_SUCCESS on success.
*/
void audStreamModifyCodecParam(int med_idx, const CodecParam ¶m)
PJSUA2_THROW(Error);
/**
* Get media stream info for the specified media index.
*
* @param med_idx Media stream index.
*
* @return The stream info.
*/
StreamInfo getStreamInfo(unsigned med_idx) const PJSUA2_THROW(Error);
/**
* Get media stream statistic for the specified media index.
*
* @param med_idx Media stream index.
*
* @return The stream statistic.
*/
StreamStat getStreamStat(unsigned med_idx) const PJSUA2_THROW(Error);
/**
* Get media transport info for the specified media index.
*
* @param med_idx Media stream index.
*
* @return The transport info.
*/
MediaTransportInfo getMedTransportInfo(unsigned med_idx) const
PJSUA2_THROW(Error);
/**
* Internal function (callled by Endpoint( to process update to call
* medias when call media state changes.
*/
void processMediaUpdate(OnCallMediaStateParam &prm);
/**
* Internal function (called by Endpoint) to process call state change.
*/
void processStateChange(OnCallStateParam &prm);
public:
/*
* Callbacks
*/
/**
* Notify application when call state has changed.
* Application may then query the call info to get the
* detail call states by calling getInfo() function.
*
* @param prm Callback parameter.
*/
virtual void onCallState(OnCallStateParam &prm)
{ PJ_UNUSED_ARG(prm); }
/**
* This is a general notification callback which is called whenever
* a transaction within the call has changed state. Application can
* implement this callback for example to monitor the state of
* outgoing requests, or to answer unhandled incoming requests
* (such as INFO) with a final response.
*
* @param prm Callback parameter.
*/
virtual void onCallTsxState(OnCallTsxStateParam &prm)
{ PJ_UNUSED_ARG(prm); }
/**
* Notify application when media state in the call has changed.
* Normal application would need to implement this callback, e.g.
* to connect the call's media to sound device. When ICE is used,
* this callback will also be called to report ICE negotiation
* failure.
*
* @param prm Callback parameter.
*/
virtual void onCallMediaState(OnCallMediaStateParam &prm)
{ PJ_UNUSED_ARG(prm); }
/**
* Notify application when a call has just created a local SDP (for
* initial or subsequent SDP offer/answer). Application can implement
* this callback to modify the SDP, before it is being sent and/or
* negotiated with remote SDP, for example to apply per account/call
* basis codecs priority or to add custom/proprietary SDP attributes.
*
* @param prm Callback parameter.
*/
virtual void onCallSdpCreated(OnCallSdpCreatedParam &prm)
{ PJ_UNUSED_ARG(prm); }
/**
* Notify application when an audio media session is about to be created
* (as opposed to onStreamCreated(), which is called *after* the session
* has been created). The application may change
* some stream info parameter values, i.e: jbInit, jbMinPre, jbMaxPre,
* jbMax, useKa, rtcpSdesByeDisabled, jbDiscardAlgo (audio),
* vidCodecParam.encFmt (video).
*
* @param prm Callback parameter.
*/
virtual void onStreamPreCreate(OnStreamPreCreateParam &prm)
{ PJ_UNUSED_ARG(prm); }
/**
* Notify application when audio media session is created and before it is
* registered to the conference bridge. Application may return different
* audio media port if it has added media processing port to the stream.
* This media port then will be added to the conference bridge instead.
*
* @param prm Callback parameter.
*/
virtual void onStreamCreated(OnStreamCreatedParam &prm)
{ PJ_UNUSED_ARG(prm); }
/**
* Notify application when audio media session has been unregistered from
* the conference bridge and about to be destroyed.
*
* @param prm Callback parameter.
*/
virtual void onStreamDestroyed(OnStreamDestroyedParam &prm)
{ PJ_UNUSED_ARG(prm); }
/**
* Notify application upon incoming DTMF digits.
*
* @param prm Callback parameter.
*/
virtual void onDtmfDigit(OnDtmfDigitParam &prm)
{ PJ_UNUSED_ARG(prm); }
/**
* Notify application upon incoming DTMF events.
*
* @param prm Callback parameter.
*/
virtual void onDtmfEvent(OnDtmfEventParam &prm)
{ PJ_UNUSED_ARG(prm); }
/**
* Notify application on call being transferred (i.e. REFER is received).
* Application can decide to accept/reject transfer request by setting
* the code (default is 202). When this callback is not implemented,
* the default behavior is to accept the transfer.
*
* If application decides to accept the transfer request, it must also
* instantiate the new Call object for the transfer operation and return
* this new Call object to prm.newCall. For the new Call instance,
* the account should use the same account as this call and the call ID
* must be set to PJSUA_INVALID_ID.
*
* If application does not specify new Call object, library will reuse the
* existing Call object for initiating the new call (to the transfer
* destination). In this case, any events from both calls (transferred and
* transferring) will be delivered to the same Call object, where the call
* ID will be switched back and forth between callbacks. Application must
* be careful to not destroy the Call object when receiving disconnection
* event of the transferred call after the transfer process is completed.
*
* @param prm Callback parameter.
*/
virtual void onCallTransferRequest(OnCallTransferRequestParam &prm)
{ PJ_UNUSED_ARG(prm); }
/**
* Notify application of the status of previously sent call
* transfer request. Application can monitor the status of the
* call transfer request, for example to decide whether to
* terminate existing call.
*
* @param prm Callback parameter.
*/
virtual void onCallTransferStatus(OnCallTransferStatusParam &prm)
{ PJ_UNUSED_ARG(prm); }
/**
* Notify application about incoming INVITE with Replaces header.
* Application may reject the request by setting non-2xx code.
*
* In this callback, application should create a new Call instance and
* return the Call object via prm.newCall. In creating the new Call
* instance, the account should use the same account as this call and
* the call ID must be set to PJSUA_INVALID_ID.
*
* If application does not specify new Call object, library will reuse the
* existing Call object for callbacks. In this case, any events from
* both calls (replaced and new) will be delivered to the same Call object,
* where the call ID will be switched back and forth between callbacks.
* Application must be careful to not destroy the Call object when
* receiving disconnection event of the replaced call after the transfer
* process is completed.
*
* @param prm Callback parameter.
*/
virtual void onCallReplaceRequest(OnCallReplaceRequestParam &prm)
{ PJ_UNUSED_ARG(prm); }
/**
* Notify application that an existing call has been replaced with
* a new call. This happens when PJSUA-API receives incoming INVITE
* request with Replaces header.
*
* After this callback is called, normally PJSUA-API will disconnect
* this call and establish a new call.
*
* If not yet done in onCallReplaceRequest(), application can create
* the new Call instance and return the Call object via prm.newCall.
* In creating the new Call instance, the account should use the same
* account as this call and the call ID must be set to prm.newCallId.
*
* If the new Call instance has been setup in onCallReplaceRequest(),
* the prm.newCall should contain the new Call instance and application
* MUST not change it.
*
* If application does not specify new Call object, library will reuse the
* existing Call object for callbacks. In this case, any events from
* both calls (replaced and new) will be delivered to the same Call object,
* where the call ID will be switched back and forth between callbacks.
* Application must be careful to not destroy the Call object when
* receiving disconnection event of the replaced call after the transfer
* process is completed.
*
* @param prm Callback parameter.
*/
virtual void onCallReplaced(OnCallReplacedParam &prm)
{ PJ_UNUSED_ARG(prm); }
/**
* Notify application when call has received new offer from remote
* (i.e. re-INVITE/UPDATE with SDP is received). Application can
* decide to accept/reject the offer by setting the code (default
* is PJSIP_SC_OK (200)). If the offer is accepted, application can update
* the call setting to be applied in the answer. When this callback is
* not implemented, the default behavior is to accept the offer using
* current call setting.
*
* @param prm Callback parameter.
*/
virtual void onCallRxOffer(OnCallRxOfferParam &prm)
{ PJ_UNUSED_ARG(prm); }
/**
* Notify application when call has received a re-INVITE offer from
* the peer. It allows more fine-grained control over the response to
* a re-INVITE. If application sets prm.isAsync to true, it can send
* the reply manually using the function #pj::Call::answer() and setting
* the SDP answer. Otherwise, by default the re-INVITE will be
* answered automatically after the callback returns.
*
* Currently, this callback is only called for re-INVITE with
* SDP, but app should be prepared to handle the case of re-INVITE
* without SDP.
*
* Remarks: If manually answering at a later timing, application may
* need to monitor onCallTsxState() callback to check whether
* the re-INVITE is already answered automatically with
* PJSIP_SC_REQUEST_TERMINATED (487) due to being cancelled.
*
* Note: onCallRxOffer() will still be called after this callback,
* but only if prm.isAsync is false and prm.statusCode is PJSIP_SC_OK
* (200).
*
* @param prm Callback parameter.
*/
virtual void onCallRxReinvite(OnCallRxReinviteParam &prm)
{ PJ_UNUSED_ARG(prm); }
/**
* Notify application when call has received INVITE with no SDP offer.
* Application can update the call setting (e.g: add audio/video), or
* enable/disable codecs, or update other media session settings from
* within the callback, however, as mandated by the standard (RFC3261
* section 14.2), it must ensure that the update overlaps with the
* existing media session (in codecs, transports, or other parameters)
* that require support from the peer, this is to avoid the need for
* the peer to reject the offer.
*
* When this callback is not implemented, the default behavior is to send
* SDP offer using current active media session (with all enabled codecs
* on each media type).
*
* @param prm Callback parameter.
*/
virtual void onCallTxOffer(OnCallTxOfferParam &prm)
{ PJ_UNUSED_ARG(prm); }
/**
* Notify application on incoming MESSAGE request.
*
* @param prm Callback parameter.
*/
virtual void onInstantMessage(OnInstantMessageParam &prm)
{ PJ_UNUSED_ARG(prm); }
/**
* Notify application about the delivery status of outgoing MESSAGE
* request.
*
* @param prm Callback parameter.
*/
virtual void onInstantMessageStatus(OnInstantMessageStatusParam &prm)
{ PJ_UNUSED_ARG(prm); }
/**
* Notify application about typing indication.
*
* @param prm Callback parameter.
*/
virtual void onTypingIndication(OnTypingIndicationParam &prm)
{ PJ_UNUSED_ARG(prm); }
/**
* This callback is called when the call is about to resend the
* INVITE request to the specified target, following the previously
* received redirection response.
*
* Application may accept the redirection to the specified target,
* reject this target only and make the session continue to try the next
* target in the list if such target exists, stop the whole
* redirection process altogether and cause the session to be
* disconnected, or defer the decision to ask for user confirmation.
*
* This callback is optional,
* the default behavior is to NOT follow the redirection response.
*
* @param prm Callback parameter.
*
* @return Action to be performed for the target. Set this
* parameter to one of the value below:
* - PJSIP_REDIRECT_ACCEPT: immediately accept the
* redirection. When set, the call will immediately
* resend INVITE request to the target.
* - PJSIP_REDIRECT_ACCEPT_REPLACE: immediately accept
* the redirection and replace the To header with the
* current target. When set, the call will immediately
* resend INVITE request to the target.
* - PJSIP_REDIRECT_REJECT: immediately reject this
* target. The call will continue retrying with
* next target if present, or disconnect the call
* if there is no more target to try.
* - PJSIP_REDIRECT_STOP: stop the whole redirection
* process and immediately disconnect the call. The
* onCallState() callback will be called with
* PJSIP_INV_STATE_DISCONNECTED state immediately
* after this callback returns.
* - PJSIP_REDIRECT_PENDING: set to this value if
* no decision can be made immediately (for example
* to request confirmation from user). Application
* then MUST call processRedirect()
* to either accept or reject the redirection upon
* getting user decision.
*/
virtual pjsip_redirect_op onCallRedirected(OnCallRedirectedParam &prm)
{
PJ_UNUSED_ARG(prm);
return PJSIP_REDIRECT_STOP;
}
/**
* This callback is called when media transport state is changed.
*
* @param prm Callback parameter.
*/
virtual void onCallMediaTransportState(OnCallMediaTransportStateParam &prm)
{ PJ_UNUSED_ARG(prm); }
/**
* Notification about media events such as video notifications. This
* callback will most likely be called from media threads, thus
* application must not perform heavy processing in this callback.
* Especially, application must not destroy the call or media in this
* callback. If application needs to perform more complex tasks to
* handle the event, it should post the task to another thread.
*
* @param prm Callback parameter.
*/
virtual void onCallMediaEvent(OnCallMediaEventParam &prm)
{ PJ_UNUSED_ARG(prm); }
/**
* This callback can be used by application to implement custom media
* transport adapter for the call, or to replace the media transport
* with something completely new altogether.
*
* This callback is called when a new call is created. The library has
* created a media transport for the call, and it is provided as the
* \a mediaTp argument of this callback. The callback may change it
* with the instance of media transport to be used by the call.
*
* @param prm Callback parameter.
*/
virtual void
onCreateMediaTransport(OnCreateMediaTransportParam &prm)
{ PJ_UNUSED_ARG(prm); }
/**
* Warning: deprecated and may be removed in future release.
* Application can set SRTP crypto settings (including keys) and
* keying methods via AccountConfig.mediaConfig.srtpOpt.
* See also ticket #2100.
*
* This callback is called when SRTP media transport is created.
* Application can modify the SRTP setting \a srtpOpt to specify
* the cryptos and keys which are going to be used. Note that
* application should not modify the field
* \a pjmedia_srtp_setting.close_member_tp and can only modify
* the field \a pjmedia_srtp_setting.use for initial INVITE.
*
* @param prm Callback parameter.
*/
virtual void
onCreateMediaTransportSrtp(OnCreateMediaTransportSrtpParam &prm)
{ PJ_UNUSED_ARG(prm); }
private:
friend class Endpoint;
Account &acc;
pjsua_call_id id;
Token userData;
std::vector<Media *> medias;
pj_pool_t *sdp_pool;
Call *child; /* New outgoing call in call transfer. */
};
/**
* @} // PJSUA2_CALL
*/
} // namespace pj
#endif /* __PJSUA2_CALL_HPP__ */