pjsip_inv_callback Struct Reference
[INVITE Session]

#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_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 receieve notifications from the framework about various events in the invite session.

---

Field Documentation

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:

	inv	The invite session.
	e	The event which has caused the invite session's state to change.

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.

This callback is mandatory.

Parameters:

	inv	The new invite session.
	e	The 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.

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:

	inv	The invite session.
	tsx	The transaction, which state has changed.
	e	The event which has caused the transation state's to change.

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.

Parameters:

	inv	The invite session.
	offer	Remote 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:

	inv	The invite session.
	p_offer	Pointer to receive the SDP offer created by application.

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:

	inv	The invite session.
	status	The negotiation status.

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 creates the ACK request

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, and instead automatic retransmission of this ACK request from the cache will be done by the framework.

This callback is optional.

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:

	inv	The invite session.
	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 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:

• sip_inv.h