一、模块
2.1 模块框架
模块框架的主要作用是在应用程序组件之间分发SIP消息，PJSIP的所有的组件，包括dialog和transaction都是以模块方式实现的，没有模块，核心协议栈将不知道如何处理SIP消息。
模块架构思基于简单但是非常强大的接口抽象，对于到达的消息，Endpoint 按照优先级向所有的模块分发消息，直到其中一个模块告知已经处理这个消息。对于出去的消息，endpoint分发消息到所有模块，在消息未到达网络之前，允许任何模块对消息做最后的修改。
2.1.1 模块声明
模块接口再<pjsip/sip_module.h>中声明，如下：
/**
* The declaration for SIP module. This structure would be passed to
* #pjsip_endpt_register_module() to register the module to PJSIP.
*/
struct pjsip_module
{
/** To allow chaining of modules in the endpoint. */
PJ_DECL_LIST_MEMBER(struct pjsip_module);
/**
* Module name to identify the module.
*
* This field MUST be initialized before registering the module.
*/
pj_str_t name;
/**
* Module ID. Application must initialize this field with -1 before
* registering the module to PJSIP. After the module is registered,
* this field will contain a unique ID to identify the module.
*/
int id;
/**
* Integer number to identify module initialization and start order with
* regard to other modules. Higher number will make the module gets
* initialized later.
*
* This field MUST be initialized before registering the module.
*/
int priority;
/**
* Optional function to be called to initialize the module. This function
* will be called by endpoint during module registration. If the value
* is NULL, then it's equal to returning PJ_SUCCESS.
*
* @param endpt The endpoint instance.
* @return Module should return PJ_SUCCESS to indicate success.
*/
pj_status_t (*load)(pjsip_endpoint *endpt);
/**
* Optional function to be called to start the module. This function
* will be called by endpoint during module registration. If the value
* is NULL, then it's equal to returning PJ_SUCCESS.
*
* @return Module should return zero to indicate success.
*/
pj_status_t (*start)(void);
/**
* Optional function to be called to deinitialize the module before
* it is unloaded. This function will be called by endpoint during
* module unregistration. If the value is NULL, then it's equal to
* returning PJ_SUCCESS.
*
* @return Module should return PJ_SUCCESS to indicate success.
*/
pj_status_t (*stop)(void);
/**
* Optional function to be called to deinitialize the module before
* it is unloaded. This function will be called by endpoint during
* module unregistration. If the value is NULL, then it's equal to
* returning PJ_SUCCESS.
*
* @param mod The module.
*
* @return Module should return PJ_SUCCESS to indicate success.
*/
pj_status_t (*unload)(void);
/**
* Optional function to be called to process incoming request message.
*
* @param rdata The incoming message.
*
* @return Module should return PJ_TRUE if it handles the request,
* or otherwise it should return PJ_FALSE to allow other
* modules to handle the request.
*/
pj_bool_t (*on_rx_request)(pjsip_rx_data *rdata);
/**
* Optional function to be called to process incoming response message.
*
* @param rdata The incoming message.
*
* @return Module should return PJ_TRUE if it handles the
* response, or otherwise it should return PJ_FALSE to
* allow other modules to handle the response.
*/
pj_bool_t (*on_rx_response)(pjsip_rx_data *rdata);
/**
* Optional function to be called when transport layer is about to
* transmit outgoing request message.
*
* @param tdata The outgoing request message.
*
* @return Module should return PJ_SUCCESS in all cases.
* If non-zero (or PJ_FALSE) is returned, the message
* will not be sent.
*/
pj_status_t (*on_tx_request)(pjsip_tx_data *tdata);
/**
* Optional function to be called when transport layer is about to
* transmit outgoing response message.
*
* @param tdata The outgoing response message.
*
* @return Module should return PJ_SUCCESS in all cases.
* If non-zero (or PJ_FALSE) is returned, the message
* will not be sent.
*/
pj_status_t (*on_tx_response)(pjsip_tx_data *tdata);
/**
* Optional function to be called when this module is acting as
* transaction user for the specified transaction, when the
* transaction's state has changed.
*
* @param tsx The transaction.
* @param event The event which has caused the transaction state
* to change.
*/
void (*on_tsx_state)(pjsip_transaction *tsx, pjsip_event *event);
};
所有回调函数的指针都是可选的，如果没有被指定，被默认为返回成功。
Load, start, stop, unload这四个函数指针被enpoint调用，控制模块的状态，下面的图展示了模块状态的生命周期：
其中on_rx_request( ) 和 on_rx_response( ) 主要作用是从sip_endpoint或其他的模块接收SIP消息。Callback函数的返回值非常重要，如果返回非0(相当于true)，意味这个模块已经处理消息，这时，endpoint将停止分发消息到其他的模块。2.1.3 节呼入消息的处理将会详细描述。
On_tx_request( ) 和 on_tx_response（ ）在消息被广播前通过transport manager调用，这给了一些类型模块（比如：sigcomp 、 message signing）最后修改消息的机会。所有的模块必须都要返回PJ_SUCCESS（ie zero）。否则分发将会被取消，外出的消息，将会在2.1.4的将会详细描述。
On_tsx_state() 函数用来接收事务状态改变的通知，比如：接收消息、发送消息、定时器事件、传输错误事件都可能引起通知，在2.1.5节将会详细的介绍
2.1.2 模块的优先级
通过优先级指定回调调用的顺序，高优先级模块将首先调用on_rx_request 和 on_rx_response。最后调用on_tx_request 和 on_tx_response
下面是模块优先级的标准
/**
* Module priority guidelines.
*/
enum pjsip_module_priority
{
/**
* This is the priority used by transport layer.
*/
PJSIP_MOD_PRIORITY_TRANSPORT_LAYER = 8,
/**
* This is the priority used by transaction layer.
*/
PJSIP_MOD_PRIORITY_TSX_LAYER = 16,
/**
* This is the priority used by the user agent and proxy layer.
*/
PJSIP_MOD_PRIORITY_UA_PROXY_LAYER = 32,
/**
* This is the priority used by the dialog usages.
*/
PJSIP_MOD_PRIORITY_DIALOG_USAGE = 48,
/**
* This is the recommended priority to be used by applications.
*/
PJSIP_MOD_PRIORITY_APPLICATION = 64
};
注意： 数字越小优先级越高
PJSIP_MOD_PRIORITY_TRANSPORT_LAYER 被用于传输管理模块，优先级当前只是被用来控制消息的传送。低优先级的模块将在传输层调用on_tx_request/on_tx_response回调函数之前调用。高优先级的模块，将在传输层处理之后调用这两个函数。2.1 4 将详细介绍outgoing的细节。
PJSIP_MOD_PRIORITY_TSX_LAYER 是Transaction layer拥有的优先级，事务层接收所有属于事务层输入的消息。
PJSIP_MOD_PRIORITY_UA_PROXY_LAYER 是UA layer（dialog framework ）或 proxy layer 拥有的权限，UA layer 接收所有输入dialog的消息
PJSIP_MOD_PRIORITY_DIALOG_USAGE 是dialog的拥有的优先级，目前，PJSIP实现两个类型dilalog usage: invite session 和 event subscription(包括refer)。Dialog usage 接收同一个对话的属于特定session的所有消息。
PJSIP_MOD_PRIORITY_APPLICATION 是应用模块和合适的值，当他采用transaction、dialogs 和 dislog usage时。
2.1.3 处理呼入消息的模块
当Incoming Message到达时，提供接收消息的缓存区（结构体：pjsip_rx_data，参考第5章的 “Recive Data Buffer”）传输管理模块解析消息，并且把解析的数据结构存放在缓冲区中，把消息传递到endpoint.
Endpoint 分发接收的消息到每一个注册模块，调用on_rx_request和on_rx_response的回调。从高优先级的模块开始，直到有一个模块返回非0。当模块返回非0时， endpoint 不再发送消息到剩余的模块，因为它假定这个模块关心该消息的处理。
处理消息的模块可能分发消息到其他模块，举例：事务模块接收到匹配的消息，处理该消息然后再分发到其他到事务用户（本身也是一个模块）。Transction传递消息，通过回调 on_rx_request 和 on_rx_response 传递消息到transction user，在设置transction接收缓冲区以便transction user模块能其区分transction内部消息和外部消息。
下图显示模块的如何重叠调用其他的模块
2.1.4 模块处理呼出消息
出去的请求和响应消息由transmit data buffer(pjsip_tx_data)处理，包含了消息结构体本身、内存池、连续的buffer 和 transport info。
Pjsip_transport_send( ) 被调用发送一个消息，transport manager 调用on_tx_request 或 on_tx_response 为所有的模块，处理顺序是优先级的低先接收消息。当回调被调用时，消息可能已经或还没有被transport layer处理。Transport layer 主要负责管理transimit buffer。
l Transport info
l 打印结构和连续 buffer的结构体
低于PJSIP_MOD_PRIORITY_TRANSPORT_LAYER优先级的模块，将会接收消息，在这些信息被获取到之前，这就意味着目标地址没有被计算出来并且消息还没有被输出到连续buffer。
如果模块准备改变消息结构体在打印buffer之前，他一定设置他的优先级高于transport layer的优先级，如果模块先看真实的packet bytes，再它被传送到网络之前，它应该设置优先级低于transport layer。
在所有的情况下，模块一定要返回PJ_SUCCESS. 如果模块返回错误码，transmission 将被取消，并且错误码将会返回到调用者pjsip_transport_send.
2.1.5 事务用户及状态回调
回调函数on_tsx_state被用来接收特定事务的通知，当事务状态发生改变时，回调是唯一的通知路径。但是transcation的事务改变也可能会因为非消息的事件引起的。比如：超时或者传输错误
当模块注册为事务用户，才拥有这个回调，在一个事务中，只允许有一个事务用户，transaction user 能够被设置为事务再每一个transction基础上。
在dialog创建的事务，transaction user 被设置为 UA layer 模块，当应用程序手工创建事务时，他们作为事务用户设置。
On_tsx_state回调收到retransmissions的request 和 response消息时，回调将不会再被调用。注意：发送和接收临时的响应将不会被认为重传。临时消息的接收和重传将会导致回调被调用。