BLOG | DOCUMENTATION | TRAC

Home --> Documentations --> PJSIP Reference

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_tpjsip_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)
 
void pjsip_endpt_cancel_timer (pjsip_endpoint *endpt, pj_timer_entry *entry)
 
pj_timer_heap_tpjsip_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_tpjsip_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_transactionpjsip_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_dns_resolverpjsip_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_tpmgrpjsip_endpt_get_tpmgr (pjsip_endpoint *endpt)
 
pj_ioqueue_tpjsip_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_hdrpjsip_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_hdrpjsip_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

typedef void(* pjsip_endpt_exit_callback)(pjsip_endpoint *endpt)

Type of callback to register to pjsip_endpt_atexit().

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
pfPool factory that will be used for the lifetime of endpoint.
nameOptional name to be specified for the endpoint. If this parameter is NULL, then the name will use local host name.
endptPointer 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
endptThe SIP endpoint to be destroyed.
const pj_str_t* pjsip_endpt_name ( const pjsip_endpoint endpt)

Get endpoint name.

Parameters
endptThe 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
endptThe endpoint.
max_timeoutMaximum 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
endptThe endpoint.
max_timeoutMaximum time to wait for events, or NULL to wait forever until event is received.
countOptional 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
endptThe endpoint.
entryThe timer entry.
delayThe 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
endptThe endpoint.
entryThe 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
endptThe 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
endptThe endpoint.
moduleThe 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
endptThe endpoint.
moduleThe module to be registered.
Returns
PJ_SUCCESS on success.
void pjsip_process_rdata_param_default ( pjsip_process_rdata_param p)

Initialize with default.

Parameters
pThe 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
endptThe endpoint instance.
rdataThe rdata to be distributed.
pOptional pointer to param to specify from which module the processing should start.
p_handledOptional 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.

Parameters
endptThe SIP endpoint.
pool_nameName to be assigned to the pool.
initialThe initial size of the pool.
incrementThe 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
endptThe endpoint.
poolThe 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
endptThe endpoint instance.
keyTransaction 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
endptThe SIP endpoint.
tsxThe 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
endptThe endpoint.
tsxThe 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
endptThe endpoint.
p_tdataPointer 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
endptThe SIP endpoint instance.
p_resvPointer 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
endptThe SIP endpoint instance.
resvThe 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
endptThe 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
endptThe endpoint instance.
poolThe pool to allocate resolver job.
targetThe target specification to be resolved.
tokenA user defined token to be passed back to callback function.
cbThe callback function.
pjsip_tpmgr* pjsip_endpt_get_tpmgr ( pjsip_endpoint endpt)

Get transport manager instance.

Parameters
endptThe endpoint.
Returns
Transport manager instance.
pj_ioqueue_t* pjsip_endpt_get_ioqueue ( pjsip_endpoint endpt)

Get ioqueue instance.

Parameters
endptThe 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
endptThe SIP endpoint instance.
typeThe type of transport to be acquired.
remoteThe remote address to send message to.
addr_lenLength of the remote address.
selOptional pointer to transport selector instance which is used to find explicit transport, if required.
p_tpPointer 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 Also
pjsip_tpmgr_acquire_transport
Parameters
endptThe SIP endpoint instance.
typeThe type of transport to be acquired.
remoteThe remote address to send message to.
addr_lenLength of the remote address.
selOptional pointer to transport selector instance which is used to find explicit transport, if required.
tdataOptional pointer to SIP message data to be sent.
p_tpPointer 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
endptThe endpoint.
htypeThe header type to be retrieved, which value may be:
  • PJSIP_H_ACCEPT
  • PJSIP_H_ALLOW
  • PJSIP_H_SUPPORTED
hnameIf 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
endptThe endpoint.
htypeThe header type to be retrieved, which value may be:
  • PJSIP_H_ACCEPT
  • PJSIP_H_ALLOW
  • PJSIP_H_SUPPORTED
hnameIf htype specifies PJSIP_H_OTHER, then the header name must be supplied in this argument. Otherwise the value must be set to NULL.
tokenThe 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
endptThe endpoint.
modThe module which registers the capability.
htypeThe header type to be set, which value may be:
  • PJSIP_H_ACCEPT
  • PJSIP_H_ALLOW
  • PJSIP_H_SUPPORTED
hnameIf htype specifies PJSIP_H_OTHER, then the header name must be supplied in this argument. Otherwise the value must be set to NULL.
countThe number of tags in the array.
tagsArray 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
eThe 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
endptThe endpoint.
detailIf 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
endptThe SIP endpoint.
funcThe function to be registered.
Returns
PJ_SUCCESS on success.

 


PJSIP Open Source, high performance, small footprint, and very very portable SIP stack
Copyright (C) 2006-2008 Teluu Inc.