Calls¶

Calls are represented by Call class.

Subclassing the Call Class¶

To use the Call class, normally application SHOULD create its own subclass, such as:

class MyCall : public Call
{
public:
    MyCall(Account &acc, int call_id = PJSUA_INVALID_ID)
    : Call(acc, call_id)
    { }

    ~MyCall()
    { }

    // Notification when call's state has changed.
    virtual void onCallState(OnCallStateParam &prm);

    // Notification when call's media state has changed.
    virtual void onCallMediaState(OnCallMediaStateParam &prm);
};

In its subclass, application can implement the call callbacks, which is basically used to process events related to the call, such as call state change or incoming call transfer request.

Making Outgoing Calls¶

Making outgoing call is simple, just invoke makeCall() method of the Call object. Assuming you have the Account object as acc variable and destination URI string in dest_uri, you can initiate outgoing call with the snippet below:

Call *call = new MyCall(*acc);
CallOpParam prm(true); // Use default call settings
try {
    call->makeCall(dest_uri, prm);
} catch(Error& err) {
    cout << err.info() << endl;
}

The snippet above creates a Call object and initiates outgoing call to dest_uri using the default call settings. Subsequent operations to the call can use the method in the call instance, and events to the call will be reported to the callback. More on the callback will be explained a bit later.

Receiving Incoming Calls¶

Incoming calls are reported as onIncomingCall() of the Account class. You must derive a class from the Account class to handle incoming calls.

Below is a sample code of the callback implementation:

void MyAccount::onIncomingCall(OnIncomingCallParam &iprm)
{
    Call *call = new MyCall(*this, iprm.callId);
    CallOpParam prm;
    prm.statusCode = PJSIP_SC_OK;
    call->answer(prm);
}

For incoming calls, the call instance is created in the callback function as shown above. Application should make sure to store the call instance during the lifetime of the call (that is until the call is disconnected).

Call Properties¶

All call properties such as state, media state, remote peer information, etc. are stored as CallInfo class, which can be retrieved from the call object with using getInfo() method of the Call.

Call Disconnection¶

Call disconnection event is a special event since once the callback that reports this event returns, the call is no longer valid and any operations invoked to the call object will raise error exception. Thus, it is recommended to delete the call object inside the callback.

The call disconnection is reported in onCallState() method of Call and it can be detected as follows:

void MyCall::onCallState(OnCallStateParam &prm)
{
    CallInfo ci = getInfo();
    if (ci.state == PJSIP_INV_STATE_DISCONNECTED) {
        /* Delete the call */
        delete this;
    }
}

Working with Call’s Audio Media¶

You can only operate with the call’s audio media (e.g. connecting the call to the sound device in the conference bridge) when the call’s audio media is ready (or active). The changes to the call’s media state is reported in onCallMediaState() callback, and if the calls audio media is ready (or active) the function Call.getMedia() will return a valid audio media.

Below is a sample code to connect the call to the sound device when the media is active:

void MyCall::onCallMediaState(OnCallMediaStateParam &prm)
{
    CallInfo ci = getInfo();
    // Iterate all the call medias
    for (unsigned i = 0; i < ci.media.size(); i++) {
        if (ci.media[i].type==PJMEDIA_TYPE_AUDIO && getMedia(i)) {
            AudioMedia *aud_med = (AudioMedia *)getMedia(i);

            // Connect the call audio media to sound device
            AudDevManager& mgr = Endpoint::instance().audDevManager();
            aud_med->startTransmit(mgr.getPlaybackDevMedia());
            mgr.getCaptureDevMedia().startTransmit(*aud_med);
        }
    }
}

When the audio media becomes inactive (for example when the call is put on hold), there is no need to stop the audio media’s transmission to/from the sound device since the call’s audio media will be removed automatically from the conference bridge when it’s no longer valid, and this will automatically remove all connections to/from the call.

Call Operations¶

You can invoke operations to the Call object, such as hanging up, putting the call on hold, sending re-INVITE, etc. Please see the reference documentation of Call for more info.

Instant Messaging(IM)¶

You can send IM within a call using Call.sendInstantMessage(). The transmission status of outgoing instant messages is reported in Call.onInstantMessageStatus() callback method.

In addition to sending instant messages, you can also send typing indication using Call.sendTypingIndication().

Incoming IM and typing indication received within a call will be reported in the callback functions Call.onInstantMessage() and Call.onTypingIndication().

Alternatively, you can send IM and typing indication outside a call by using Buddy.sendInstantMessage() and Buddy.sendTypingIndication(). For more information, please see Presence documentation.

Class Reference¶

Call¶

class Call

Call.

Public Functions

Call(Account &acc, int call_id = PJSUA_INVALID_ID): Constructor.

virtual ~Call(): Destructor.

CallInfo getInfo () const PJSUA2_THROW(Error)

Obtain detail information about this call.

Returns: Call info.

bool isActive() const

Check if this call has active INVITE session and the INVITE session has not been disconnected.

Returns: True if call is active.

int getId() const

Get PJSUA-LIB call ID or index associated with this call.

Returns: Integer greater than or equal to zero.

bool hasMedia() const

Check if call has an active media session.

Returns: True if yes.

Media *getMedia(unsigned med_idx) const

Warning: deprecated, use getAudioMedia() instead. This function is not safe in multithreaded environment.

Get media for the specified media index.

Parameters: med_idx – Media index.
Returns: The media or NULL if invalid or inactive.

AudioMedia getAudioMedia (int med_idx) const PJSUA2_THROW(Error)

Get audio media for the specified media index. If the specified media index is not audio or invalid or inactive, exception will be thrown.

Parameters: med_idx – Media index, or -1 to specify any first audio media registered in the conference bridge.
Returns: The audio media.

VideoMedia getEncodingVideoMedia (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.

Parameters: med_idx – Media index, or -1 to specify any first video media with encoding direction registered in the conference bridge.
Returns: The video media.

VideoMedia getDecodingVideoMedia (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.

Parameters: med_idx – Media index, or -1 to specify any first video media with decoding direction registered in the conference bridge.
Returns: The video media.

pjsip_dialog_cap_status remoteHasCap(int htype, const string &hname, const string &token) const

Check if remote peer support the specified capability.

Parameters

htype – The header type (pjsip_hdr_e) to be checked, which value may be:
- PJSIP_H_ACCEPT
- PJSIP_H_ALLOW
- PJSIP_H_SUPPORTED
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 (“”).
token – The capability token to check. For example, if htype is PJSIP_H_ALLOW, then token specifies the method names; if htype is PJSIP_H_SUPPORTED, then token specifies the extension names such as “100rel”.

Returns

PJSIP_DIALOG_CAP_SUPPORTED if the specified capability is explicitly supported, see pjsip_dialog_cap_status for more info.

void setUserData(Token user_data)

Attach application specific data to the call. Application can then inspect this data by calling getUserData().

Parameters: user_data – Arbitrary data to be attached to the call.

Token getUserData() const

Get user data attached to the call, which has been previously set with setUserData().

Returns: The user data.

pj_stun_nat_type getRemNatType () PJSUA2_THROW(Error)

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 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 200/OK response to INVITE). As a general case, application should call this function after or in onCallMediaState() callback.

Settings¶

struct CallSetting

Call settings.

Public Functions

CallSetting(bool useDefaultValues = false): Default constructor initializes with empty or default values.

bool isEmpty() const

Check if the settings are set with empty values.

Returns: True if the settings are empty.

void fromPj(const pjsua_call_setting &prm): Convert from pjsip

pjsua_call_setting toPj() const: Convert to pjsip

Public Members

unsigned flag

Bitmask of pjsua_call_flag constants.

Default: PJSUA_CALL_INCLUDE_DISABLED_MEDIA

unsigned reqKeyframeMethod

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 audioCount

Number of simultaneous active audio streams for this call. Setting this to zero will disable audio in this call.

Default: 1

unsigned videoCount

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)

Info and Statistics¶

struct CallInfo

Call information. Application can query the call information by calling Call::getInfo().

Public Functions

inline CallInfo(): Default constructor

void fromPj(const pjsua_call_info &pci): Convert from pjsip

Public Members

pjsua_call_id id: Call identification.

pjsip_role_e role: Initial call role (UAC == caller)

pjsua_acc_id accId: The account ID where this call belongs.

string localUri: Local URI

string localContact: Local Contact

string remoteUri: Remote URI

string remoteContact: Remote contact

string callIdString: Dialog Call-ID string.

CallSetting setting: Call setting

pjsip_inv_state state: Call state

string stateText: Text describing the state

pjsip_status_code lastStatusCode: Last status code heard, which can be used as cause code

string lastReason: The reason phrase describing the last status.

CallMediaInfoVector media: Array of active media information.

CallMediaInfoVector provMedia: 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).

TimeVal connectDuration: Up-to-date call connected duration (zero when call is not established)

TimeVal totalDuration: Total call duration, including set-up time

bool remOfferer: Flag if remote was SDP offerer

unsigned remAudioCount: Number of audio streams offered by remote

unsigned remVideoCount: Number of video streams offered by remote

struct CallMediaInfo

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.

Public Functions

CallMediaInfo(): Default constructor

void fromPj(const pjsua_call_media_info &prm): Convert from pjsip

Public Members

unsigned index: Media index in SDP.

pjmedia_type type: Media type.

pjmedia_dir dir: Media direction.

pjsua_call_media_status status: Call media status.

int audioConfSlot

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.

pjsua_vid_win_id videoIncomingWindowId: The window id for incoming video, if any, or PJSUA_INVALID_ID. Only valid if the media type is video.

VideoWindow videoWindow: The video window instance for incoming video. Only valid if videoIncomingWindowId is not PJSUA_INVALID_ID and the media type is video.

pjmedia_vid_dev_index videoCapDev: The video capture device for outgoing transmission, if any, or PJMEDIA_VID_INVALID_DEV. Only valid if the media type is video.

struct StreamInfo

Media stream info.

Public Functions

inline StreamInfo(): Default constructor

void fromPj(const pjsua_stream_info &info): Convert from pjsip

Public Members

pjmedia_type type: Media type of this stream.

pjmedia_tp_proto proto: Transport protocol (RTP/AVP, etc.)

pjmedia_dir dir: Media direction.

SocketAddress remoteRtpAddress: Remote RTP address

SocketAddress remoteRtcpAddress: Optional remote RTCP address

unsigned txPt: Outgoing codec payload type.

unsigned rxPt: Incoming codec payload type.

string codecName: Codec name.

unsigned codecClockRate: Codec clock rate.

CodecParam audCodecParam: Optional audio codec param.

VidCodecParam vidCodecParam: Optional video codec param.

struct StreamStat

Media stream statistic.

Public Functions

void fromPj(const pjsua_stream_stat &prm): Convert from pjsip

Public Members

RtcpStat rtcp: RTCP statistic.

JbufState jbuf: Jitter buffer statistic.

struct JbufState

This structure describes jitter buffer state.

Public Functions

void fromPj(const pjmedia_jb_state &prm): Convert from pjsip

Public Members

unsigned frameSize: Individual frame size, in bytes.

unsigned minPrefetch: Minimum allowed prefetch, in frms.

unsigned maxPrefetch: Maximum allowed prefetch, in frms.

unsigned burst: Current burst level, in frames

unsigned prefetch: Current prefetch value, in frames

unsigned size: Current buffer size, in frames.

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.

struct RtcpStat

Bidirectional RTP stream statistics.

Public Functions

void fromPj(const pjmedia_rtcp_stat &prm): Convert from pjsip

Public Members

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.

struct RtcpStreamStat

Unidirectional RTP stream statistics.

Public Functions

void fromPj(const pjmedia_rtcp_stream_stat &prm): Convert from pjsip

Public Members

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

struct MathStat

This structure describes statistics state.

Public Functions

MathStat(): Default constructor

void fromPj(const pj_math_stat &prm): Convert from pjsip

Public Members

int n: number of samples

int max: maximum value

int min: minimum value

int last: last value

int mean: mean

struct MediaTransportInfo

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.

Public Functions

void fromPj(const pjmedia_transport_info &info): Convert from pjsip

Public Members

SocketAddress localRtpName: 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 localRtcpName: 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 srcRtpName: Remote address where RTP originated from. This can be empty string if no data is received from the remote.

SocketAddress srcRtcpName: Remote address where RTCP originated from. This can be empty string if no data is recevied from the remote.

Callback Parameters¶

struct OnCallStateParam

This structure contains parameters for Call::onCallState() callback.

Public Members

SipEvent e: Event which causes the call state to change.

struct OnCallTsxStateParam

This structure contains parameters for Call::onCallTsxState() callback.

Public Members

SipEvent e: Transaction event that caused the state change.

struct OnCallMediaStateParam: This structure contains parameters for Call::onCallMediaState() callback.

struct OnCallSdpCreatedParam

This structure contains parameters for Call::onCallSdpCreated() callback.

Public Members

SdpSession sdp: The SDP has just been created.

SdpSession remSdp: The remote SDP, will be empty if local is SDP offerer.

struct OnStreamCreatedParam

This structure contains parameters for Call::onStreamCreated() callback.

Public Members

MediaStream stream: Audio media stream, read-only.

unsigned streamIdx: Stream index in the audio media session, read-only.

bool destroyPort

Specify if PJSUA2 should take ownership of the port returned in the pPort parameter below. If set to PJ_TRUE, pjmedia_port_destroy() will be called on the port when it is no longer needed.

Default: PJ_FALSE

MediaPort pPort: 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.

struct OnStreamDestroyedParam

This structure contains parameters for Call::onStreamDestroyed() callback.

Public Members

MediaStream stream: Audio media stream.

unsigned streamIdx: Stream index in the audio media session.

struct OnDtmfDigitParam

This structure contains parameters for Call::onDtmfDigit() callback.

Public Members

pjsua_dtmf_method method: DTMF sending method.

string digit: DTMF ASCII digit.

unsigned duration: DTMF signal duration which might be included when sending DTMF using SIP INFO.

struct OnCallTransferRequestParam

This structure contains parameters for Call::onCallTransferRequest() callback.

Public Members

string dstUri: The destination where the call will be transferred to.

pjsip_status_code statusCode: Status code to be returned for the call transfer request. On input, it contains status code 202.

CallSetting opt: The current call setting, application can update this setting for the call being transferred.

Call *newCall: New Call derived object instantiated by application when the call transfer is about to be accepted.

struct OnCallTransferStatusParam

This structure contains parameters for Call::onCallTransferStatus() callback.

Public Members

pjsip_status_code statusCode: Status progress of the transfer request.

string reason: Status progress reason.

bool finalNotify: If true, no further notification will be reported. The statusCode specified in this callback is the final status.

bool cont: 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).

struct OnCallReplaceRequestParam

This structure contains parameters for Call::onCallReplaceRequest() callback.

Public Members

SipRxData rdata: The incoming INVITE request to replace the call.

pjsip_status_code statusCode: Status code to be set by application. Application should only return a final status (200-699)

string reason: Optional status text to be set by application.

CallSetting opt: The current call setting, application can update this setting for the call being replaced.

struct OnCallReplacedParam

This structure contains parameters for Call::onCallReplaced() callback.

Public Members

pjsua_call_id newCallId: The new call id.

Call *newCall: New Call derived object instantiated by application.

struct OnCallRxOfferParam

This structure contains parameters for Call::onCallRxOffer() callback.

Public Members

SdpSession offer: The new offer received.

pjsip_status_code statusCode: Status code to be returned for answering the offer. On input, it contains status code 200. Currently, valid values are only 200 and 488.

CallSetting opt: The current call setting, application can update this setting for answering the offer.

struct OnCallRedirectedParam

This structure contains parameters for Call::onCallRedirected() callback.

Public Members

string targetUri: The current target to be tried.

SipEvent e: 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.

struct OnCallMediaEventParam

This structure contains parameters for Call::onCallMediaEvent() callback.

Public Members

unsigned medIdx: The media stream index.

MediaEvent ev: The media event.

struct OnCallMediaTransportStateParam

This structure contains parameters for Call::onCallMediaTransportState() callback.

Public Members

unsigned medIdx: The media index.

pjsua_med_tp_st state: The media transport state

pj_status_t status: The last error code related to the media transport state.

int sipErrorCode: Optional SIP error code.

struct OnCreateMediaTransportParam

This structure contains parameters for Call::onCreateMediaTransport() callback.

Public Members

unsigned mediaIdx: The media index in the SDP for which this media transport will be used.

MediaTransport mediaTp: 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.

unsigned flags: Bitmask from pjsua_create_media_transport_flag.

struct CallOpParam

This structure contains parameters for Call::answer(), Call::hangup(), Call::reinvite(), Call::update(), Call::xfer(), Call::xferReplaces(), Call::setHold().

Public Functions

CallOpParam(bool useDefaultCallSetting = false): Default constructor initializes with zero/empty values. Setting useDefaultCallSetting to true will initialize opt with default call setting values.

Public Members

CallSetting opt: The call setting.

pjsip_status_code statusCode: Status code.

string reason: Reason phrase.

unsigned options: Options.

SipTxOption txOption: 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.

SdpSession sdp: SDP answer. Currently only used for Call::answer().

struct CallSendRequestParam

This structure contains parameters for Call::sendRequest()

Public Functions

CallSendRequestParam(): Default constructor initializes with zero/empty values.

Public Members

string method: SIP method of the request.

SipTxOption txOption: Message body and/or list of headers etc to be included in outgoing request.

struct CallVidSetStreamParam

This structure contains parameters for Call::vidSetStream()

Public Functions

CallVidSetStreamParam(): Default constructor

Public Members

int medIdx

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)

pjmedia_dir dir

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_vid_dev_index capDev

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.

Other¶

struct MediaEvent

This structure describes a media event. It corresponds to the pjmedia_event structure.

Public Functions

inline MediaEvent(): Default constructor

void fromPj(const pjmedia_event &ev): Convert from pjsip

Public Members

pjmedia_event_type type: The event type.

MediaEventData data: Additional data/parameters about the event. The type of data will be specific to the event type being reported.

void *pjMediaEvent: Pointer to original pjmedia_event. Only valid when the struct is converted from PJSIP’s pjmedia_event.

struct MediaFmtChangedEvent

This structure describes a media format changed event.

Public Members

unsigned newWidth: The new width.

unsigned newHeight: The new height.

struct SdpSession

This structure describes SDP session description. It corresponds to the pjmedia_sdp_session structure.

Public Functions

void fromPj(const pjmedia_sdp_session &sdp): Convert from pjsip

Public Members

string wholeSdp: The whole SDP as a string.

void *pjSdpSession: Pointer to its original pjmedia_sdp_session. Only valid when the struct is converted from PJSIP’s pjmedia_sdp_session.

struct RtcpSdes: RTCP SDES structure.