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

Obtain detail information about this call.

Return

Call info.

bool isActive() const

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

Return

True if call is active.

int getId() const

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

Return

Integer greater than or equal to zero.

bool hasMedia() const

Check if call has an active media session.

Return

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.

Return

The media or NULL if invalid or inactive.

Parameters

AudioMedia getAudioMedia(int 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.

Return

The audio media.

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

VideoMedia getEncodingVideoMedia(int med_idx) const

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.

Return

The video media.

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

VideoMedia getDecodingVideoMedia(int med_idx) const

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.

Return

The video media.

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

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

Check if remote peer support the specified capability.

Return

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

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”.

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().

Return

The user data.

pj_stun_nat_type getRemNatType()

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.

Return

The NAT type.

See

Endpoint::natGetType(), natTypeInSdp

void makeCall(const string &dst_uri, const CallOpParam &prm)

Make outgoing call to the specified URI.

Parameters
  • dst_uri: URI to be put in the To header (normally is the same as the target URI).

  • prm.opt: Optional call setting.

  • prm.txOption: Optional headers etc to be added to outgoing INVITE request.

void answer(const CallOpParam &prm)

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.

Parameters
  • prm.opt: Optional call setting.

  • prm.statusCode: Status code, (100-699).

  • prm.reason: Optional reason phrase. If empty, default text will be used.

  • 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 hangup(const CallOpParam &prm)

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.

Parameters
  • prm.statusCode: Optional status code to be sent when we’re rejecting incoming call. If the value is zero, “603/Decline” will be sent.

  • prm.reason: Optional reason phrase to be sent when we’re rejecting incoming call. If empty, default text will be used.

  • prm.txOption: Optional list of headers etc to be added to outgoing request/response message.

void setHold(const CallOpParam &prm)

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 onCallMediaState() callback, which inform the application that the media state of the call has changed.

Parameters
  • prm.options: Bitmask of pjsua_call_flag constants. Currently, only the flag PJSUA_CALL_UPDATE_CONTACT can be used.

  • prm.txOption: Optional message components to be sent with the request.

void reinvite(const CallOpParam &prm)

Send re-INVITE. The final status of the request itself will be reported on the onCallMediaState() callback, which inform the application that the media state of the call has changed.

Parameters
  • prm.opt: Optional call setting, if empty, the current call setting will remain unchanged.

  • prm.opt.flag: Bitmask of pjsua_call_flag constants. Specifying PJSUA_CALL_UNHOLD here will release call hold.

  • prm.txOption: Optional message components to be sent with the request.

void update(const CallOpParam &prm)

Send UPDATE request.

Parameters
  • prm.opt: Optional call setting, if empty, the current call setting will remain unchanged.

  • prm.txOption: Optional message components to be sent with the request.

void xfer(const string &dest, const CallOpParam &prm)

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 onCallTransferStatus() callback which will report the progress of the call transfer request.

Parameters
  • dest: URI of new target to be contacted. The URI may be in name address or addr-spec format.

  • prm.txOption: Optional message components to be sent with the request.

void xferReplaces(const Call &dest_call, const CallOpParam &prm)

Initiate attended call transfer. This function will send REFER request to instruct remote call party to initiate new INVITE session to the URL of destCall. The party at dest_call then should “replace” the call with us with the new call from the REFER recipient.

Parameters
  • dest_call: The call to be replaced.

  • 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.

  • prm.txOption: Optional message components to be sent with the request.

void processRedirect(pjsip_redirect_op cmd)

Accept or reject redirection response. Application MUST call this function after it signaled PJSIP_REDIRECT_PENDING in the 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 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 onCallRedirected() callback may also be called before this function returns if there is another target to try.

Parameters
  • cmd: Redirection operation to be applied to the current target. The semantic of this argument is similar to the description in the onCallRedirected() callback, except that the PJSIP_REDIRECT_PENDING is not accepted here.

void dialDtmf(const string &digits)

Send DTMF digits to remote using RFC 2833 payload formats.

Parameters
  • digits: DTMF string digits to be sent.

void sendDtmf(const CallSendDtmfParam &param)

Send DTMF digits to remote.

Parameters
  • param: The send DTMF parameter.

void sendInstantMessage(const SendInstantMessageParam &prm)

Send instant messaging inside INVITE session.

Parameters
  • prm.contentType: MIME type.

  • prm.content: The message content.

  • prm.txOption: Optional list of headers etc to be included in outgoing request. The body descriptor in the txOption is ignored.

  • prm.userData: Optional user data, which will be given back when the IM callback is called.

void sendTypingIndication(const SendTypingIndicationParam &prm)

Send IM typing indication inside INVITE session.

Parameters
  • prm.isTyping: True to indicate to remote that local person is currently typing an IM.

  • prm.txOption: Optional list of headers etc to be included in outgoing request.

void sendRequest(const CallSendRequestParam &prm)

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.

Parameters
  • prm.method: SIP method of the request.

  • prm.txOption: Optional message body and/or list of headers to be included in outgoing request.

string dump(bool with_media, const string indent)

Dump call and media statistics to string.

Return

Call dump and media statistics string.

Parameters
  • with_media: True to include media information too.

  • indent: Spaces for left indentation.

int vidGetStreamIdx() const

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.

bool vidStreamIsRunning(int med_idx, pjmedia_dir dir) 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.

Return

True if stream is currently running for the specified direction.

Parameters
  • med_idx: Media stream index, or -1 to specify default video media.

  • dir: The direction to be checked.

void vidSetStream(pjsua_call_vid_strm_op op, const CallVidSetStreamParam &param)

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.

Parameters
  • op: The video stream operation to be performed, possible values are pjsua_call_vid_strm_op.

  • param: The parameters for the video stream operation (see CallVidSetStreamParam).

StreamInfo getStreamInfo(unsigned med_idx) const

Get media stream info for the specified media index.

Return

The stream info.

Parameters
  • med_idx: Media stream index.

StreamStat getStreamStat(unsigned med_idx) const

Get media stream statistic for the specified media index.

Return

The stream statistic.

Parameters
  • med_idx: Media stream index.

MediaTransportInfo getMedTransportInfo(unsigned med_idx) const

Get media transport info for the specified media index.

Return

The transport info.

Parameters
  • med_idx: Media stream index.

void processMediaUpdate(OnCallMediaStateParam &prm)

Internal function (callled by Endpoint( to process update to call medias when call media state changes.

void processStateChange(OnCallStateParam &prm)

Internal function (called by Endpoint) to process call state change.

virtual void onCallState(OnCallStateParam &prm)

Notify application when call state has changed. Application may then query the call info to get the detail call states by calling getInfo() function.

Parameters
  • prm: Callback parameter.

virtual void onCallTsxState(OnCallTsxStateParam &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.

Parameters
  • prm: Callback parameter.

virtual void onCallMediaState(OnCallMediaStateParam &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.

Parameters
  • prm: Callback parameter.

virtual void onCallSdpCreated(OnCallSdpCreatedParam &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.

Parameters
  • prm: Callback parameter.

virtual void onStreamCreated(OnStreamCreatedParam &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.

Parameters
  • prm: Callback parameter.

virtual void onStreamDestroyed(OnStreamDestroyedParam &prm)

Notify application when audio media session has been unregistered from the conference bridge and about to be destroyed.

Parameters
  • prm: Callback parameter.

virtual void onDtmfDigit(OnDtmfDigitParam &prm)

Notify application upon incoming DTMF digits.

Parameters
  • prm: Callback parameter.

virtual void onCallTransferRequest(OnCallTransferRequestParam &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.

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.

Parameters
  • prm: Callback parameter.

virtual void onCallTransferStatus(OnCallTransferStatusParam &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.

Parameters
  • prm: Callback parameter.

virtual void onCallReplaceRequest(OnCallReplaceRequestParam &prm)

Notify application about incoming INVITE with Replaces header. Application may reject the request by setting non-2xx code.

Parameters
  • prm: Callback parameter.

virtual void onCallReplaced(OnCallReplacedParam &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. To be able to control the call, e.g: hold, transfer, change media parameters, application must instantiate a new Call object for the new call using call ID specified in prm.newCallId, and return the Call object via prm.newCall.

Parameters
  • prm: Callback parameter.

virtual void onCallRxOffer(OnCallRxOfferParam &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 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.

Parameters
  • prm: Callback parameter.

virtual void onCallRxReinvite(OnCallRxReinviteParam &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 async to PJ_TRUE, it can send the reply manually using the function #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 487 due to being cancelled.

Note: onCallRxOffer() will still be called after this callback, but only if prm.async is false and prm.code is 200.

virtual void onCallTxOffer(OnCallTxOfferParam &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).

Parameters
  • prm: Callback parameter.

virtual void onInstantMessage(OnInstantMessageParam &prm)

Notify application on incoming MESSAGE request.

Parameters
  • prm: Callback parameter.

virtual void onInstantMessageStatus(OnInstantMessageStatusParam &prm)

Notify application about the delivery status of outgoing MESSAGE request.

Parameters
  • prm: Callback parameter.

virtual void onTypingIndication(OnTypingIndicationParam &prm)

Notify application about typing indication.

Parameters
  • prm: Callback parameter.

virtual pjsip_redirect_op onCallRedirected(OnCallRedirectedParam &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.

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.

Parameters
  • prm: Callback parameter.

virtual void onCallMediaTransportState(OnCallMediaTransportStateParam &prm)

This callback is called when media transport state is changed.

Parameters
  • prm: Callback parameter.

virtual void onCallMediaEvent(OnCallMediaEventParam &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.

Parameters
  • prm: Callback parameter.

virtual void onCreateMediaTransport(OnCreateMediaTransportParam &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 mediaTp argument of this callback. The callback may change it with the instance of media transport to be used by the call.

Parameters
  • prm: Callback parameter.

virtual void onCreateMediaTransportSrtp(OnCreateMediaTransportSrtpParam &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 srtpOpt to specify the cryptos and keys which are going to be used. Note that application should not modify the field pjmedia_srtp_setting.close_member_tp and can only modify the field pjmedia_srtp_setting.use for initial INVITE.

Parameters
  • prm: Callback parameter.

Public Static Functions

static Call *lookup(int call_id)

Get the Call class for the specified call Id.

Return

The Call instance or NULL if not found.

Parameters
  • call_id: The call ID to lookup

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.

Return

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

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

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

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.