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.

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.

See: pj_pool_create

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.

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

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.

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

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

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: e – 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.

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.