pjsua_callback Struct Reference
[PJSUA-API Basic API]

#include <pjsua.h>

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

Python Syntax:: This callback structure is embedded on pjsua_config structure.


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_stream_created )(pjsua_call_id call_id, pjmedia_session sess, unsigned stream_idx, pjmedia_port *p_port)
void(*	on_stream_destroyed )(pjsua_call_id call_id, pjmedia_session *sess, unsigned stream_idx)
void(*	on_dtmf_digit )(pjsua_call_id call_id, int digit)
void(*	on_call_transfer_request )(pjsua_call_id call_id, const pj_str_t dst, pjsip_status_code code)
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_replaced )(pjsua_call_id old_call_id, pjsua_call_id new_call_id)
void(*	on_reg_state )(pjsua_acc_id acc_id)
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_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)

Field Documentation

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

Notify application when invite 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.

Python Syntax:

     # call_id: integer
     # e:       an opaque object

     def on_call_state(call_id, e):
            return

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.

Python Syntax:

     # acc_id:  integer
     # call_id: integer
     # rdata:   an opaque object

     def on_incoming_call(acc_id, call_id, rdata):
            return

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.

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.

Parameters:

call_id

The call index.

Python Syntax:

     # call_id: integer

     def on_call_media_state(call_id):
            return

void(* pjsua_callback::on_stream_created)(pjsua_call_id call_id, pjmedia_session *sess, unsigned stream_idx, pjmedia_port **p_port)

Notify application when media session is created and before it is registered to the conference bridge. Application may return different 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.
	sess	Media session for the call.
	stream_idx	Stream index in the media session.
	p_port	On input, it specifies the media port of the stream. Application may modify this pointer to point to different media port to be registered to the conference bridge.

Python:: Not applicable.

void(* pjsua_callback::on_stream_destroyed)(pjsua_call_id call_id, pjmedia_session *sess, unsigned stream_idx)

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

Parameters:

	call_id	Call identification.
	sess	Media session for the call.
	stream_idx	Stream index in the media session.

Python:: Not applicable.

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

Notify application upon incoming DTMF digits.

Parameters:

	call_id	The call index.
	digit	DTMF ASCII digit.

Python Syntax:

     # call_id: integer
     # digit:   digit string

     def on_dtmf_digit(call_id, digit):
            return

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 transfered (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 transfered to.
	code	Status code to be returned for the call transfer request. On input, it contains status code 200.

Python Syntax:

     # call_id: integer
     # dst:     string
     # code:    integer

     def on_call_transfer_request(call_id, dst, code):
            return code

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

Python Syntax:

     # call_id: integer
     # st_code: integer
     # st_text: string
     # final:   integer
     # cont:    integer

     # return:  cont

     def on_call_transfer_status(call_id, st_code, st_text, final, cont):
            return cont

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.

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.

Python Syntax:

     # call_id: integer
     # rdata:   an opaque object
     # st_code: integer
     # st_text: string

     # return:  (st_code, st_text) tuple

     def on_call_replace_request(call_id, rdata, st_code, st_text):
            return st_code, st_text

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.

Python Syntax:

     # old_call_id: integer
     # new_call_id: integer

     def on_call_replaced(old_call_id, new_call_id):
            return

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

Account ID.

Python Syntax:

     # acc_id:  account ID (integer)

     def on_reg_state(acc_id):
            return

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, and later calls pjsua_pres_notify() 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.

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.

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.

Python Syntax:

     # buddy_id:    integer

     def on_buddy_state(buddy_id):
            return

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.

Python Syntax:

     # call_id:     integer
     # from:        string
     # to:          string
     # contact:     string
     # mime_type:   string
     # body:        string
     # acc_id:      integer

     def on_pager(call_id, from, to, contact, mime_type, body):
            return

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.

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.

Python Syntax

     # call_id:     integer
     # to:          string
     # body:        string
     # user_data:   string
     # status:      integer
     # reason:      string
     # acc_id:      integer

     def on_pager_status(call_id, to, body, user_data, status, reason):
            return

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.

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.

Python Syntax

     # call_id:     string
     # from:        string
     # to:          string
     # contact:     string
     # is_typing:   integer

     def on_typing(call_id, from, to, contact, is_typing):
            return

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.

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.

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

pjsua.h

pjsua_callback Struct Reference [PJSUA-API Basic API]

Detailed Description

Data Fields

Field Documentation

pjsua_callback Struct Reference
[PJSUA-API Basic API]