Endpoint
[At the Very Core]

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

Theoritically application can have multiple instances of SIP endpoint, although it's not clear why application may want to do it.

Function Documentation

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

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

void pjsip_endpt_register_tsx	(	pjsip_endpoint *	endpt,
		pjsip_transaction *	tsx
	)

Parameters:

	endpt	The SIP endpoint.
	tsx	The transaction.

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.

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.

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.

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.

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.

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_tpmgr* pjsip_endpt_get_tpmgr ( pjsip_endpoint * endpt )

Get transport manager instance.

Parameters:

endpt

The endpoint.

Returns:: Transport manager instance.

pj_ioqueue_t* pjsip_endpt_get_ioqueue ( pjsip_endpoint * endpt )

Get ioqueue instance.

Parameters:

endpt

The endpoint.

Returns:: The ioqueue.

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.

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.

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

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.
	tags	Array of tags describing the capabilities or extensions to be added to the appropriate header.

Returns:: PJ_SUCCESS on success.

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:

The endpoint.

Returns:: List of headers.

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.

Endpoint [At the Very Core]

Detailed Description

Functions

Function Documentation

Endpoint
[At the Very Core]