WARNING: The online documentation has moved to https://docs.pjsip.org.

Visit the new documentation at https://docs.pjsip.org:

BLOG | DOCUMENTATION | GITHUB

Home --> Documentations --> PJSIP Reference

pjsip_inv_callback Struct Reference

#include <sip_inv.h>

Data Fields

void(* on_state_changed )(pjsip_inv_session *inv, pjsip_event *e)
 
void(* on_new_session )(pjsip_inv_session *inv, pjsip_event *e)
 
void(* on_tsx_state_changed )(pjsip_inv_session *inv, pjsip_transaction *tsx, pjsip_event *e)
 
void(* on_rx_offer )(pjsip_inv_session *inv, const pjmedia_sdp_session *offer)
 
void(* on_rx_offer2 )(pjsip_inv_session *inv, struct pjsip_inv_on_rx_offer_cb_param *param)
 
pj_status_t(* on_rx_reinvite )(pjsip_inv_session *inv, const pjmedia_sdp_session *offer, pjsip_rx_data *rdata)
 
void(* on_create_offer )(pjsip_inv_session *inv, pjmedia_sdp_session **p_offer)
 
void(* on_media_update )(pjsip_inv_session *inv_ses, pj_status_t status)
 
void(* on_send_ack )(pjsip_inv_session *inv, pjsip_rx_data *rdata)
 
pjsip_redirect_op(* on_redirected )(pjsip_inv_session *inv, const pjsip_uri *target, const pjsip_event *e)
 

Detailed Description

This structure contains callbacks to be registered by application to receive notifications from the framework about various events in the invite session.

Field Documentation

◆ on_state_changed

void(* pjsip_inv_callback::on_state_changed) (pjsip_inv_session *inv, pjsip_event *e)

This callback is called when the invite sesion state has changed. Application should inspect the session state (inv_sess->state) to get the current state of the session.

This callback is mandatory.

Parameters
invThe invite session.
eThe event which has caused the invite session's state to change.

◆ on_new_session

void(* pjsip_inv_callback::on_new_session) (pjsip_inv_session *inv, pjsip_event *e)

This callback is called when the invite usage module has created a new dialog and invite because of forked outgoing request.

Currently the invite session does not create a new dialog in forking scenario, so this callback will never be invoked.

Parameters
invThe new invite session.
eThe event which has caused the dialog to fork. The type of this event can be either PJSIP_EVENT_RX_MSG or PJSIP_EVENT_RX_200_MSG.

◆ on_tsx_state_changed

void(* pjsip_inv_callback::on_tsx_state_changed) (pjsip_inv_session *inv, pjsip_transaction *tsx, pjsip_event *e)

This callback is called whenever any transactions within the session has changed their state. Application MAY implement this callback, e.g. to monitor the progress of an outgoing request, or to send response to unhandled incoming request (such as INFO).

This callback is optional.

Parameters
invThe invite session.
tsxThe transaction, which state has changed.
eThe event which has caused the transation state's to change.

◆ on_rx_offer

void(* pjsip_inv_callback::on_rx_offer) (pjsip_inv_session *inv, const pjmedia_sdp_session *offer)

This callback is called when the invite session has received new offer from peer. Application can inspect the remote offer in "offer", and set the SDP answer with pjsip_inv_set_sdp_answer(). When the application sends a SIP message to send the answer, this SDP answer will be negotiated with the offer, and the result will be sent with the SIP message.

Note: if callback on_rx_offer2() is implemented, this callback will not be called.

Parameters
invThe invite session.
offerRemote offer.

◆ on_rx_offer2

void(* pjsip_inv_callback::on_rx_offer2) (pjsip_inv_session *inv, struct pjsip_inv_on_rx_offer_cb_param *param)

This callback is called when the invite session has received new offer from peer. Variant of on_rx_offer() callback.

Parameters
invThe invite session.
paramThe callback parameters.

◆ on_rx_reinvite

pj_status_t(* pjsip_inv_callback::on_rx_reinvite) (pjsip_inv_session *inv, const pjmedia_sdp_session *offer, pjsip_rx_data *rdata)

This callback is optional, and is called when the invite session has received a re-INVITE from the peer. It will be called after on_rx_offer() callback and works only for re-INVITEs. It allows more fine-grained control over the response to a re-INVITE, e.g. sending a provisional response first. Application can return PJ_SUCCESS and send a reply using the function pjsip_inv_initial_answer() or pjsip_inv_answer(), as with the initial INVITE. If application returns non-PJ_SUCCESS, it needs to set the SDP answer with pjsip_inv_set_sdp_answer() and the re-INVITE will be answered automatically.

Remarks: Application may need to monitor on_tsx_state_changed() callback to check whether the re-INVITE is already answered automatically with 487 due to being cancelled.

Parameters
invThe invite session.
offerRemote offer.
rdataThe received re-INVITE request.
Returns
- PJ_SUCCESS: application will answer the re-INVITE manually

◆ on_create_offer

void(* pjsip_inv_callback::on_create_offer) (pjsip_inv_session *inv, pjmedia_sdp_session **p_offer)

This callback is optional, and it is used to ask the application to create a fresh offer, when the invite session has received re-INVITE without offer. This offer then will be sent in the 200/OK response to the re-INVITE request.

If application doesn't implement this callback, the invite session will send the currently active SDP as the offer.

Parameters
invThe invite session.
p_offerPointer to receive the SDP offer created by application.

◆ on_media_update

void(* pjsip_inv_callback::on_media_update) (pjsip_inv_session *inv_ses, pj_status_t status)

This callback is called after SDP offer/answer session has completed. The status argument specifies the status of the offer/answer, as returned by pjmedia_sdp_neg_negotiate().

This callback is optional (from the point of view of the framework), but all useful applications normally need to implement this callback.

Parameters
invThe invite session.
statusThe negotiation status.

◆ on_send_ack

void(* pjsip_inv_callback::on_send_ack) (pjsip_inv_session *inv, pjsip_rx_data *rdata)

This callback is called when the framework needs to send ACK request after it receives incoming 2xx response for INVITE. It allows application to manually handle the transmission of ACK request, which is required by some 3PCC scenarios. If this callback is not implemented, the framework will handle the ACK transmission automatically.

When this callback is overridden, application may delay the sending of the ACK request (for example, when it needs to wait for answer from the other call leg, in 3PCC scenarios).

Application MUST create the ACK request using pjsip_inv_create_ack() and send it using pjsip_inv_send_msg().

Once it has sent the ACK request, the framework will keep this ACK request in the cache. Subsequent receipt of 2xx response will not cause this callback to be called (but see exception below), and instead automatic retransmission of this ACK request from the cache will be done by the framework. Exception: if app has created the ACK but has not sent it, while it receives a retransmission of 2xx response, this callback will be called again.

This callback is optional.

◆ on_redirected

pjsip_redirect_op(* pjsip_inv_callback::on_redirected) (pjsip_inv_session *inv, const pjsip_uri *target, const pjsip_event *e)

This callback is called when the session 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 (the default behavior if this callback is implemented), 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
invThe invite session.
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 pjsip_inv_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 to this target. When set, the session will immediately resend INVITE request to the target after this callback returns.
  • PJSIP_REDIRECT_REJECT: immediately reject this target. The session 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_state_changed() 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 pjsip_inv_process_redirect() to either accept or reject the redirection upon getting user decision.

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.