PJSIP开发手册之模块（二）

第二章 模块

模块框架是在PJSIP程序中各个软件组件之间派发SIP消息的主要方法。PJSIP中所有的软件组件，包括transaction层和dialog层，都是以模块实现的。如果没有模块，核心栈（pjsip_endpoint和transport）就不知道如何处理SIP消息。

模块框架是基于一个简单但是功能强大的接口抽象。对于接收到的消息，Endpoint（pjsip_endpoint）按照优先级向各个模块分发这个消息，直到其中一个模块处理了这个消息。对于发出的消息，Endpoint在电缆传输数据之前，会将这个消息分发到各个模块，允许它们对消息做最后的修改。

 

模块声明

模块接口在<pjsip/sip_module.h>中声明，如下：

所有的函数指针是可选的，如果它们没有被指定，它们将会被认为是成功返回的。

Load，start，stop，和unload这四个函数将会被Endpoint调用去控制模块状态。下图是模块状态的生命周期：

on_rx_request()和on_rx_response()函数指针是模块从Endpoint（pjsip_endpt）或其他模块接收SIP消息的主要方法。这些回调函数的返回值很重要。如果一个回调函数返回非0（例如真的条件），表示这个模块已经处理了这个消息，这样，Endpoint就可以停止分发消息到其他模块。

在一个消息被发送之前，on_tx_request()和on_tx_response()函数指针将会被传输管理调用。这就给了一些模块（比如sipcomp，message signing）机会去对消息做最后的修改。所有的模块必须返回PJ_SUCCESS（例如0状态），否则传输将被取消。

on_tsx_state()函数指针用于接收由于接收到消息、发送消息、定时器事件或者网络错误事件引起的事务状态改变的通知。

模块优先级

模块的优先级决定了模块被调用来处理回调的顺序。高优先级的模块（例如，较小的优先级数）将会先调用它们的on_rx_request()和on_rx_response()，最后调用它们的on_tx_request()和on_tx_response()函数。

下面给出的是标准的模块优先级的值：（注意：数字越小优先级越高）

Transport Manager使用的是PJSIP_MOD_PRIORITY_TRANSPORT_LAYER优先级。这个优先级是用来控制消息的传输，例如，优先级比它低的模块（有更大的优先级数）的on_tx_request()和on_tx_response()函数将会在传输层处理消息之前调用（例如，目的地址的计算，在连续的缓存里打印消息等等）。而且高优先级的模块将会在传输层处理完成之后，才会调用回调函数。

Transaction层使用PJSIP_MOD_PRIORITY_TSX_LAYER优先级。Transaction层接收属于一个Transaction里的所有接收到的消息。

UA层（如dialog框架）或proxy层使用PJSIP_MOD_PRIORITY_UA_PROXY_LAYER优先级。UA层吸收所有属于同一个dialog集的所有接收到的消息（这代表有分歧的响应）。

Dialog usages使用PJSIP_MOD_PRIORITY_DIALOG_USAGE优先级。目前PJSIP实现了两种dialog usages：INVITE会话和事件订阅会话（包括REFER订阅）。Dialog usage吸收属于一个特定的会话的同一个dialog的消息。

对于应用模块来说PJSIP_MOD_PRIORITY_APPLICATION是一个合适的值，因为应用希望利用transactions、dialogs和dialog usages。

到来消息的模块处理

当消息到来时，它将被表示为接收消息缓存（struct pjsip_rx_data）。传输管理解析这个消息后，把解析后的数据结构存放在接收消息缓存中，并把消息传给Endpoint。

Endpoint通过调用on_rx_request()或on_rx_response()回调函数将接收消息缓存分发给各个已注册的模块。先分发到高优先级的模块，直到有个模块返回非零。当一个模块返回非