Endpoint

The master, owner of all objects. More...

Data Structures
struct	pjsip_process_rdata_param

Typedefs
typedef void(*	pjsip_endpt_exit_callback) (pjsip_endpoint *endpt)

Functions
pj_status_t	pjsip_endpt_create (pj_pool_factory *pf, const char *name, pjsip_endpoint **endpt)
void	pjsip_endpt_destroy (pjsip_endpoint *endpt)
const pj_str_t *	pjsip_endpt_name (const pjsip_endpoint *endpt)
pj_status_t	pjsip_endpt_handle_events (pjsip_endpoint *endpt, const pj_time_val *max_timeout)
pj_status_t	pjsip_endpt_handle_events2 (pjsip_endpoint *endpt, const pj_time_val *max_timeout, unsigned *count)
pj_status_t	pjsip_endpt_schedule_timer (pjsip_endpoint *endpt, pj_timer_entry *entry, const pj_time_val *delay)
pj_status_t	pjsip_endpt_schedule_timer_w_grp_lock (pjsip_endpoint *endpt, pj_timer_entry *entry, const pj_time_val *delay, int id_val, pj_grp_lock_t *grp_lock)
void	pjsip_endpt_cancel_timer (pjsip_endpoint *endpt, pj_timer_entry *entry)
pj_timer_heap_t *	pjsip_endpt_get_timer_heap (pjsip_endpoint *endpt)
pj_status_t	pjsip_endpt_register_module (pjsip_endpoint *endpt, pjsip_module *module)
pj_status_t	pjsip_endpt_unregister_module (pjsip_endpoint *endpt, pjsip_module *module)
void	pjsip_process_rdata_param_default (pjsip_process_rdata_param *p)
pj_status_t	pjsip_endpt_process_rx_data (pjsip_endpoint *endpt, pjsip_rx_data *rdata, pjsip_process_rdata_param *p, pj_bool_t *p_handled)
pj_pool_t *	pjsip_endpt_create_pool (pjsip_endpoint *endpt, const char *pool_name, pj_size_t initial, pj_size_t increment)
void	pjsip_endpt_release_pool (pjsip_endpoint *endpt, pj_pool_t *pool)
pjsip_transaction *	pjsip_endpt_find_tsx (pjsip_endpoint *endpt, const pj_str_t *key)
void	pjsip_endpt_register_tsx (pjsip_endpoint *endpt, pjsip_transaction *tsx)
void	pjsip_endpt_destroy_tsx (pjsip_endpoint *endpt, pjsip_transaction *tsx)
pj_status_t	pjsip_endpt_create_tdata (pjsip_endpoint *endpt, pjsip_tx_data **p_tdata)
pj_status_t	pjsip_endpt_create_resolver (pjsip_endpoint *endpt, pj_dns_resolver **p_resv)
pj_status_t	pjsip_endpt_set_resolver (pjsip_endpoint *endpt, pj_dns_resolver *resv)
pj_status_t	pjsip_endpt_set_ext_resolver (pjsip_endpoint *endpt, pjsip_ext_resolver *ext_res)
pj_dns_resolver *	pjsip_endpt_get_resolver (pjsip_endpoint *endpt)
void	pjsip_endpt_resolve (pjsip_endpoint *endpt, pj_pool_t *pool, pjsip_host_info *target, void *token, pjsip_resolver_callback *cb)
pjsip_tpmgr *	pjsip_endpt_get_tpmgr (pjsip_endpoint *endpt)
pj_ioqueue_t *	pjsip_endpt_get_ioqueue (pjsip_endpoint *endpt)
pj_status_t	pjsip_endpt_acquire_transport (pjsip_endpoint *endpt, pjsip_transport_type_e type, const pj_sockaddr_t *remote, int addr_len, const pjsip_tpselector *sel, pjsip_transport **p_tp)
pj_status_t	pjsip_endpt_acquire_transport2 (pjsip_endpoint *endpt, pjsip_transport_type_e type, const pj_sockaddr_t *remote, int addr_len, const pjsip_tpselector *sel, pjsip_tx_data *tdata, pjsip_transport **p_tp)
const pjsip_hdr *	pjsip_endpt_get_capability (pjsip_endpoint *endpt, int htype, const pj_str_t *hname)
pj_bool_t	pjsip_endpt_has_capability (pjsip_endpoint *endpt, int htype, const pj_str_t *hname, const pj_str_t *token)
pj_status_t	pjsip_endpt_add_capability (pjsip_endpoint *endpt, pjsip_module *mod, int htype, const pj_str_t *hname, unsigned count, const pj_str_t tags[])
const pjsip_hdr *	pjsip_endpt_get_request_headers (pjsip_endpoint *e)
void	pjsip_endpt_dump (pjsip_endpoint *endpt, pj_bool_t detail)
pj_status_t	pjsip_endpt_atexit (pjsip_endpoint *endpt, pjsip_endpt_exit_callback func)

Detailed Description

SIP Endpoint instance (pjsip_endpoint) can be viewed as the master/owner of all SIP objects in an application. It performs the following roles:

• it manages the allocation/deallocation of memory pools for all objects.
• it manages listeners and transports, and how they are used by transactions.
• it receives incoming messages from transport layer and automatically dispatches them to the correct transaction (or create a new one).
• it has a single instance of timer management (timer heap).
• it manages modules, which is the primary means of extending the library.
• it provides single polling function for all objects and distributes events.
• it automatically handles incoming requests which can not be handled by existing modules (such as when incoming request has unsupported method).
• and so on..

Application should only instantiate one SIP endpoint instance for every process.

Typedef Documentation

pjsip_endpt_exit_callback

typedef void(* pjsip_endpt_exit_callback) (pjsip_endpoint *endpt)

Type of callback to register to pjsip_endpt_atexit().

Function Documentation

pjsip_endpt_create()

pj_status_t pjsip_endpt_create	(	pj_pool_factory *	pf,
		const char *	name,
		pjsip_endpoint **	endpt
	)

Create an instance of SIP endpoint from the specified pool factory. The pool factory reference then will be kept by the endpoint, so that future memory allocations by SIP components will be taken from the same pool factory.

Parameters

pf	Pool factory that will be used for the lifetime of endpoint.
name	Optional name to be specified for the endpoint. If this parameter is NULL, then the name will use local host name.
endpt	Pointer to receive endpoint instance.

Returns

PJ_SUCCESS on success.

pjsip_endpt_destroy()

void pjsip_endpt_destroy

(

pjsip_endpoint *

endpt

)

Destroy endpoint instance. Application must make sure that all pending transactions have been terminated properly, because this function does not check for the presence of pending transactions.

Parameters

endpt

The SIP endpoint to be destroyed.

pjsip_endpt_name()

const pj_str_t * pjsip_endpt_name

(

const pjsip_endpoint *

endpt

)

Get endpoint name.

Parameters

endpt

The SIP endpoint instance.

Returns

Endpoint name, as was registered during endpoint creation. The string is NULL terminated.

pjsip_endpt_handle_events()

pj_status_t pjsip_endpt_handle_events	(	pjsip_endpoint *	endpt,
		const pj_time_val *	max_timeout
	)

Poll for events. Application must call this function periodically to ensure that all events from both transports and timer heap are handled in timely manner. This function, like all other endpoint functions, is thread safe, and application may have more than one thread concurrently calling this function.

Parameters

endpt	The endpoint.
max_timeout	Maximum time to wait for events, or NULL to wait forever until event is received.

Returns

PJ_SUCCESS on success.

pjsip_endpt_handle_events2()

pj_status_t pjsip_endpt_handle_events2	(	pjsip_endpoint *	endpt,
		const pj_time_val *	max_timeout,
		unsigned *	count
	)

Handle events with additional info about number of events that have been handled.

Parameters

endpt	The endpoint.
max_timeout	Maximum time to wait for events, or NULL to wait forever until event is received.
count	Optional argument to receive the number of events that have been handled by the function.

Returns

PJ_SUCCESS on success.

pjsip_endpt_schedule_timer()

pj_status_t pjsip_endpt_schedule_timer	(	pjsip_endpoint *	endpt,
		pj_timer_entry *	entry,
		const pj_time_val *	delay
	)

Schedule timer to endpoint's timer heap. Application must poll the endpoint periodically (by calling pjsip_endpt_handle_events) to ensure that the timer events are handled in timely manner. When the timeout for the timer has elapsed, the callback specified in the entry argument will be called. This function, like all other endpoint functions, is thread safe.

Parameters

endpt	The endpoint.
entry	The timer entry.
delay	The relative delay of the timer.

Returns

PJ_OK (zero) if successfull.

pjsip_endpt_schedule_timer_w_grp_lock()

pj_status_t pjsip_endpt_schedule_timer_w_grp_lock	(	pjsip_endpoint *	endpt,
		pj_timer_entry *	entry,
		const pj_time_val *	delay,
		int	id_val,
		pj_grp_lock_t *	grp_lock
	)

Schedule timer to endpoint's timer heap with group lock. Application must poll the endpoint periodically (by calling pjsip_endpt_handle_events) to ensure that the timer events are handled in timely manner. When the timeout for the timer has elapsed, the callback specified in the entry argument will be called. This function, like all other endpoint functions, is thread safe.

Parameters

endpt	The endpoint.
entry	The timer entry.
delay	The relative delay of the timer.
id_val	The value to be set to the "id" field of the timer entry once the timer is scheduled.
grp_lock	The group lock.

Returns

PJ_OK (zero) if successfull.

pjsip_endpt_cancel_timer()

void pjsip_endpt_cancel_timer	(	pjsip_endpoint *	endpt,
		pj_timer_entry *	entry
	)

Cancel the previously registered timer. This function, like all other endpoint functions, is thread safe.

Parameters

endpt	The endpoint.
entry	The timer entry previously registered.

pjsip_endpt_get_timer_heap()

pj_timer_heap_t * pjsip_endpt_get_timer_heap

(

pjsip_endpoint *

endpt

)

Get the timer heap instance of the SIP endpoint.

Parameters

endpt

The endpoint.

Returns

The timer heap instance.

pjsip_endpt_register_module()

pj_status_t pjsip_endpt_register_module	(	pjsip_endpoint *	endpt,
		pjsip_module *	module
	)

Register new module to the endpoint. The endpoint will then call the load and start function in the module to properly initialize the module, and assign a unique module ID for the module.

Parameters

endpt	The endpoint.
module	The module to be registered.

Returns

PJ_SUCCESS on success.

pjsip_endpt_unregister_module()

pj_status_t pjsip_endpt_unregister_module	(	pjsip_endpoint *	endpt,
		pjsip_module *	module
	)

Unregister a module from the endpoint. The endpoint will then call the stop and unload function in the module to properly shutdown the module.

Parameters

endpt	The endpoint.
module	The module to be registered.

Returns

PJ_SUCCESS on success.

pjsip_process_rdata_param_default()

void pjsip_process_rdata_param_default

(

pjsip_process_rdata_param *

p

)

Initialize with default.

Parameters

p	The param.

pjsip_endpt_process_rx_data()

pj_status_t pjsip_endpt_process_rx_data	(	pjsip_endpoint *	endpt,
		pjsip_rx_data *	rdata,
		pjsip_process_rdata_param *	p,
		pj_bool_t *	p_handled
	)

Manually distribute the specified pjsip_rx_data to registered modules. Normally application does not need to call this function because received messages will be given to endpoint automatically by transports.

Application can use this function when it has postponed the processing of an incoming message, for example to perform long operations such as database operation or to consult other servers to decide what to do with the message. In this case, application clones the original rdata, return from the callback, and perform the long operation. Upon completing the long operation, it resumes pjsip's module processing by calling this function, and then free the cloned rdata.

Parameters

endpt	The endpoint instance.
rdata	The rdata to be distributed.
p	Optional pointer to param to specify from which module the processing should start.
p_handled	Optional pointer to receive last return value of module's on_rx_request() or on_rx_response() callback.

Returns

PJ_SUCCESS on success.

pjsip_endpt_create_pool()

pj_pool_t * pjsip_endpt_create_pool	(	pjsip_endpoint *	endpt,
		const char *	pool_name,
		pj_size_t	initial,
		pj_size_t	increment
	)

Create pool from the endpoint. All SIP components should allocate their memory pool by calling this function, to make sure that the pools are allocated from the same pool factory. This function, like all other endpoint functions, is thread safe.

Parameters

endpt	The SIP endpoint.
pool_name	Name to be assigned to the pool.
initial	The initial size of the pool.
increment	The resize size.

Returns

Memory pool, or NULL on failure.

See also

pj_pool_create

pjsip_endpt_release_pool()

void pjsip_endpt_release_pool	(	pjsip_endpoint *	endpt,
		pj_pool_t *	pool
	)

Return back pool to endpoint to be released back to the pool factory. This function, like all other endpoint functions, is thread safe.

Parameters

endpt	The endpoint.
pool	The pool to be destroyed.

pjsip_endpt_find_tsx()

pjsip_transaction * pjsip_endpt_find_tsx	(	pjsip_endpoint *	endpt,
		const pj_str_t *	key
	)

Find transaction in endpoint's transaction table by the transaction's key. This function normally is only used by modules. The key for a transaction can be created by calling pjsip_tsx_create_key.

Parameters

endpt	The endpoint instance.
key	Transaction key, as created with pjsip_tsx_create_key.

Returns

The transaction, or NULL if it's not found.

pjsip_endpt_register_tsx()

void pjsip_endpt_register_tsx	(	pjsip_endpoint *	endpt,
		pjsip_transaction *	tsx
	)

Register the transaction to the endpoint's transaction table. This function should only be used internally by the stack.

Parameters

endpt	The SIP endpoint.
tsx	The transaction.

pjsip_endpt_destroy_tsx()

void pjsip_endpt_destroy_tsx	(	pjsip_endpoint *	endpt,
		pjsip_transaction *	tsx
	)

Forcefull destroy the transaction. This function should only be used internally by the stack.

Parameters

endpt	The endpoint.
tsx	The transaction to destroy.

pjsip_endpt_create_tdata()

pj_status_t pjsip_endpt_create_tdata	(	pjsip_endpoint *	endpt,
		pjsip_tx_data **	p_tdata
	)

Create a new transmit data buffer. This function, like all other endpoint functions, is thread safe.

Parameters

endpt	The endpoint.
p_tdata	Pointer to receive transmit data buffer.

Returns

PJ_SUCCESS or the appropriate error code.

pjsip_endpt_create_resolver()

pj_status_t pjsip_endpt_create_resolver	(	pjsip_endpoint *	endpt,
		pj_dns_resolver **	p_resv
	)

Create the DNS resolver instance. Application creates the DNS resolver instance, set the nameserver to be used by the DNS resolver, then set the DNS resolver to be used by the endpoint by calling pjsip_endpt_set_resolver().

Parameters

endpt	The SIP endpoint instance.
p_resv	Pointer to receive the DNS resolver instance.

Returns

PJ_SUCCESS on success, or the appropriate error code.

pjsip_endpt_set_resolver()

pj_status_t pjsip_endpt_set_resolver	(	pjsip_endpoint *	endpt,
		pj_dns_resolver *	resv
	)

Set DNS resolver to be used by the SIP resolver. Application can set the resolver instance to NULL to disable DNS resolution (perhaps temporarily). When DNS resolver is disabled, the endpoint will resolve hostnames with the normal pj_gethostbyname() function.

Parameters

endpt	The SIP endpoint instance.
resv	The resolver instance to be used by the SIP endpoint.

Returns

PJ_SUCCESS on success, or the appropriate error code.

pjsip_endpt_set_ext_resolver()

pj_status_t pjsip_endpt_set_ext_resolver	(	pjsip_endpoint *	endpt,
		pjsip_ext_resolver *	ext_res
	)

Set the DNS external resolver implementation to use in the SIP resolver.

Note that naturally when implementing its own resolver, application would not need the internal resolver, hence this function will also destroy the PJLIB-UTIL DNS resolver if any (e.g: set using pjsip_endpt_set_resolver()). Application that needs it, still be able create its own instance.

Parameters

endpt	The SIP resolver engine.
ext_res	The external resolver implementation callback. This argument can be NULL to reset the whole external implementation. However, it is prohibited to reset individual callback.

Returns

PJ_SUCCESS on success, or the appropriate error code.

pjsip_endpt_get_resolver()

pj_dns_resolver * pjsip_endpt_get_resolver

(

pjsip_endpoint *

endpt

)

Get the DNS resolver being used by the SIP resolver.

Parameters

endpt

The SIP endpoint instance.

Returns

The DNS resolver instance currently being used by the SIP endpoint.

pjsip_endpt_resolve()

void pjsip_endpt_resolve	(	pjsip_endpoint *	endpt,
		pj_pool_t *	pool,
		pjsip_host_info *	target,
		void *	token,
		pjsip_resolver_callback *	cb
	)

Asynchronously resolve a SIP target host or domain according to rule specified in RFC 3263 (Locating SIP Servers). When the resolving operation has completed, the callback will be called.

Parameters

endpt	The endpoint instance.
pool	The pool to allocate resolver job.
target	The target specification to be resolved.
token	A user defined token to be passed back to callback function.
cb	The callback function.

pjsip_endpt_get_tpmgr()

pjsip_tpmgr * pjsip_endpt_get_tpmgr

(

pjsip_endpoint *

endpt

)

Get transport manager instance.

Parameters

endpt

The endpoint.

Returns

Transport manager instance.

pjsip_endpt_get_ioqueue()

pj_ioqueue_t * pjsip_endpt_get_ioqueue

(

pjsip_endpoint *

endpt

)

Get ioqueue instance.

Parameters

endpt

The endpoint.

Returns

The ioqueue.

pjsip_endpt_acquire_transport()

pj_status_t pjsip_endpt_acquire_transport	(	pjsip_endpoint *	endpt,
		pjsip_transport_type_e	type,
		const pj_sockaddr_t *	remote,
		int	addr_len,
		const pjsip_tpselector *	sel,
		pjsip_transport **	p_tp
	)

Find a SIP transport suitable for sending SIP message to the specified address. If transport selector ("sel") is set, then the function will check if the transport selected is suitable to send requests to the specified address.

See also

pjsip_tpmgr_acquire_transport

Parameters

endpt	The SIP endpoint instance.
type	The type of transport to be acquired.
remote	The remote address to send message to.
addr_len	Length of the remote address.
sel	Optional pointer to transport selector instance which is used to find explicit transport, if required.
p_tp	Pointer to receive the transport instance, if one is found.

Returns

PJ_SUCCESS on success, or the appropriate error code.

pjsip_endpt_acquire_transport2()

pj_status_t pjsip_endpt_acquire_transport2	(	pjsip_endpoint *	endpt,
		pjsip_transport_type_e	type,
		const pj_sockaddr_t *	remote,
		int	addr_len,
		const pjsip_tpselector *	sel,
		pjsip_tx_data *	tdata,
		pjsip_transport **	p_tp
	)

Find a SIP transport suitable for sending SIP message to the specified address by also considering the outgoing SIP message data. If transport selector ("sel") is set, then the function will check if the transport selected is suitable to send requests to the specified address.

See also

pjsip_tpmgr_acquire_transport

Parameters

endpt	The SIP endpoint instance.
type	The type of transport to be acquired.
remote	The remote address to send message to.
addr_len	Length of the remote address.
sel	Optional pointer to transport selector instance which is used to find explicit transport, if required.
tdata	Optional pointer to SIP message data to be sent.
p_tp	Pointer to receive the transport instance, if one is found.

Returns

PJ_SUCCESS on success, or the appropriate error code.

pjsip_endpt_get_capability()

const pjsip_hdr * pjsip_endpt_get_capability	(	pjsip_endpoint *	endpt,
		int	htype,
		const pj_str_t *	hname
	)

Get the value of the specified capability header field.

Parameters

endpt	The endpoint.
htype	The header type to be retrieved, which value may be: PJSIP_H_ACCEPT PJSIP_H_ALLOW PJSIP_H_SUPPORTED
hname	If htype specifies PJSIP_H_OTHER, then the header name must be supplied in this argument. Otherwise the value must be set to NULL.

Returns

The appropriate header, or NULL if the header is not available.

pjsip_endpt_has_capability()

pj_bool_t pjsip_endpt_has_capability	(	pjsip_endpoint *	endpt,
		int	htype,
		const pj_str_t *	hname,
		const pj_str_t *	token
	)

Check if we have the specified capability.

Parameters

endpt	The endpoint.
htype	The header type to be retrieved, which value may be: PJSIP_H_ACCEPT PJSIP_H_ALLOW PJSIP_H_SUPPORTED
hname	If htype specifies PJSIP_H_OTHER, then the header name must be supplied in this argument. Otherwise the value must be set to NULL.
token	The capability token to check. For example, if htype is PJSIP_H_ALLOW, then token specifies the method names; if htype is PJSIP_H_SUPPORTED, then token specifies the extension names such as "100rel".

Returns

PJ_TRUE if the specified capability is supported, otherwise PJ_FALSE..

pjsip_endpt_add_capability()

pj_status_t pjsip_endpt_add_capability	(	pjsip_endpoint *	endpt,
		pjsip_module *	mod,
		int	htype,
		const pj_str_t *	hname,
		unsigned	count,
		const pj_str_t	tags[]
	)

Add or register new capabilities as indicated by the tags to the appropriate header fields in the endpoint.

Parameters

endpt	The endpoint.
mod	The module which registers the capability.
htype	The header type to be set, which value may be: PJSIP_H_ACCEPT PJSIP_H_ALLOW PJSIP_H_SUPPORTED
hname	If htype specifies PJSIP_H_OTHER, then the header name must be supplied in this argument. Otherwise the value must be set to NULL.
count	The number of tags in the array. The value must not be greater than PJSIP_GENERIC_ARRAY_MAX_COUNT.
tags	Array of tags describing the capabilities or extensions to be added to the appropriate header.

Returns

PJ_SUCCESS on success.

pjsip_endpt_get_request_headers()

const pjsip_hdr * pjsip_endpt_get_request_headers

(

pjsip_endpoint *

e

)

Get list of additional headers to be put in outgoing request message. Currently only Max-Forwards are defined.

Parameters

e	The endpoint.

Returns

List of headers.

pjsip_endpt_dump()

void pjsip_endpt_dump	(	pjsip_endpoint *	endpt,
		pj_bool_t	detail
	)

Dump endpoint status to the log. This will print the status to the log with log level 3.

Parameters

endpt	The endpoint.
detail	If non zero, then it will dump a detailed output. BEWARE that this option may crash the system because it tries to access all memory pools.

pjsip_endpt_atexit()

pj_status_t pjsip_endpt_atexit	(	pjsip_endpoint *	endpt,
		pjsip_endpt_exit_callback	func
	)

Register cleanup function to be called by SIP endpoint when pjsip_endpt_destroy() is called. Note that application should not use or access any endpoint resource (such as pool, ioqueue, timer heap) from within the callback as such resource may have been released when the callback function is invoked.

Parameters

endpt	The SIP endpoint.
func	The function to be registered.

Returns

PJ_SUCCESS on success.