#include <pjsua.h>

Data Fields
void(*	on_call_state )(pjsua_call_id call_id, pjsip_event *e)

void(*	on_incoming_call )(pjsua_acc_id acc_id, pjsua_call_id call_id, pjsip_rx_data *rdata)

void(*	on_call_tsx_state )(pjsua_call_id call_id, pjsip_transaction tsx, pjsip_event e)

void(*	on_call_media_state )(pjsua_call_id call_id)

void(*	on_call_sdp_created )(pjsua_call_id call_id, pjmedia_sdp_session sdp, pj_pool_t pool, const pjmedia_sdp_session *rem_sdp)

void(*	on_stream_precreate )(pjsua_call_id call_id, pjsua_on_stream_precreate_param *param)

void(*	on_stream_created )(pjsua_call_id call_id, pjmedia_stream strm, unsigned stream_idx, pjmedia_port *p_port)

void(*	on_stream_created2 )(pjsua_call_id call_id, pjsua_on_stream_created_param *param)

void(*	on_stream_destroyed )(pjsua_call_id call_id, pjmedia_stream *strm, unsigned stream_idx)

void(*	on_dtmf_digit )(pjsua_call_id call_id, int digit)

void(*	on_dtmf_digit2 )(pjsua_call_id call_id, const pjsua_dtmf_info *info)

void(*	on_dtmf_event )(pjsua_call_id call_id, const pjsua_dtmf_event *event)

void(*	on_call_transfer_request )(pjsua_call_id call_id, const pj_str_t dst, pjsip_status_code code)

void(*	on_call_transfer_request2 )(pjsua_call_id call_id, const pj_str_t dst, pjsip_status_code code, pjsua_call_setting *opt)

void(*	on_call_transfer_status )(pjsua_call_id call_id, int st_code, const pj_str_t st_text, pj_bool_t final, pj_bool_t p_cont)

void(*	on_call_replace_request )(pjsua_call_id call_id, pjsip_rx_data rdata, int st_code, pj_str_t *st_text)

void(*	on_call_replace_request2 )(pjsua_call_id call_id, pjsip_rx_data rdata, int st_code, pj_str_t st_text, pjsua_call_setting opt)

void(*	on_call_replaced )(pjsua_call_id old_call_id, pjsua_call_id new_call_id)

void(*	on_call_rx_offer )(pjsua_call_id call_id, const pjmedia_sdp_session offer, void reserved, pjsip_status_code code, pjsua_call_setting opt)

void(*	on_call_rx_reinvite )(pjsua_call_id call_id, const pjmedia_sdp_session offer, pjsip_rx_data rdata, void reserved, pj_bool_t async, pjsip_status_code code, pjsua_call_setting opt)

void(*	on_call_tx_offer )(pjsua_call_id call_id, void reserved, pjsua_call_setting opt)

void(*	on_reg_started )(pjsua_acc_id acc_id, pj_bool_t renew)

void(*	on_reg_started2 )(pjsua_acc_id acc_id, pjsua_reg_info *info)

void(*	on_reg_state )(pjsua_acc_id acc_id)

void(*	on_reg_state2 )(pjsua_acc_id acc_id, pjsua_reg_info *info)

void(*	on_incoming_subscribe )(pjsua_acc_id acc_id, pjsua_srv_pres srv_pres, pjsua_buddy_id buddy_id, const pj_str_t from, pjsip_rx_data rdata, pjsip_status_code code, pj_str_t reason, pjsua_msg_data msg_data)

void(*	on_srv_subscribe_state )(pjsua_acc_id acc_id, pjsua_srv_pres srv_pres, const pj_str_t remote_uri, pjsip_evsub_state state, pjsip_event *event)

void(*	on_buddy_state )(pjsua_buddy_id buddy_id)

void(*	on_buddy_evsub_state )(pjsua_buddy_id buddy_id, pjsip_evsub sub, pjsip_event event)

void(*	on_pager )(pjsua_call_id call_id, const pj_str_t from, const pj_str_t to, const pj_str_t contact, const pj_str_t mime_type, const pj_str_t *body)

void(*	on_pager2 )(pjsua_call_id call_id, const pj_str_t from, const pj_str_t to, const pj_str_t contact, const pj_str_t mime_type, const pj_str_t body, pjsip_rx_data rdata, pjsua_acc_id acc_id)

void(*	on_pager_status )(pjsua_call_id call_id, const pj_str_t to, const pj_str_t body, void user_data, pjsip_status_code status, const pj_str_t reason)

void(*	on_pager_status2 )(pjsua_call_id call_id, const pj_str_t to, const pj_str_t body, void user_data, pjsip_status_code status, const pj_str_t reason, pjsip_tx_data tdata, pjsip_rx_data rdata, pjsua_acc_id acc_id)

void(*	on_typing )(pjsua_call_id call_id, const pj_str_t from, const pj_str_t to, const pj_str_t *contact, pj_bool_t is_typing)

void(*	on_typing2 )(pjsua_call_id call_id, const pj_str_t from, const pj_str_t to, const pj_str_t contact, pj_bool_t is_typing, pjsip_rx_data rdata, pjsua_acc_id acc_id)

void(*	on_nat_detect )(const pj_stun_nat_detect_result *res)

pjsip_redirect_op(*	on_call_redirected )(pjsua_call_id call_id, const pjsip_uri target, const pjsip_event e)

void(*	on_mwi_state )(pjsua_acc_id acc_id, pjsip_evsub *evsub)

void(*	on_mwi_info )(pjsua_acc_id acc_id, pjsua_mwi_info *mwi_info)

pjsip_tp_state_callback	on_transport_state

pjsua_med_tp_state_cb	on_call_media_transport_state

void(*	on_ice_transport_error )(int index, pj_ice_strans_op op, pj_status_t status, void *param)

pj_status_t(*	on_snd_dev_operation )(int operation)

void(*	on_call_media_event )(pjsua_call_id call_id, unsigned med_idx, pjmedia_event *event)

pjmedia_transport (	on_create_media_transport )(pjsua_call_id call_id, unsigned media_idx, pjmedia_transport *base_tp, unsigned flags)

void(*	on_create_media_transport_srtp )(pjsua_call_id call_id, unsigned media_idx, pjmedia_srtp_setting *srtp_opt)

void(*	on_acc_find_for_incoming )(const pjsip_rx_data rdata, pjsua_acc_id acc_id)

pj_stun_resolve_cb	on_stun_resolution_complete

void(*	on_ip_change_progress )(pjsua_ip_change_op op, pj_status_t status, const pjsua_ip_change_op_info *info)

void(*	on_media_event )(pjmedia_event *event)

Detailed Description

This structure describes application callback to receive various event notification from PJSUA-API. All of these callbacks are OPTIONAL, although definitely application would want to implement some of the important callbacks (such as on_incoming_call).

Field Documentation

◆ on_call_state

void(* pjsua_callback::on_call_state) (pjsua_call_id call_id, pjsip_event *e)

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

Parameters

call_id	The call index.
e	Event which causes the call state to change.

◆ on_incoming_call

void(* pjsua_callback::on_incoming_call) (pjsua_acc_id acc_id, pjsua_call_id call_id, pjsip_rx_data *rdata)

Notify application on incoming call.

Parameters

acc_id	The account which match the incoming call.
call_id	The call id that has just been created for the call.
rdata	The incoming INVITE request.

◆ on_call_tsx_state

void(* pjsua_callback::on_call_tsx_state) (pjsua_call_id call_id, pjsip_transaction *tsx, pjsip_event *e)

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

call_id	Call identification.
tsx	The transaction which has changed state.
e	Transaction event that caused the state change.

◆ on_call_media_state

void(* pjsua_callback::on_call_media_state) (pjsua_call_id call_id)

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. When DTLS-SRTP is used, this callback will also be called to report DTLS negotiation failure.

Parameters

call_id The call index.

◆ on_call_sdp_created

void(* pjsua_callback::on_call_sdp_created) (pjsua_call_id call_id, pjmedia_sdp_session *sdp, pj_pool_t *pool, const pjmedia_sdp_session *rem_sdp)

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

call_id	The call index.
sdp	The SDP has just been created.
pool	The pool instance, application should use this pool to modify the SDP.
rem_sdp	The remote SDP, will be NULL if local is SDP offerer.

◆ on_stream_precreate

void(* pjsua_callback::on_stream_precreate) (pjsua_call_id call_id, pjsua_on_stream_precreate_param *param)

Notify application when an audio media session is about to be created (as opposed to on_stream_created() and on_stream_created2() which are called after the session has been created). The application may change some stream info parameter values, i.e: jb_init, jb_min_pre, jb_max_pre, jb_max, use_ka, rtcp_sdes_bye_disabled, jb_discard_algo (audio), codec_param->enc_fmt (video).

Parameters

call_id	Call identification.
param	The on stream precreate callback parameter.

◆ on_stream_created

void(* pjsua_callback::on_stream_created) (pjsua_call_id call_id, pjmedia_stream *strm, unsigned stream_idx, pjmedia_port **p_port)

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.

Note: if implemented, on_stream_created2() callback will be called instead of this one.

Parameters

call_id	Call identification.
strm	Audio media stream.
stream_idx	Stream index in the audio media session.
p_port	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.

◆ on_stream_created2

void(* pjsua_callback::on_stream_created2) (pjsua_call_id call_id, pjsua_on_stream_created_param *param)

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

call_id	Call identification.
param	The on stream created callback parameter.

◆ on_stream_destroyed

void(* pjsua_callback::on_stream_destroyed) (pjsua_call_id call_id, pjmedia_stream *strm, unsigned stream_idx)

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

Parameters

call_id	Call identification.
strm	Audio media stream.
stream_idx	Stream index in the audio media session.

◆ on_dtmf_digit

void(* pjsua_callback::on_dtmf_digit) (pjsua_call_id call_id, int digit)

Notify application upon incoming DTMF digits using RFC 2833 payload formats. This callback will not be called if app implements on_dtmf_digit2() or on_dtmf_event().

Parameters

call_id	The call index.
digit	DTMF ASCII digit.

◆ on_dtmf_digit2

void(* pjsua_callback::on_dtmf_digit2) (pjsua_call_id call_id, const pjsua_dtmf_info *info)

Notify application upon incoming DTMF digits using the method specified in pjsua_dtmf_method. This callback will not be called if app implements on_dtmf_event().

Parameters

call_id	The call index.
info	The DTMF info.

◆ on_dtmf_event

void(* pjsua_callback::on_dtmf_event) (pjsua_call_id call_id, const pjsua_dtmf_event *event)

Notify application upon incoming DTMF digits using the method specified in pjsua_dtmf_method. Includes additional information about events received via RTP.

Parameters

call_id	The call index.
event	The DTMF event.

◆ on_call_transfer_request

void(* pjsua_callback::on_call_transfer_request) (pjsua_call_id call_id, const pj_str_t *dst, pjsip_status_code *code)

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 defined, the default behavior is to accept the transfer. See also on_call_transfer_request2() callback for the version with pjsua_call_setting in the argument list.

Parameters

call_id	The call index.
dst	The destination where the call will be transferred to.
code	Status code to be returned for the call transfer request. On input, it contains status code 202.

◆ on_call_transfer_request2

void(* pjsua_callback::on_call_transfer_request2) (pjsua_call_id call_id, const pj_str_t *dst, pjsip_status_code *code, pjsua_call_setting *opt)

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 defined, the default behavior is to accept the transfer.

Parameters

call_id	The call index.
dst	The destination where the call will be transferred to.
code	Status code to be returned for the call transfer request. On input, it contains status code 202.
opt	The current call setting, application can update this setting for the call being transferred.

◆ on_call_transfer_status

void(* pjsua_callback::on_call_transfer_status) (pjsua_call_id call_id, int st_code, const pj_str_t *st_text, pj_bool_t final, pj_bool_t *p_cont)

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

call_id	Call ID.
st_code	Status progress of the transfer request.
st_text	Status progress text.
final	If non-zero, no further notification will be reported. The st_code specified in this callback is the final status.
p_cont	Initially will be set to non-zero, application can set this to FALSE if it no longer wants to receie further notification (for example, after it hangs up the call).

◆ on_call_replace_request

void(* pjsua_callback::on_call_replace_request) (pjsua_call_id call_id, pjsip_rx_data *rdata, int *st_code, pj_str_t *st_text)

Notify application about incoming INVITE with Replaces header. Application may reject the request by setting non-2xx code. See also on_call_replace_request2() callback for the version with pjsua_call_setting in the argument list.

Parameters

call_id	The call ID to be replaced.
rdata	The incoming INVITE request to replace the call.
st_code	Status code to be set by application. Application should only return a final status (200-699).
st_text	Optional status text to be set by application.

◆ on_call_replace_request2

void(* pjsua_callback::on_call_replace_request2) (pjsua_call_id call_id, pjsip_rx_data *rdata, int *st_code, pj_str_t *st_text, pjsua_call_setting *opt)

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

Parameters

call_id	The call ID to be replaced.
rdata	The incoming INVITE request to replace the call.
st_code	Status code to be set by application. Application should only return a final status (200-699).
st_text	Optional status text to be set by application.
opt	The current call setting, application can update this setting for the call being replaced.

◆ on_call_replaced

void(* pjsua_callback::on_call_replaced) (pjsua_call_id old_call_id, pjsua_call_id new_call_id)

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 old_call_id and establish new_call_id.

Parameters

old_call_id	Existing call which to be replaced with the new call.
new_call_id	The new call.
rdata	The incoming INVITE with Replaces request.

◆ on_call_rx_offer

void(* pjsua_callback::on_call_rx_offer) (pjsua_call_id call_id, const pjmedia_sdp_session *offer, void *reserved, pjsip_status_code *code, pjsua_call_setting *opt)

Notify application when call has received new offer from remote (i.e. re-INVITE/UPDATE with SDP is received, or from the INVITE response in the case that the initial outgoing INVITE has no SDP). 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 defined, the default behavior is to accept the offer using current call setting.

Note: this callback may not be called if on_call_rx_reinvite() is implemented.

Parameters

call_id	The call index.
offer	The new offer received.
reserved	Reserved param, currently not used.
code	Status code to be returned for answering the offer. On input, it contains status code 200. Currently, valid values are only 200 and 488.
opt	The current call setting, application can update this setting for answering the offer.

◆ on_call_rx_reinvite

void(* pjsua_callback::on_call_rx_reinvite) (pjsua_call_id call_id, const pjmedia_sdp_session *offer, pjsip_rx_data *rdata, void *reserved, pj_bool_t *async, pjsip_status_code *code, pjsua_call_setting *opt)

Notify application when call has received a re-INVITE with 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 pjsua_call_answer_with_sdp(). 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 on_call_tsx_state() callback to check whether the re-INVITE is already answered automatically with 487 due to being cancelled.

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

Parameters

call_id	The call index.
offer	Remote offer.
rdata	The received re-INVITE request.
reserved	Reserved param, currently not used.
async	On input, it is PJ_FALSE. Set to PJ_TRUE if app wants to manually answer the re-INVITE.
code	Status code to be returned for answering the offer. On input, it contains status code 200. Currently, valid values are only 200 and 488.
opt	The current call setting, application can update this setting for answering the offer.

◆ on_call_tx_offer

void(* pjsua_callback::on_call_tx_offer) (pjsua_call_id call_id, void *reserved, pjsua_call_setting *opt)

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 defined, the default behavior is to send SDP offer using current active media session (with all enabled codecs on each media type).

Parameters

call_id	The call index.
reserved	Reserved param, currently not used.
opt	The current call setting, application can update this setting for generating the offer.

◆ on_reg_started

void(* pjsua_callback::on_reg_started) (pjsua_acc_id acc_id, pj_bool_t renew)

Notify application when registration or unregistration has been initiated. Note that this only notifies the initial registration and unregistration. Once registration session is active, subsequent refresh will not cause this callback to be called.

Parameters

acc_id	The account ID.
renew	Non-zero for registration and zero for unregistration.

◆ on_reg_started2

void(* pjsua_callback::on_reg_started2) (pjsua_acc_id acc_id, pjsua_reg_info *info)

This is the alternative version of the on_reg_started() callback with pjsua_reg_info argument.

Parameters

acc_id	The account ID.
info	The registration info.

◆ on_reg_state

void(* pjsua_callback::on_reg_state) (pjsua_acc_id acc_id)

Notify application when registration status has changed. Application may then query the account info to get the registration details.

Parameters

acc_id The account ID.

◆ on_reg_state2

void(* pjsua_callback::on_reg_state2) (pjsua_acc_id acc_id, pjsua_reg_info *info)

Notify application when registration status has changed. Application may inspect the registration info to get the registration status details.

Parameters

acc_id	The account ID.
info	The registration info.

◆ on_incoming_subscribe

void(* pjsua_callback::on_incoming_subscribe) (pjsua_acc_id acc_id, pjsua_srv_pres *srv_pres, pjsua_buddy_id buddy_id, const pj_str_t *from, pjsip_rx_data *rdata, pjsip_status_code *code, pj_str_t *reason, pjsua_msg_data *msg_data)

Notification when incoming SUBSCRIBE request is received. Application may use this callback to authorize the incoming subscribe request (e.g. ask user permission if the request should be granted).

If this callback is not implemented, all incoming presence subscription requests will be accepted.

If this callback is implemented, application has several choices on what to do with the incoming request:

it may reject the request immediately by specifying non-200 class final response in the code argument.
it may immediately accept the request by specifying 200 as the code argument. This is the default value if application doesn't set any value to the code argument. In this case, the library will automatically send NOTIFY request upon returning from this callback.
it may delay the processing of the request, for example to request user permission whether to accept or reject the request. In this case, the application MUST set the code argument to 202, then IMMEDIATELY calls pjsua_pres_notify() with state PJSIP_EVSUB_STATE_PENDING and later calls pjsua_pres_notify() again to accept or reject the subscription request.

Any code other than 200 and 202 will be treated as 200.

Application MUST return from this callback immediately (e.g. it must not block in this callback while waiting for user confirmation).

Parameters

srv_pres	Server presence subscription instance. If application delays the acceptance of the request, it will need to specify this object when calling pjsua_pres_notify().
acc_id	Account ID most appropriate for this request.
buddy_id	ID of the buddy matching the sender of the request, if any, or PJSUA_INVALID_ID if no matching buddy is found.
from	The From URI of the request.
rdata	The incoming request.
code	The status code to respond to the request. The default value is 200. Application may set this to other final status code to accept or reject the request.
reason	The reason phrase to respond to the request.
msg_data	If the application wants to send additional headers in the response, it can put it in this parameter.

◆ on_srv_subscribe_state

void(* pjsua_callback::on_srv_subscribe_state) (pjsua_acc_id acc_id, pjsua_srv_pres *srv_pres, const pj_str_t *remote_uri, pjsip_evsub_state state, pjsip_event *event)

Notification when server side subscription state has changed. This callback is optional as application normally does not need to do anything to maintain server side presence subscription.

Parameters

acc_id	The account ID.
srv_pres	Server presence subscription object.
remote_uri	Remote URI string.
state	New subscription state.
event	PJSIP event that triggers the state change.

◆ on_buddy_state

void(* pjsua_callback::on_buddy_state) (pjsua_buddy_id buddy_id)

Notify application when the buddy state has changed. Application may then query the buddy into to get the details.

Parameters

buddy_id The buddy id.

◆ on_buddy_evsub_state

void(* pjsua_callback::on_buddy_evsub_state) (pjsua_buddy_id buddy_id, pjsip_evsub *sub, pjsip_event *event)

Notify application when the state of client subscription session associated with a buddy has changed. Application may use this callback to retrieve more detailed information about the state changed event.

Parameters

buddy_id	The buddy id.
sub	Event subscription session.
event	The event which triggers state change event.

◆ on_pager

void(* pjsua_callback::on_pager) (pjsua_call_id call_id, const pj_str_t *from, const pj_str_t *to, const pj_str_t *contact, const pj_str_t *mime_type, const pj_str_t *body)

Notify application on incoming pager (i.e. MESSAGE request). Argument call_id will be -1 if MESSAGE request is not related to an existing call.

See also on_pager2() callback for the version with pjsip_rx_data passed as one of the argument.

Parameters

call_id	Containts the ID of the call where the IM was sent, or PJSUA_INVALID_ID if the IM was sent outside call context.
from	URI of the sender.
to	URI of the destination message.
contact	The Contact URI of the sender, if present.
mime_type	MIME type of the message.
body	The message content.

◆ on_pager2

void(* pjsua_callback::on_pager2) (pjsua_call_id call_id, const pj_str_t *from, const pj_str_t *to, const pj_str_t *contact, const pj_str_t *mime_type, const pj_str_t *body, pjsip_rx_data *rdata, pjsua_acc_id acc_id)

This is the alternative version of the on_pager() callback with pjsip_rx_data argument.

Parameters

call_id	Containts the ID of the call where the IM was sent, or PJSUA_INVALID_ID if the IM was sent outside call context.
from	URI of the sender.
to	URI of the destination message.
contact	The Contact URI of the sender, if present.
mime_type	MIME type of the message.
body	The message content.
rdata	The incoming MESSAGE request.
acc_id	Account ID most suitable for this message.

◆ on_pager_status

void(* pjsua_callback::on_pager_status) (pjsua_call_id call_id, const pj_str_t *to, const pj_str_t *body, void *user_data, pjsip_status_code status, const pj_str_t *reason)

Notify application about the delivery status of outgoing pager request. See also on_pager_status2() callback for the version with pjsip_rx_data in the argument list.

Parameters

call_id	Containts the ID of the call where the IM was sent, or PJSUA_INVALID_ID if the IM was sent outside call context.
to	Destination URI.
body	Message body.
user_data	Arbitrary data that was specified when sending IM message.
status	Delivery status.
reason	Delivery status reason.

◆ on_pager_status2

void(* pjsua_callback::on_pager_status2) (pjsua_call_id call_id, const pj_str_t *to, const pj_str_t *body, void *user_data, pjsip_status_code status, const pj_str_t *reason, pjsip_tx_data *tdata, pjsip_rx_data *rdata, pjsua_acc_id acc_id)

Notify application about the delivery status of outgoing pager request.

Parameters

call_id	Containts the ID of the call where the IM was sent, or PJSUA_INVALID_ID if the IM was sent outside call context.
to	Destination URI.
body	Message body.
user_data	Arbitrary data that was specified when sending IM message.
status	Delivery status.
reason	Delivery status reason.
tdata	The original MESSAGE request.
rdata	The incoming MESSAGE response, or NULL if the message transaction fails because of time out or transport error.
acc_id	Account ID from this the instant message was send.

◆ on_typing

void(* pjsua_callback::on_typing) (pjsua_call_id call_id, const pj_str_t *from, const pj_str_t *to, const pj_str_t *contact, pj_bool_t is_typing)

Notify application about typing indication.

Parameters

call_id	Containts the ID of the call where the IM was sent, or PJSUA_INVALID_ID if the IM was sent outside call context.
from	URI of the sender.
to	URI of the destination message.
contact	The Contact URI of the sender, if present.
is_typing	Non-zero if peer is typing, or zero if peer has stopped typing a message.

◆ on_typing2

void(* pjsua_callback::on_typing2) (pjsua_call_id call_id, const pj_str_t *from, const pj_str_t *to, const pj_str_t *contact, pj_bool_t is_typing, pjsip_rx_data *rdata, pjsua_acc_id acc_id)

Notify application about typing indication.

Parameters

call_id	Containts the ID of the call where the IM was sent, or PJSUA_INVALID_ID if the IM was sent outside call context.
from	URI of the sender.
to	URI of the destination message.
contact	The Contact URI of the sender, if present.
is_typing	Non-zero if peer is typing, or zero if peer has stopped typing a message.
rdata	The received request.
acc_id	Account ID most suitable for this message.

◆ on_nat_detect

void(* pjsua_callback::on_nat_detect) (const pj_stun_nat_detect_result *res)

Callback when the library has finished performing NAT type detection.

Parameters

res	NAT detection result.

◆ on_call_redirected

pjsip_redirect_op(* pjsua_callback::on_call_redirected) (pjsua_call_id call_id, const pjsip_uri *target, const pjsip_event *e)

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. If this callback is not implemented, the default behavior is to NOT follow the redirection response.

Parameters

call_id	The call ID.
target	The current target to be tried.
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 NULL if this callback is called from within pjsua_call_process_redirect() context.

Returns

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 on_call_state() 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 pjsua_call_process_redirect() to either accept or reject the redirection upon getting user decision.

◆ on_mwi_state

void(* pjsua_callback::on_mwi_state) (pjsua_acc_id acc_id, pjsip_evsub *evsub)

This callback is called when message waiting indication subscription state has changed. Application can then query the subscription state by calling pjsip_evsub_get_state().

Parameters

acc_id	The account ID.
evsub	The subscription instance.

◆ on_mwi_info

void(* pjsua_callback::on_mwi_info) (pjsua_acc_id acc_id, pjsua_mwi_info *mwi_info)

This callback is called when a NOTIFY request for message summary / message waiting indication is received.

Parameters

acc_id	The account ID.
mwi_info	Structure containing details of the event, including the received NOTIFY request in the rdata field.

◆ on_transport_state

pjsip_tp_state_callback pjsua_callback::on_transport_state

This callback is called when transport state is changed. See also pjsip_tp_state_callback.

◆ on_call_media_transport_state

pjsua_med_tp_state_cb pjsua_callback::on_call_media_transport_state

This callback is called when media transport state is changed. See also pjsua_med_tp_state_cb.

◆ on_ice_transport_error

void(* pjsua_callback::on_ice_transport_error) (int index, pj_ice_strans_op op, pj_status_t status, void *param)

This callback is called to report error in ICE media transport. Currently it is used to report TURN Refresh error.

Parameters

index	Transport index.
op	Operation which trigger the failure.
status	Error status.
param	Additional info about the event. Currently this will always be set to NULL.

◆ on_snd_dev_operation

pj_status_t(* pjsua_callback::on_snd_dev_operation) (int operation)

Callback when the sound device is about to be opened or closed. This callback will be called even when null sound device or no sound device is configured by the application (i.e. the pjsua_set_null_snd_dev() and pjsua_set_no_snd_dev() APIs). Application can use the API pjsua_get_snd_dev() to get the info about which sound device is going to be opened/closed.

This callback is mostly useful when the application wants to manage the sound device by itself (i.e. with pjsua_set_no_snd_dev()), to get notified when it should open or close the sound device.

Parameters

operation The value will be set to 0 to signal that sound device is about to be closed, and 1 to be opened.

Returns: The callback must return PJ_SUCCESS at the moment.

◆ on_call_media_event

void(* pjsua_callback::on_call_media_event) (pjsua_call_id call_id, unsigned med_idx, pjmedia_event *event)

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

call_id	The call id.
med_idx	The media stream index.
event	The media event.

◆ on_create_media_transport

pjmedia_transport *(* pjsua_callback::on_create_media_transport) (pjsua_call_id call_id, unsigned media_idx, pjmedia_transport *base_tp, unsigned flags)

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 base_tp argument of this callback. Upon returning, the callback must return an instance of media transport to be used by the call.

Parameters

call_id	Call ID
media_idx	The media index in the SDP for which this media transport will be used.
base_tp	The media transport which otherwise will be used by the call has this callback not been implemented.
flags	Bitmask from pjsua_create_media_transport_flag.

Returns: The callback must return an instance of media transport to be used by the call.

◆ on_create_media_transport_srtp

void(* pjsua_callback::on_create_media_transport_srtp) (pjsua_call_id call_id, unsigned media_idx, pjmedia_srtp_setting *srtp_opt)

Warning: deprecated and may be removed in future release. Application can set SRTP crypto settings (including keys) and keying methods via pjsua_srtp_opt in pjsua_config and pjsua_acc_config. See also ticket #2100.

This callback is called before SRTP media transport is created. Application can modify the SRTP setting srtp_opt to specify the cryptos & keys and keying methods which are going to be used. Note that only some fields of pjmedia_srtp_setting can be overriden from this callback, i.e: "crypto_count", "crypto", "keying_count", "keying", and "use" (only for initial INVITE), any modification in other fields will be ignored.

Parameters

call_id	Call ID
media_idx	The media index in the SDP for which this SRTP media transport will be used.
srtp_opt	The SRTP setting. Application can modify this.

◆ on_acc_find_for_incoming

void(* pjsua_callback::on_acc_find_for_incoming) (const pjsip_rx_data *rdata, pjsua_acc_id *acc_id)

This callback can be used by application to override the account to be used to handle an incoming message. Initially, the account to be used will be calculated automatically by the library. This initial account will be used if application does not implement this callback, or application sets an invalid account upon returning from this callback.

Note that currently the incoming messages requiring account assignment are INVITE, MESSAGE, SUBSCRIBE, and unsolicited NOTIFY. This callback may be called before the callback of the SIP event itself, i.e: incoming call, pager, subscription, or unsolicited-event.

Parameters

rdata	The incoming message.
acc_id	On input, initial account ID calculated automatically by the library. On output, the account ID prefered by application to handle the incoming message.

◆ on_stun_resolution_complete

pj_stun_resolve_cb pjsua_callback::on_stun_resolution_complete

Calling pjsua_init() will initiate an async process to resolve and contact each of the STUN server entries to find which is usable. This callback is called when the process is complete, and can be used by the application to start creating and registering accounts. This way, the accounts can avoid call setup delay caused by pending STUN resolution.

◆ on_ip_change_progress

void(* pjsua_callback::on_ip_change_progress) (pjsua_ip_change_op op, pj_status_t status, const pjsua_ip_change_op_info *info)

Calling pjsua_handle_ip_change() may involve different operation. This callback is called to report the progress of each enabled operation.

Parameters

op	The operation.
status	The status of operation.
info	The info from the operation

◆ on_media_event

void(* pjsua_callback::on_media_event) (pjmedia_event *event)

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. If application needs to perform more complex tasks to handle the event, it should post the task to another thread.

Parameters

event The media event.

The documentation for this struct was generated from the following file:

pjsua-lib/pjsua.h

Data Fields

Detailed Description

Field Documentation

◆ on_call_state

◆ on_incoming_call

◆ on_call_tsx_state

◆ on_call_media_state

◆ on_call_sdp_created

◆ on_stream_precreate

◆ on_stream_created

◆ on_stream_created2

◆ on_stream_destroyed

◆ on_dtmf_digit

◆ on_dtmf_digit2

◆ on_dtmf_event

◆ on_call_transfer_request

◆ on_call_transfer_request2

◆ on_call_transfer_status

◆ on_call_replace_request

◆ on_call_replace_request2

◆ on_call_replaced

◆ on_call_rx_offer

◆ on_call_rx_reinvite

◆ on_call_tx_offer

◆ on_reg_started

◆ on_reg_started2

◆ on_reg_state

◆ on_reg_state2

◆ on_incoming_subscribe

◆ on_srv_subscribe_state

◆ on_buddy_state

◆ on_buddy_evsub_state

◆ on_pager

◆ on_pager2

◆ on_pager_status

◆ on_pager_status2

◆ on_typing

◆ on_typing2

◆ on_nat_detect

◆ on_call_redirected

◆ on_mwi_state

◆ on_mwi_info

◆ on_transport_state

◆ on_call_media_transport_state

◆ on_ice_transport_error

◆ on_snd_dev_operation

◆ on_call_media_event

◆ on_create_media_transport

◆ on_create_media_transport_srtp

◆ on_acc_find_for_incoming

◆ on_stun_resolution_complete

◆ on_ip_change_progress

◆ on_media_event