BLOG | DOCUMENTATION | TRAC

Home --> Documentations --> PJSIP Reference

#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_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_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_idThe call index.
eEvent 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_idThe account which match the incoming call.
call_idThe call id that has just been created for the call.
rdataThe 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_idCall identification.
tsxThe transaction which has changed state.
eTransaction 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_idThe 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_idThe call index.
sdpThe SDP has just been created.
poolThe pool instance, application should use this pool to modify the SDP.
rem_sdpThe remote SDP, will be NULL if local is SDP offerer.

◆ 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_idCall identification.
strmAudio media stream.
stream_idxStream index in the audio media session.
p_portOn 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_idCall identification.
paramThe 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_idCall identification.
strmAudio media stream.
stream_idxStream 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().

Parameters
call_idThe call index.
digitDTMF 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.

Parameters
call_idThe call index.
infoThe DTMF info.

◆ 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_idThe call index.
dstThe destination where the call will be transferred to.
codeStatus 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_idThe call index.
dstThe destination where the call will be transferred to.
codeStatus code to be returned for the call transfer request. On input, it contains status code 202.
optThe 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_idCall ID.
st_codeStatus progress of the transfer request.
st_textStatus progress text.
finalIf non-zero, no further notification will be reported. The st_code specified in this callback is the final status.
p_contInitially 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_idThe call ID to be replaced.
rdataThe incoming INVITE request to replace the call.
st_codeStatus code to be set by application. Application should only return a final status (200-699).
st_textOptional 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_idThe call ID to be replaced.
rdataThe incoming INVITE request to replace the call.
st_codeStatus code to be set by application. Application should only return a final status (200-699).
st_textOptional status text to be set by application.
optThe 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_idExisting call which to be replaced with the new call.
new_call_idThe new call.
rdataThe 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_idThe call index.
offerThe new offer received.
reservedReserved param, currently not used.
codeStatus code to be returned for answering the offer. On input, it contains status code 200. Currently, valid values are only 200 and 488.
optThe 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_idThe call index.
offerRemote offer.
rdataThe received re-INVITE request.
reservedReserved param, currently not used.
asyncOn input, it is PJ_FALSE. Set to PJ_TRUE if app wants to manually answer the re-INVITE.
codeStatus code to be returned for answering the offer. On input, it contains status code 200. Currently, valid values are only 200 and 488.
optThe 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_idThe call index.
reservedReserved param, currently not used.
optThe 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_idThe account ID.
renewNon-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_idThe account ID.
infoThe 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_idThe 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_idThe account ID.
infoThe 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_presServer presence subscription instance. If application delays the acceptance of the request, it will need to specify this object when calling pjsua_pres_notify().
acc_idAccount ID most appropriate for this request.
buddy_idID of the buddy matching the sender of the request, if any, or PJSUA_INVALID_ID if no matching buddy is found.
fromThe From URI of the request.
rdataThe incoming request.
codeThe 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.
reasonThe reason phrase to respond to the request.
msg_dataIf 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_idThe account ID.
srv_presServer presence subscription object.
remote_uriRemote URI string.
stateNew subscription state.
eventPJSIP 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_idThe 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_idThe buddy id.
subEvent subscription session.
eventThe 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_idContaints the ID of the call where the IM was sent, or PJSUA_INVALID_ID if the IM was sent outside call context.
fromURI of the sender.
toURI of the destination message.
contactThe Contact URI of the sender, if present.
mime_typeMIME type of the message.
bodyThe 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_idContaints the ID of the call where the IM was sent, or PJSUA_INVALID_ID if the IM was sent outside call context.
fromURI of the sender.
toURI of the destination message.
contactThe Contact URI of the sender, if present.
mime_typeMIME type of the message.
bodyThe message content.
rdataThe incoming MESSAGE request.
acc_idAccount 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_idContaints the ID of the call where the IM was sent, or PJSUA_INVALID_ID if the IM was sent outside call context.
toDestination URI.
bodyMessage body.
user_dataArbitrary data that was specified when sending IM message.
statusDelivery status.
reasonDelivery 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_idContaints the ID of the call where the IM was sent, or PJSUA_INVALID_ID if the IM was sent outside call context.
toDestination URI.
bodyMessage body.
user_dataArbitrary data that was specified when sending IM message.
statusDelivery status.
reasonDelivery status reason.
tdataThe original MESSAGE request.
rdataThe incoming MESSAGE response, or NULL if the message transaction fails because of time out or transport error.
acc_idAccount 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_idContaints the ID of the call where the IM was sent, or PJSUA_INVALID_ID if the IM was sent outside call context.
fromURI of the sender.
toURI of the destination message.
contactThe Contact URI of the sender, if present.
is_typingNon-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_idContaints the ID of the call where the IM was sent, or PJSUA_INVALID_ID if the IM was sent outside call context.
fromURI of the sender.
toURI of the destination message.
contactThe Contact URI of the sender, if present.
is_typingNon-zero if peer is typing, or zero if peer has stopped typing a message.
rdataThe received request.
acc_idAccount 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
resNAT 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_idThe call ID.
targetThe current target to be tried.
eThe 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_idThe account ID.
evsubThe 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_idThe account ID.
mwi_infoStructure 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
indexTransport index.
opOperation which trigger the failure.
statusError status.
paramAdditional 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
operationThe 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_idThe call id.
med_idxThe media stream index.
eventThe 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_idCall ID
media_idxThe media index in the SDP for which this media transport will be used.
base_tpThe media transport which otherwise will be used by the call has this callback not been implemented.
flagsBitmask 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_idCall ID
media_idxThe media index in the SDP for which this SRTP media transport will be used.
srtp_optThe 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
rdataThe incoming message.
acc_idOn 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.

See also pj_stun_resolve_cb.

◆ 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
opThe operation.
statusThe status of operation.
infoThe 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
eventThe media event.

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

 


PJSIP Open Source, high performance, small footprint, and very very portable SIP stack
Copyright (C) 2006-2008 Teluu Inc.