Group PJSUA_LIB_CALL

group PJSUA_LIB_CALL

Call manipulation.

Defines

PJSUA_MAX_CALLS

Maximum simultaneous calls.

PJSUA_XFER_NO_REQUIRE_REPLACES

Flag to indicate that “Require: replaces” should not be put in the outgoing INVITE request caused by REFER request created by pjsua_call_xfer_replaces().

Enums

enum pjsua_call_media_status

This enumeration specifies the media status of a call, and it’s part of pjsua_call_info structure.

Values:

enumerator PJSUA_CALL_MEDIA_NONE

Call currently has no media

enumerator PJSUA_CALL_MEDIA_ACTIVE

The media is active

enumerator PJSUA_CALL_MEDIA_LOCAL_HOLD

The media is currently put on hold by local endpoint

enumerator PJSUA_CALL_MEDIA_REMOTE_HOLD

The media is currently put on hold by remote endpoint

enumerator PJSUA_CALL_MEDIA_ERROR

The media has reported error (e.g. ICE negotiation)

enum pjsua_call_flag

Flags to be given to various call APIs. More than one flags may be specified by bitmasking them.

Values:

enumerator PJSUA_CALL_UNHOLD

When the call is being put on hold, specify this flag to unhold it. This flag is only valid for pjsua_call_reinvite(). Note: for compatibility reason, this flag must have value of 1 because previously the unhold option is specified as boolean value.

enumerator PJSUA_CALL_UPDATE_CONTACT

Update the local invite session’s contact with the contact URI from the account. This flag is only valid for pjsua_call_reinvite() and pjsua_call_update(). This flag is useful in IP address change situation, after the local account’s Contact has been updated (typically with re-registration) use this flag to update the invite session with the new Contact and to inform this new Contact to the remote peer with the outgoing re-INVITE or UPDATE

Functions

unsigned pjsua_call_get_max_count(void)

Get maximum number of calls configured in pjsua.

Returns

Maximum number of calls configured.

unsigned pjsua_call_get_count(void)

Get number of currently active calls.

Returns

Number of currently active calls.

pj_status_t pjsua_enum_calls(pjsua_call_id ids[], unsigned *count)

Enumerate all active calls. Application may then query the information and state of each call by calling pjsua_call_get_info().

Parameters

  • ids – Array of account IDs to be initialized.

  • count – In input, specifies the maximum number of elements. On return, it contains the actual number of elements.

Returns

PJ_SUCCESS on success, or the appropriate error code.

pj_status_t pjsua_call_make_call(pjsua_acc_id acc_id, const pj_str_t *dst_uri, unsigned options, void *user_data, const pjsua_msg_data *msg_data, pjsua_call_id *p_call_id)

Make outgoing call to the specified URI using the specified account.

Parameters

  • acc_id – The account to be used.

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

  • options – Options (must be zero at the moment).

  • user_data – Arbitrary user data to be attached to the call, and can be retrieved later.

  • msg_data – Optional headers etc to be added to outgoing INVITE request, or NULL if no custom header is desired.

  • p_call_id – Pointer to receive call identification.

Returns

PJ_SUCCESS on success, or the appropriate error code.

pj_bool_t pjsua_call_is_active(pjsua_call_id call_id)

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

Parameters

call_id – Call identification.

Returns

Non-zero if call is active.

pj_bool_t pjsua_call_has_media(pjsua_call_id call_id)

Check if call has an active media session.

Parameters

call_id – Call identification.

Returns

Non-zero if yes.

pjmedia_session *pjsua_call_get_media_session(pjsua_call_id call_id)

Retrieve the media session associated with this call. Note that the media session may not be available depending on the current call’s media status (the pjsua_call_media_status information in pjsua_call_info). Application may use the media session to retrieve more detailed information about the call’s media.

Parameters

call_id – Call identification.

Returns

Call media session.

pjmedia_transport *pjsua_call_get_media_transport(pjsua_call_id cid)

Retrieve the media transport instance that is used for this call. Application may use the media transport to query more detailed information about the media transport.

Parameters

cid – Call identification (the call_id).

Returns

Call media transport.

pjsua_conf_port_id pjsua_call_get_conf_port(pjsua_call_id call_id)

Get the conference port identification associated with the call.

Parameters

call_id – Call identification.

Returns

Conference port ID, or PJSUA_INVALID_ID when the media has not been established or is not active.

pj_status_t pjsua_call_get_info(pjsua_call_id call_id, pjsua_call_info *info)

Obtain detail information about the specified call.

Parameters

  • call_id – Call identification.

  • info – Call info to be initialized.

Returns

PJ_SUCCESS on success, or the appropriate error code.

pjsip_dialog_cap_status pjsua_call_remote_has_cap(pjsua_call_id call_id, int htype, const pj_str_t *hname, const pj_str_t *token)

Check if remote peer support the specified capability.

Parameters

  • call_id – Call identification.

  • htype – The header type 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 NULL.

  • 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 for more info.

pj_status_t pjsua_call_set_user_data(pjsua_call_id call_id, void *user_data)

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

Parameters

  • call_id – Call identification.

  • user_data – Arbitrary data to be attached to the call.

Returns

The user data.

void *pjsua_call_get_user_data(pjsua_call_id call_id)

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

Parameters

call_id – Call identification.

Returns

The user data.

pj_status_t pjsua_call_get_rem_nat_type(pjsua_call_id call_id, pj_stun_nat_type *p_type)

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 nat_type_in_sdp is set in pjsua_config.

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

See

pjsua_get_nat_type(), nat_type_in_sdp

Parameters

  • call_id – Call identification.

  • p_type – Pointer to store the NAT type. Application can then retrieve the string description of the NAT type by calling pj_stun_get_nat_name().

Returns

PJ_SUCCESS on success.

pj_status_t pjsua_call_answer(pjsua_call_id call_id, unsigned code, const pj_str_t *reason, const pjsua_msg_data *msg_data)

Send response to incoming INVITE request. Depending on the status code specified as parameter, this function may send provisional response, establish the call, or terminate the call.

Parameters

  • call_id – Incoming call identification.

  • code – Status code, (100-699).

  • reason – Optional reason phrase. If NULL, default text will be used.

  • msg_data – Optional list of headers etc to be added to outgoing response message.

Returns

PJ_SUCCESS on success, or the appropriate error code.

pj_status_t pjsua_call_hangup(pjsua_call_id call_id, unsigned code, const pj_str_t *reason, const pjsua_msg_data *msg_data)

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 pjsua_call_answer()), in that this function will hangup the call regardless of the state and role of the call, while pjsua_call_answer() only works with incoming calls on EARLY state.

Parameters

  • call_id – Call identification.

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

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

  • msg_data – Optional list of headers etc to be added to outgoing request/response message.

Returns

PJ_SUCCESS on success, or the appropriate error code.

pj_status_t pjsua_call_process_redirect(pjsua_call_id call_id, pjsip_redirect_op cmd)

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

Parameters

  • call_id – The call ID.

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

Returns

PJ_SUCCESS on successful operation.

pj_status_t pjsua_call_set_hold(pjsua_call_id call_id, const pjsua_msg_data *msg_data)

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

Parameters

  • call_id – Call identification.

  • msg_data – Optional message components to be sent with the request.

Returns

PJ_SUCCESS on success, or the appropriate error code.

pj_status_t pjsua_call_reinvite(pjsua_call_id call_id, unsigned options, const pjsua_msg_data *msg_data)

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

Parameters

  • call_id – Call identification.

  • options – Bitmask of pjsua_call_flag constants. Note that for compatibility, specifying PJ_TRUE here is equal to specifying PJSUA_CALL_UNHOLD flag.

  • msg_data – Optional message components to be sent with the request.

Returns

PJ_SUCCESS on success, or the appropriate error code.

pj_status_t pjsua_call_update(pjsua_call_id call_id, unsigned options, const pjsua_msg_data *msg_data)

Send UPDATE request.

Parameters

  • call_id – Call identification.

  • options – Bitmask of pjsua_call_flag constants.

  • msg_data – Optional message components to be sent with the request.

Returns

PJ_SUCCESS on success, or the appropriate error code.

pj_status_t pjsua_call_xfer(pjsua_call_id call_id, const pj_str_t *dest, const pjsua_msg_data *msg_data)

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

Parameters

  • call_id – The call id to be transfered.

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

  • msg_data – Optional message components to be sent with the request.

Returns

PJ_SUCCESS on success, or the appropriate error code.

pj_status_t pjsua_call_xfer_replaces(pjsua_call_id call_id, pjsua_call_id dest_call_id, unsigned options, const pjsua_msg_data *msg_data)

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

Parameters

  • call_id – The call id to be transfered.

  • dest_call_id – The call id to be replaced.

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

  • msg_data – Optional message components to be sent with the request.

Returns

PJ_SUCCESS on success, or the appropriate error code.

pj_status_t pjsua_call_dial_dtmf(pjsua_call_id call_id, const pj_str_t *digits)

Send DTMF digits to remote using RFC 2833 payload formats.

Parameters

  • call_id – Call identification.

  • digits – DTMF string digits to be sent.

Returns

PJ_SUCCESS on success, or the appropriate error code.

pj_status_t pjsua_call_send_im(pjsua_call_id call_id, const pj_str_t *mime_type, const pj_str_t *content, const pjsua_msg_data *msg_data, void *user_data)

Send instant messaging inside INVITE session.

Parameters

  • call_id – Call identification.

  • mime_type – Optional MIME type. If NULL, then “text/plain” is assumed.

  • content – The message content.

  • msg_data – Optional list of headers etc to be included in outgoing request. The body descriptor in the msg_data is ignored.

  • user_data – Optional user data, which will be given back when the IM callback is called.

Returns

PJ_SUCCESS on success, or the appropriate error code.

pj_status_t pjsua_call_send_typing_ind(pjsua_call_id call_id, pj_bool_t is_typing, const pjsua_msg_data *msg_data)

Send IM typing indication inside INVITE session.

Parameters

  • call_id – Call identification.

  • is_typing – Non-zero to indicate to remote that local person is currently typing an IM.

  • msg_data – Optional list of headers etc to be included in outgoing request.

Returns

PJ_SUCCESS on success, or the appropriate error code.

pj_status_t pjsua_call_send_request(pjsua_call_id call_id, const pj_str_t *method, const pjsua_msg_data *msg_data)

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

  • call_id – Call identification.

  • method – SIP method of the request.

  • msg_data – Optional message body and/or list of headers to be included in outgoing request.

Returns

PJ_SUCCESS on success, or the appropriate error code.

void pjsua_call_hangup_all(void)

Terminate all calls. This will initiate pjsua_call_hangup() for all currently active calls.

pj_status_t pjsua_call_dump(pjsua_call_id call_id, pj_bool_t with_media, char *buffer, unsigned maxlen, const char *indent)

Dump call and media statistics to string.

Parameters

  • call_id – Call identification.

  • with_media – Non-zero to include media information too.

  • buffer – Buffer where the statistics are to be written to.

  • maxlen – Maximum length of buffer.

  • indent – Spaces for left indentation.

Returns

PJ_SUCCESS on success.

struct pjsua_call_info
#include <pjsua.h>

This structure describes the information and current status of a call.