PJSUA-API Calls Management
[PJSUA API - High Level Softphone API for C/C++ and Python]

Detailed Description

Define Documentation

#define PJSUA_MAX_CALLS 32

Maximum simultaneous calls.

#define PJSUA_XFER_NO_REQUIRE_REPLACES 1

Flag to indicate that "Require: replaces" should not be put in the outgoing INVITE request caused by REFER request created by pjsua_call_xfer_replaces().

Enumeration Type Documentation

enum pjsua_call_media_status

This enumeration specifies the media status of a call, and it's part of pjsua_call_info structure.

Enumerator:

PJSUA_CALL_MEDIA_NONE	Call currently has no media
PJSUA_CALL_MEDIA_ACTIVE	The media is active
PJSUA_CALL_MEDIA_LOCAL_HOLD	The media is currently put on hold by local endpoint
PJSUA_CALL_MEDIA_REMOTE_HOLD	The media is currently put on hold by remote endpoint
PJSUA_CALL_MEDIA_ERROR	The media has reported error (e.g. ICE negotiation)

Function Documentation

unsigned pjsua_call_get_max_count ( void )

Get maximum number of calls configured in pjsua.

Returns:: Maximum number of calls configured.

Python:

    count = py_pjsua.call_get_max_count()

unsigned pjsua_call_get_count ( void )

Get number of currently active calls.

Returns:: Number of currently active calls.

Python:

    count = py_pjsua.call_get_count()

pj_status_t pjsua_enum_calls	(	pjsua_call_id	ids[],
		unsigned *	count
	)

Enumerate all active calls. Application may then query the information and state of each call by calling pjsua_call_get_info().

Parameters:

	ids	Array of account IDs to be initialized.
	count	In input, specifies the maximum number of elements. On return, it contains the actual number of elements.

Returns:: PJ_SUCCESS on success, or the appropriate error code.

Python:

This function takes no argument and return list of call Ids.

    [call_ids] = py_pjsua.enum_calls()

pj_status_t pjsua_call_make_call	(	pjsua_acc_id	acc_id,
		const pj_str_t *	dst_uri,
		unsigned	options,
		void *	user_data,
		const pjsua_msg_data *	msg_data,
		pjsua_call_id *	p_call_id
	)

Make outgoing call to the specified URI using the specified account.

Parameters:

	acc_id	The account to be used.
	dst_uri	URI to be put in the To header (normally is the same as the target URI).
	options	Options (must be zero at the moment).
	user_data	Arbitrary user data to be attached to the call, and can be retrieved later.
	msg_data	Optional headers etc to be added to outgoing INVITE request, or NULL if no custom header is desired.
	p_call_id	Pointer to receive call identification.

Returns:: PJ_SUCCESS on success, or the appropriate error code.

Python:

The Python function returns (status, call_id) tuple:

    status, call_id = py_pjsua.call_make_call(acc_id, dst_uri, options, 
                                              user_data, msg_data)

Note: the user_data in Python function is an integer, and the msg_data can be set to None if not required.

pj_bool_t pjsua_call_is_active ( pjsua_call_id call_id )

Check if the specified call has active INVITE session and the INVITE session has not been disconnected.

Parameters:

call_id

Call identification.

Returns:: Non-zero if call is active.

Python:

    bool = py_pjsua.call_is_active(call_id)

pj_bool_t pjsua_call_has_media ( pjsua_call_id call_id )

Check if call has an active media session.

Parameters:

call_id

Call identification.

Returns:: Non-zero if yes.

Python:

    bool = py_pjsua.call_has_media(call_id)

pjsua_conf_port_id pjsua_call_get_conf_port ( pjsua_call_id call_id )

Get the conference port identification associated with the call.

Parameters:

call_id

Call identification.

Returns:: Conference port ID, or PJSUA_INVALID_ID when the media has not been established or is not active.

Python:

    slot = py_pjsua.call_get_conf_port(call_id)

pj_status_t pjsua_call_get_info	(	pjsua_call_id	call_id,
		pjsua_call_info *	info
	)

Obtain detail information about the specified call.

Parameters:

	call_id	Call identification.
	info	Call info to be initialized.

Returns:: PJ_SUCCESS on success, or the appropriate error code.

Python:

    call_info = py_pjsua.call_get_info(call_id)

call_info return value will be set to None if call_id is not valid.

pj_status_t pjsua_call_set_user_data	(	pjsua_call_id	call_id,
		void *	user_data
	)

Attach application specific data to the call. Application can then inspect this data by calling pjsua_call_get_user_data().

Parameters:

	call_id	Call identification.
	user_data	Arbitrary data to be attached to the call.

Returns:: The user data.

Python:

    status = py_pjsua.call_set_user_data(call_id, user_data)

The user_data is an integer in the Python function.

void* pjsua_call_get_user_data ( pjsua_call_id call_id )

Get user data attached to the call, which has been previously set with pjsua_call_set_user_data().

Parameters:

call_id

Call identification.

Returns:: The user data.

Python:

    user_data = py_pjsua.call_get_user_data(call_id)

The user_data is an integer.

pj_status_t pjsua_call_get_rem_nat_type	(	pjsua_call_id	call_id,
		pj_stun_nat_type *	p_type
	)

Get the NAT type of remote's endpoint. This is a proprietary feature of PJSUA-LIB which sends its NAT type in the SDP when nat_type_in_sdp is set in pjsua_config.

This function can only be called after SDP has been received from remote, which means for incoming call, this function can be called as soon as call is received as long as incoming call contains SDP, and for outgoing call, this function can be called only after SDP is received (normally in 200/OK response to INVITE). As a general case, application should call this function after or in on_call_media_state() callback.

Parameters:

	call_id	Call identification.
	p_type	Pointer to store the NAT type. Application can then retrieve the string description of the NAT type by calling pj_stun_get_nat_name().

Returns:: PJ_SUCCESS on success.

See also:: pjsua_get_nat_type(), nat_type_in_sdp

pj_status_t pjsua_call_answer	(	pjsua_call_id	call_id,
		unsigned	code,
		const pj_str_t *	reason,
		const pjsua_msg_data *	msg_data
	)

Send response to incoming INVITE request. Depending on the status code specified as parameter, this function may send provisional response, establish the call, or terminate the call.

Parameters:

	call_id	Incoming call identification.
	code	Status code, (100-699).
	reason	Optional reason phrase. If NULL, default text will be used.
	msg_data	Optional list of headers etc to be added to outgoing response message.

Returns:: PJ_SUCCESS on success, or the appropriate error code.

Python:

    status = py_pjsua.call_answer(call_id, code, reason, msg_data)

Arguments reason and msg_data may be set to None if not required.

pj_status_t pjsua_call_hangup	(	pjsua_call_id	call_id,
		unsigned	code,
		const pj_str_t *	reason,
		const pjsua_msg_data *	msg_data
	)

Hangup call by using method that is appropriate according to the call state. This function is different than answering the call with 3xx-6xx response (with pjsua_call_answer()), in that this function will hangup the call regardless of the state and role of the call, while pjsua_call_answer() only works with incoming calls on EARLY state.

Parameters:

	call_id	Call identification.
	code	Optional status code to be sent when we're rejecting incoming call. If the value is zero, "603/Decline" will be sent.
	reason	Optional reason phrase to be sent when we're rejecting incoming call. If NULL, default text will be used.
	msg_data	Optional list of headers etc to be added to outgoing request/response message.

Returns:: PJ_SUCCESS on success, or the appropriate error code.

Python:

    status = py_pjsua.call_hangup(call_id, code, reason, msg_data)

Arguments reason and msg_data may be set to None if not required.

pj_status_t pjsua_call_set_hold	(	pjsua_call_id	call_id,
		const pjsua_msg_data *	msg_data
	)

Put the specified call on hold. This will send re-INVITE with the appropriate SDP to inform remote that the call is being put on hold. The final status of the request itself will be reported on the on_call_media_state() callback, which inform the application that the media state of the call has changed.

Parameters:

	call_id	Call identification.
	msg_data	Optional message components to be sent with the request.

Returns:: PJ_SUCCESS on success, or the appropriate error code.

Python:

    status = py_pjsua.call_set_hold(call_id, msg_data)

Argument msg_data may be set to None if not required.

pj_status_t pjsua_call_reinvite	(	pjsua_call_id	call_id,
		pj_bool_t	unhold,
		const pjsua_msg_data *	msg_data
	)

Send re-INVITE to release hold. The final status of the request itself will be reported on the on_call_media_state() callback, which inform the application that the media state of the call has changed.

Parameters:

	call_id	Call identification.
	unhold	If this argument is non-zero and the call is locally held, this will release the local hold.
	msg_data	Optional message components to be sent with the request.

Returns:: PJ_SUCCESS on success, or the appropriate error code.

Python:

    status = py_pjsua.call_reinvite(call_id, unhold, msg_data)

Argument msg_data may be set to None if not required.

pj_status_t pjsua_call_update	(	pjsua_call_id	call_id,
		unsigned	options,
		const pjsua_msg_data *	msg_data
	)

Send UPDATE request.

Parameters:

	call_id	Call identification.
	options	Must be zero for now.
	msg_data	Optional message components to be sent with the request.

Returns:: PJ_SUCCESS on success, or the appropriate error code.

pj_status_t pjsua_call_xfer	(	pjsua_call_id	call_id,
		const pj_str_t *	dest,
		const pjsua_msg_data *	msg_data
	)

Initiate call transfer to the specified address. This function will send REFER request to instruct remote call party to initiate a new INVITE session to the specified destination/target.

If application is interested to monitor the successfulness and the progress of the transfer request, it can implement on_call_transfer_status() callback which will report the progress of the call transfer request.

Parameters:

	call_id	The call id to be transfered.
	dest	Address of new target to be contacted.
	msg_data	Optional message components to be sent with the request.

Returns:: PJ_SUCCESS on success, or the appropriate error code.

Python:

    status = py_pjsua.call_xfer(call_id, dest, msg_data)

Argument msg_data may be set to None if not required.

pj_status_t pjsua_call_xfer_replaces	(	pjsua_call_id	call_id,
		pjsua_call_id	dest_call_id,
		unsigned	options,
		const pjsua_msg_data *	msg_data
	)

Initiate attended call transfer. This function will send REFER request to instruct remote call party to initiate new INVITE session to the URL of dest_call_id. The party at dest_call_id then should "replace" the call with us with the new call from the REFER recipient.

Parameters:

	call_id	The call id to be transfered.
	dest_call_id	The call id to be replaced.
	options	Application may specify PJSUA_XFER_NO_REQUIRE_REPLACES to suppress the inclusion of "Require: replaces" in the outgoing INVITE request created by the REFER request.
	msg_data	Optional message components to be sent with the request.

Returns:: PJ_SUCCESS on success, or the appropriate error code.

Python:

    status = py_pjsua.call_xfer_replaces(call_id, dest_call_id, options, msg_data)

Argument msg_data may be set to None if not required.

pj_status_t pjsua_call_dial_dtmf	(	pjsua_call_id	call_id,
		const pj_str_t *	digits
	)

Send DTMF digits to remote using RFC 2833 payload formats.

Parameters:

	call_id	Call identification.
	digits	DTMF string digits to be sent.

Returns:: PJ_SUCCESS on success, or the appropriate error code.

Python:

    status = py_pjsua.call_dial_dtmf(call_id, digits)

pj_status_t pjsua_call_send_im	(	pjsua_call_id	call_id,
		const pj_str_t *	mime_type,
		const pj_str_t *	content,
		const pjsua_msg_data *	msg_data,
		void *	user_data
	)

Send instant messaging inside INVITE session.

Parameters:

	call_id	Call identification.
	mime_type	Optional MIME type. If NULL, then "text/plain" is assumed.
	content	The message content.
	msg_data	Optional list of headers etc to be included in outgoing request. The body descriptor in the msg_data is ignored.
	user_data	Optional user data, which will be given back when the IM callback is called.

Returns:: PJ_SUCCESS on success, or the appropriate error code.

Python:

    status = py_pjsua.call_send_im(call_id, mime_type, content, msg_data, user_data)

Note that the user_data argument is an integer in Python.

pj_status_t pjsua_call_send_typing_ind	(	pjsua_call_id	call_id,
		pj_bool_t	is_typing,
		const pjsua_msg_data *	msg_data
	)

Send IM typing indication inside INVITE session.

Parameters:

	call_id	Call identification.
	is_typing	Non-zero to indicate to remote that local person is currently typing an IM.
	msg_data	Optional list of headers etc to be included in outgoing request.

Returns:: PJ_SUCCESS on success, or the appropriate error code.

Python:

    status = py_pjsua.call_send_typing_ind(call_id, is_typing, msg_data)

Argument msg_data may be set to None if not required.

pj_status_t pjsua_call_send_request	(	pjsua_call_id	call_id,
		const pj_str_t *	method,
		const pjsua_msg_data *	msg_data
	)

Send arbitrary request with the call. This is useful for example to send INFO request. Note that application should not use this function to send requests which would change the invite session's state, such as re-INVITE, UPDATE, PRACK, and BYE.

Parameters:

	call_id	Call identification.
	method	SIP method of the request.
	msg_data	Optional message body and/or list of headers to be included in outgoing request.

Returns:: PJ_SUCCESS on success, or the appropriate error code.

void pjsua_call_hangup_all ( void )

Terminate all calls. This will initiate pjsua_call_hangup() for all currently active calls.

Python:

    py_pjsua.call_hangup_all()

pj_status_t pjsua_call_dump	(	pjsua_call_id	call_id,
		pj_bool_t	with_media,
		char *	buffer,
		unsigned	maxlen,
		const char *	indent
	)

Dump call and media statistics to string.

Parameters:

	call_id	Call identification.
	with_media	Non-zero to include media information too.
	buffer	Buffer where the statistics are to be written to.
	maxlen	Maximum length of buffer.
	indent	Spaces for left indentation.

Returns:: PJ_SUCCESS on success.

Python:

    string = py_pjsua.call_dump(call_id, with_media, max_len, indent)

The max_len argument is the desired maximum length to be allocated.

PJSUA-API Calls Management [PJSUA API - High Level Softphone API for C/C++ and Python]

Detailed Description

Data Structures

Defines

Enumerations

Functions

Define Documentation

Enumeration Type Documentation

Function Documentation

PJSUA-API Calls Management
[PJSUA API - High Level Softphone API for C/C++ and Python]