Group PJSIP_ENDPT

group PJSIP_ENDPT

The master, owner of all objects.

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.

Typedefs

typedef void (*pjsip_endpt_exit_callback)(pjsip_endpoint *endpt): Type of callback to register to pjsip_endpt_atexit().

Functions

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.

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.

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.

void pjsip_process_rdata_param_default(pjsip_process_rdata_param *p)

Initialize with default.

Parameters:: p – The param.

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.

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.