Group PJSUA_LIB_CALL

group PJSUA_LIB_CALL

Call manipulation.

Defines

PJSUA_MAX_CALLS

Maximum simultaneous calls.

PJSUA_MAX_VID_WINS

Maximum active video windows

PJSUA_LOCK_CODEC_DONT_USE_UPDATE

Specifies if lock codec feature should always use INVITE method. This will also affect ICE completion update in updating default address in SDP.

This can be useful when communicating with endpoints that do not respond to UPDATE properly while indicating UPDATE support (by specifying UPDATE in its SIP Allow header).

Note that UPDATE can be sent when dialog is still in early state, while re-INVITE needs to wait until the dialog is confirmed.

PJSUA_CALL_SEND_DTMF_DURATION_DEFAULT

Specify the default signal duration when sending DTMF using SIP INFO.

Default is 160

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

Typedefs

typedef int pjsua_vid_win_id

Video window ID.

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, or the media is not used.

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_vid_req_keyframe_method

Enumeration of video keyframe request methods. Keyframe request is triggered by decoder, usually when the incoming video stream cannot be decoded properly due to missing video keyframe.

Values:

enumerator PJSUA_VID_REQ_KEYFRAME_SIP_INFO

Requesting keyframe via SIP INFO message. Note that incoming keyframe request via SIP INFO will always be handled even if this flag is unset.

enumerator PJSUA_VID_REQ_KEYFRAME_RTCP_PLI

Requesting keyframe via Picture Loss Indication of RTCP feedback.

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() and pjsua_call_update(). 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_set_hold2(), 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.

enumerator PJSUA_CALL_INCLUDE_DISABLED_MEDIA

Include SDP “m=” line with port set to zero for each disabled media (i.e when aud_cnt or vid_cnt is set to zero). This flag is only valid for pjsua_call_make_call(), pjsua_call_reinvite(), and pjsua_call_update(). Note that even this flag is applicable in pjsua_call_reinvite() and pjsua_call_update(), it will only take effect when the re-INVITE/UPDATE operation regenerates SDP offer, such as changing audio or video count in the call setting.

enumerator PJSUA_CALL_NO_SDP_OFFER

Do not send SDP when sending INVITE or UPDATE. This flag is only valid for pjsua_call_make_call(), pjsua_call_reinvite()/reinvite2(), or pjsua_call_update()/update2(). For re-invite/update, specifying PJSUA_CALL_UNHOLD will take precedence over this flag.

enumerator PJSUA_CALL_REINIT_MEDIA

Deinitialize and recreate media, including media transport. This flag is useful in IP address change situation, if the media transport address (or address family) changes, for example during IPv4/IPv6 network handover. This flag is only valid for pjsua_call_reinvite()/reinvite2(), or pjsua_call_update()/update2().

Warning: If the re-INVITE/UPDATE fails, the old media will not be reverted.

enumerator PJSUA_CALL_UPDATE_VIA

Update the local invite session’s Via with the via address from the account. This flag is only valid for pjsua_call_set_hold2(), pjsua_call_reinvite() and pjsua_call_update(). Similar to the flag PJSUA_CALL_UPDATE_CONTACT above, this flag is useful in IP address change situation, after the local account’s Via has been updated (typically with re-registration).

enumerator PJSUA_CALL_UPDATE_TARGET

Update dialog target to URI specified in pjsua_msg_data.target_uri. This flag is only valid for pjsua_call_set_hold(), pjsua_call_reinvite(), and pjsua_call_update(). This flag can be useful in IP address change scenario where IP version has been changed and application needs to update target IP address.

enumerator PJSUA_CALL_SET_MEDIA_DIR

Set media direction as specified in pjsua_call_setting.media_dir.

enum pjsua_call_vid_strm_op

This enumeration represents video stream operation on a call. See also pjsua_call_vid_strm_op_param for further info.

Values:

enumerator PJSUA_CALL_VID_STRM_NO_OP

No operation

enumerator PJSUA_CALL_VID_STRM_ADD

Add a new video stream. This will add a new m=video line to the media, regardless of whether existing video is/are present or not. This will cause re-INVITE or UPDATE to be sent to remote party.

enumerator PJSUA_CALL_VID_STRM_REMOVE

Remove/disable an existing video stream. This will cause re-INVITE or UPDATE to be sent to remote party.

enumerator PJSUA_CALL_VID_STRM_CHANGE_DIR

Change direction of a video stream. This operation can be used to activate or deactivate an existing video media. This will cause re-INVITE or UPDATE to be sent to remote party.

enumerator PJSUA_CALL_VID_STRM_CHANGE_CAP_DEV

Change capture device of a video stream. This will not send re-INVITE or UPDATE to remote party.

enumerator PJSUA_CALL_VID_STRM_START_TRANSMIT

Start transmitting video stream. This will cause previously stopped stream to start transmitting again. Note that no re-INVITE/UPDATE is to be transmitted to remote since this operation only operates on local stream.

enumerator PJSUA_CALL_VID_STRM_STOP_TRANSMIT

Stop transmitting video stream. This will cause the stream to be paused in TX direction, causing it to stop sending any video packets. No re-INVITE/UPDATE is to be transmitted to remote with this operation.

enumerator PJSUA_CALL_VID_STRM_SEND_KEYFRAME

Send keyframe in the video stream. This will force the stream to generate and send video keyframe as soon as possible. No re-INVITE/UPDATE is to be transmitted to remote with this operation.

Functions

void pjsua_call_setting_default(pjsua_call_setting *opt)

Initialize call settings.

Parameters:

opt – The call setting to be initialized.

void pjsua_call_vid_strm_op_param_default(pjsua_call_vid_strm_op_param *param)

Initialize video stream operation param with default values.

Parameters:

param – The video stream operation param to be initialized.

void pjsua_call_send_dtmf_param_default(pjsua_call_send_dtmf_param *param)

Initialize send DTMF param with default values.

Parameters:

param – The send DTMF param to be initialized.

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 the number of current calls. The number includes active calls (pjsua_call_is_active(call_id) == PJ_TRUE), as well as calls that are no longer active but still in the process of hanging up.

Returns:

Number of current 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, const pjsua_call_setting *opt, 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).

  • opt – Optional call setting. This should be initialized using pjsua_call_setting_default().

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

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.

pjsua_vid_win_id pjsua_call_get_vid_win(pjsua_call_id call_id)

Get the video window associated with the call. Note that this function will only evaluate the first video stream in the call, to query any other video stream, use pjsua_call_get_info().

Parameters:

call_id – Call identification.

Returns:

Video window, or PJSUA_INVALID_ID when the media has not been established or is not active.

pjsua_conf_port_id pjsua_call_get_vid_conf_port(pjsua_call_id call_id, pjmedia_dir dir)

Get the video conference port identification associated with the call. Note that this function will only evaluate the first video stream in the call, to query any other video stream, use pjsua_call_get_info().

Parameters:

  • call_id – Call identification.

  • dir – Port direction to be queried. Valid values are PJMEDIA_DIR_ENCODING and PJMEDIA_DIR_DECODING only.

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 pjsip_dialog_cap_status 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 also

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. See also pjsua_call_answer2().

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. Note that this message data will be persistent in all next answers/responses for this INVITE request.

Returns:

PJ_SUCCESS on success, or the appropriate error code.

pj_status_t pjsua_call_answer2(pjsua_call_id call_id, const pjsua_call_setting *opt, unsigned code, const pj_str_t *reason, const pjsua_msg_data *msg_data)

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 pjsua_call_setting for its default values.

Parameters:

  • call_id – Incoming call identification.

  • opt – Optional call setting.

  • 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. Note that this message data will be persistent in all next answers/responses for this INVITE request.

Returns:

PJ_SUCCESS on success, or the appropriate error code.

pj_status_t pjsua_call_answer_with_sdp(pjsua_call_id call_id, const pjmedia_sdp_session *sdp, const pjsua_call_setting *opt, unsigned code, const pj_str_t *reason, const pjsua_msg_data *msg_data)

Same as pjsua_call_answer2() but this function will set the SDP answer first before sending the response.

Parameters:

  • call_id – Incoming call identification.

  • sdp – SDP answer.

  • opt – Optional call setting.

  • 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. Note that this message data will be persistent in all next answers/responses for this INVITE request.

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.

After calling this function, media will be deinitialized (call media callbacks, if any, will still be received) and then, on_call_state() will be immediately called with state DISCONNECTED. No further call callbacks will be received after this. The call hangup process itself (sending BYE, waiting for the response, and resource cleanup) will continue in the background and the call slot can be reused only after this process is completed. If application has limited call slots and would like to check if there are any free slots remaining, it can query the number of free slots using the APIs: pjsua_call_get_max_count()-pjsua_call_get_count()

Note that on_call_tsx_state() will not be called when using this API.

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_set_hold2(pjsua_call_id call_id, unsigned options, 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.

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

  • 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 request or 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_reinvite2(pjsua_call_id call_id, const pjsua_call_setting *opt, const pjsua_msg_data *msg_data)

Send re-INVITE request or 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.

  • opt – Optional call setting, if NULL, the current call setting will be used. Note that to release hold or update contact or omit SDP offer, this parameter cannot be NULL and it must specify appropriate flags, e.g: PJSUA_CALL_UNHOLD, PJSUA_CALL_UPDATE_CONTACT, PJSUA_CALL_NO_SDP_OFFER.

  • 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_update2(pjsua_call_id call_id, const pjsua_call_setting *opt, const pjsua_msg_data *msg_data)

Send UPDATE request.

Parameters:

  • call_id – Call identification.

  • opt – Optional call setting, if NULL, the current call setting will be used. Note that to release hold or update contact or omit SDP offer, this parameter cannot be NULL and it must specify appropriate flags, e.g: PJSUA_CALL_UNHOLD, PJSUA_CALL_UPDATE_CONTACT, PJSUA_CALL_NO_SDP_OFFER.

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

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

  • 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. Use pjsua_call_send_dtmf() to send DTMF using SIP INFO or other method in pjsua_dtmf_method. App can use on_dtmf_digit() or on_dtmf_digit2() callback to monitor incoming DTMF.

Parameters:

  • call_id – Call identification.

  • digits – DTMF string digits to be sent as described on RFC 2833 section 3.10. If PJMEDIA_HAS_DTMF_FLASH is enabled, character ‘R’ is used to represent the event type 16 (flash) as stated in RFC 4730.

Returns:

PJ_SUCCESS on success, or the appropriate error code.

pj_status_t pjsua_call_send_dtmf(pjsua_call_id call_id, const pjsua_call_send_dtmf_param *param)

Send DTMF digits to remote. Use this method to send DTMF using the method in pjsua_dtmf_method. This method will call pjsua_call_dial_dtmf() when sending DTMF using PJSUA_DTMF_METHOD_RFC2833. Note that on_dtmf_digit() callback can only monitor incoming DTMF using RFC 2833. App can use on_dtmf_digit2() to monitor incoming DTMF using the method in pjsua_dtmf_method. Note that on_dtmf_digit() will not be called once on_dtmf_digit2() is implemented.

Parameters:

  • call_id – Call identification.

  • param – The send DTMF parameter.

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. Can be NULL if msg_data specifies body and/or multipart.

  • msg_data – Optional list of headers etc to be included in outgoing request. The body descriptor in the msg_data is ignored if parameter ‘content’ is set.

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

int pjsua_call_get_vid_stream_idx(pjsua_call_id call_id)

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.

Parameters:

call_id – Call identification.

Returns:

The media stream index or -1 if no video stream is present in the call.

pj_bool_t pjsua_call_vid_stream_is_running(pjsua_call_id call_id, int med_idx, pjmedia_dir dir)

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.

Parameters:

  • call_id – Call identification.

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

  • dir – The direction to be checked.

Returns:

PJ_TRUE if stream is currently running for the specified direction.

pj_status_t pjsua_call_set_vid_strm(pjsua_call_id call_id, pjsua_call_vid_strm_op op, const pjsua_call_vid_strm_op_param *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:

  • call_id – Call identification.

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

  • param – The parameters for the video stream operation, or NULL for the default parameter values (see pjsua_call_vid_strm_op_param).

Returns:

PJ_SUCCESS on success or the appropriate error.

pj_status_t pjsua_call_vid_stream_modify_codec_param(pjsua_call_id call_id, int med_idx, const pjmedia_vid_codec_param *param)

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

Parameters:

  • call_id – Call identification.

  • med_idx – Video stream index.

  • param – The new codec parameter.

Returns:

PJ_SUCCESS on success.

pj_status_t pjsua_call_aud_stream_modify_codec_param(pjsua_call_id call_id, int med_idx, const pjmedia_codec_param *param)

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.

Parameters:

  • call_id – Call identification.

  • med_idx – Media stream index, or -1 to specify default audio media.

  • param – The new codec parameter.

Returns:

PJ_SUCCESS on success.

pj_status_t pjsua_call_get_stream_info(pjsua_call_id call_id, unsigned med_idx, pjsua_stream_info *psi)

Get media stream info for the specified media index.

Parameters:

  • call_id – The call identification.

  • med_idx – Media stream index.

  • psi – To be filled with the stream info.

Returns:

PJ_SUCCESS on success or the appropriate error.

pj_status_t pjsua_call_get_stream_stat(pjsua_call_id call_id, unsigned med_idx, pjsua_stream_stat *stat)

Get media stream statistic for the specified media index.

Parameters:

  • call_id – The call identification.

  • med_idx – Media stream index.

  • stat – To be filled with the stream statistic.

Returns:

PJ_SUCCESS on success or the appropriate error.

pj_status_t pjsua_call_get_med_transport_info(pjsua_call_id call_id, unsigned med_idx, pjmedia_transport_info *t)

Get media transport info for the specified media index.

Parameters:

  • call_id – The call identification.

  • med_idx – Media stream index.

  • t – To be filled with the transport info.

Returns:

PJ_SUCCESS on success or the appropriate error.

struct pjsua_call_media_info
#include <pjsua.h>

Call media information.

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.

pjsua_conf_port_id conf_slot

The conference port number for the call.

struct pjsua_call_media_info::[anonymous]::[anonymous] aud

Audio stream

pjsua_vid_win_id win_in

The window id for incoming video, if any, or PJSUA_INVALID_ID.

pjsua_conf_port_id dec_slot

The video conference port number for the call in decoding direction.

pjsua_conf_port_id enc_slot

The video conference port number for the call in encoding direction.

pjmedia_vid_dev_index cap_dev

The video capture device for outgoing transmission, if any, or PJMEDIA_VID_INVALID_DEV

struct pjsua_call_media_info::[anonymous]::[anonymous] vid

Video stream

union pjsua_call_media_info::[anonymous] stream

The specific media stream info.

struct pjsua_call_info
#include <pjsua.h>

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

Public Members

pjsua_call_id id

Call identification.

pjsip_role_e role

Initial call role (UAC == caller)

pjsua_acc_id acc_id

The account ID where this call belongs.

pj_str_t local_info

Local URI

pj_str_t local_contact

Local Contact

pj_str_t remote_info

Remote URI

pj_str_t remote_contact

Remote contact

pj_str_t call_id

Dialog Call-ID string.

pjsua_call_setting setting

Call setting

pjsip_inv_state state

Call state

pj_str_t state_text

Text describing the state

pjsip_status_code last_status

Last status code heard, which can be used as cause code

pj_str_t last_status_text

The reason phrase describing the status.

pjsua_call_media_status media_status

Media status of the default audio stream. Default audio stream is chosen according to this priority:

  1. enabled, i.e: SDP media port not zero

  2. transport protocol in the SDP matching account config’s secure media transport usage (use_srtp field).

  3. active, i.e: SDP media direction is not “inactive”

  4. media order (according to the SDP).

pjmedia_dir media_dir

Media direction of the default audio stream. See media_status above on how the default is chosen.

pjsua_conf_port_id conf_slot

The conference port number for the default audio stream. See media_status above on how the default is chosen.

unsigned media_cnt

Number of active media info in this call.

pjsua_call_media_info media[PJMEDIA_MAX_SDP_MEDIA]

Array of active media information.

unsigned prov_media_cnt

Number of provisional media info in this call.

pjsua_call_media_info prov_media[PJMEDIA_MAX_SDP_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).

pj_time_val connect_duration

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

pj_time_val total_duration

Total call duration, including set-up time

pj_bool_t rem_offerer

Flag if remote was SDP offerer

unsigned rem_aud_cnt

Number of audio streams offered by remote

unsigned rem_vid_cnt

Number of video streams offered by remote

struct pjsua_call_info::[anonymous] buf_

Internal

struct pjsua_call_vid_strm_op_param
#include <pjsua.h>

Parameters for video stream operation on a call. Application should use pjsua_call_vid_strm_op_param_default() to initialize this structure with its default values.

Public Members

int med_idx

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 cap_dev

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.

struct pjsua_call_send_dtmf_param
#include <pjsua.h>

Parameters for sending DTMF. Application should use pjsua_call_send_dtmf_param_default() to initialize this structure with its default values.

Public Members

pjsua_dtmf_method method

The method used to send DTMF.

Default: PJSUA_DTMF_METHOD_RFC2833

unsigned duration

The signal duration used for the DTMF.

Default: PJSUA_CALL_SEND_DTMF_DURATION_DEFAULT

pj_str_t digits

The DTMF digits to be sent.