PJSIP开发者指南：构建高性能SIP栈

4星 · 超过85%的资源需积分: 32 2 浏览量更新于2024-07-26 1 收藏 939KB PDF 举报

"PJSIP开发者指南，版本0.5.4，是一份详细介绍了PJSIP的开发和内部架构的文档。PJSIP是一个用C语言编写的轻量级、高性能的SIP（Session Initiation Protocol）堆栈，遵循GPL许可，同时也提供其他授权选项。此文档由Benny Prijono编写，受GNU Free Documentation License v1.2保护，允许复制和分发原始副本，但禁止修改。文档的修订历史记录显示了PJSIP功能的逐步完善，包括事件框架、存在（Presence）和引用（Refer）事件包的添加，以及PJSUA抽象层的引入等。" 在深入探讨PJSIP之前，我们需要理解SIP是什么。SIP是一种用于建立、管理和终止多媒体通信会话的互联网协议，广泛应用于VoIP（Voice over IP）系统。PJSIP作为一个SIP库，它的主要目标是提供一个高效且易于使用的接口，让开发者能够快速地构建SIP应用。 PJSIP的内部架构主要包括以下几个关键组件： 1. **事务（Transaction）层**：负责处理SIP消息的事务流程，如请求和响应的匹配、超时处理等。开发者需要注意的是，当创建UAS（User Agent Server，服务器端）事务时，应用需要调用`pjsip_tsx_recv_msg()`来接收消息。 2. **会话（Session）层**：管理SIP会话，包括呼叫状态、媒体协商和会话更新。PJSIP提供了丰富的API来支持会话的创建、修改和终止，例如`dlg_terminate()`用于结束对话，`inv_terminate()`用于终止邀请会话。 3. **事件框架**：从0.5.2版本开始引入，提供了处理SIP事件的能力，如注册、注销、在线状态（Presence）和引用（Refer）事件。这对于实现高级功能，如即时通讯和状态感知至关重要。 4. **模块（Module）**：PJSIP通过模块化设计来扩展功能，每个模块专注于特定的SIP功能。例如，媒体能力管理模块用于处理通用的会话描述（SDP）和媒体能力。 5. **PJSUA抽象层**：从0.5.4版本开始引入，PJSUA提供了一种更高级别的接口，简化了应用程序与PJSIP的交互。这使得开发者可以更容易地实现基本的SIP功能，如注册、呼叫、消息传递和媒体操作。 6. **许可证**：PJSIP遵循GPL，这意味着任何基于PJSIP开发的软件都必须开放源代码。对于商业项目，PJSIP也提供了其他授权选项。在开发过程中，开发者需要熟悉PJSIP的API，理解SIP协议的工作原理，并根据文档中的示例代码来实现自己的功能。此外，持续关注PJSIP的更新和修订历史，以便及时利用新特性并修复已知问题。为了成功地使用PJSIP，开发者还需要了解网络编程、多媒体处理（如编码和解码）、信号处理和实时传输协议（如RTP）。同时，对SIP扩展如IM（即时消息）和iscomposing（正在输入提示）的支持，意味着开发者需要理解这些协议如何融入SIP框架。 PJSIP是一个强大而灵活的工具，它为开发者提供了构建复杂SIP应用的基础。通过深入学习PJSIP的文档和实践，开发者可以创建出高效、稳定且功能丰富的VoIP解决方案。

PJSIP Developer’s Guide
The on_rx_request() and on_rx_response() function pointers are the primary 
means for the module to receive SIP messages from endpoint (pjsip_endpt) or 
from other modules. The return value of these callbacks is important. If a callback 
has returned non-zero (i.e. true condition), it semantically means that the module 
has taken care the message; in this case, the endpoint will stop distributing the 
message to other modules. Section 2.1.3 Incoming Message Processing by
Modules will describe this in more detail.
The on_tx_request() and on_tx_response() function pointers are called by 
transport manager before a message is transmitted. This gives an opportunity for 
some types of modules (e.g. sigcomp, message signing) chance to make last 
modification to the message. All modules MUST return PJ_SUCCESS (i.e. zero 
status), or otherwise the transmission will be cancelled.  Section 2.1.4 Outgoing
Message Processing by Modules will describe this in more detail.
The on_tsx_state() function pointer is used to receive notification every time a 
transaction state has changed, which can be caused by receipt of message, 
transmission of message, timer events, or transport error event. More 
information about this callback will be described in next section 2.1.5 
“Transaction User and State Callback”.
2.1.2 Module Priorities
Module priority specifies the order of which modules are called first to process the 
callback. Module with higher priority (i.e. lower priority number) will have their 
on_rx_request() and on_rx_response() called first, and on_tx_request() and 
on_tx_response() called last.
The values below are the standard to set module priority.
enum pjsip_module_priority
{
PJSIP_MOD_PRIORITY_TRANSPORT_LAYER = 8, // Transport 
PJSIP_MOD_PRIORITY_TSX_LAYER = 16, // Transaction layer.
PJSIP_MOD_PRIORITY_UA_PROXY_LAYER = 32, // UA or proxy layer
PJSIP_MOD_PRIORITY_DIALOG_USAGE = 48, // Invite usage, event subscr. framework.
PJSIP_MOD_PRIORITY_APPLICATION = 64, // Application has lowest priority.
};
Code 4 Module Priorities
Note   : remember that lower priority    number    means higher priority!  
The priority PJSIP_MOD_PRIORITY_TRANSPORT_LAYER is the priority used by 
transport manager. This priority currently is only used to control message 
transmission, i.e. module with lower priority than this (that means higher priority 
number!) will have the on_tx_request()/on_tx_response() called before the 
message is processed by transport layer (e.g. destination is calculated, message 
is printed to contiguous buffer), while module with higher priority than this will 
have the callback called after the message has been processed by transport 
layer. Please see 2.1.4Outgoing Message Processing by Modules for more 
information.
PJSIP_MOD_PRIORITY_TSX_LAYER is the priority used by transaction layer 
module. The transaction layer absorbs all incoming messages that belong to a 
transaction.
PJSIP_MOD_PRIORITY_UA_PROXY_LAYER is the priority used by UA layer (i.e. 
dialog framework) or proxy layer. The UA layer absorbs all incoming messages 
that belong to a dialog set (this means forked responses as well).
Page 16

PJSIP Developer’s Guide

PJSIP_MOD_PRIORITY_DIALOG_USAGE is for dialog usages. Currently PJSIP

implements two types of dialog usages: invite sesssion and event subscription

session (including REFER subscription). The dialog usage absorbs messages inside

a dialog that belong to particular session.

PJSIP_MOD_PRIORITY_APPLICATION is the appropriate value for typical

application modules, when they want to utilize transactions, dialogs, and dialog

usages.

2.1.3 Incoming Message Processing by Modules

When incoming message arrives, it is represented as receive message buffer

(struct pjsip_rx_data, see section 5.1 “Receive Data Buffer”). Transport

manager parses the message, put the parsed data structures in the receive

message buffer, and passes the message to the endpoint.

The endpoint distributes the receive message buffer to each registered module by

calling on_rx_request() or on_rx_response() callback, starting from module with

highest priority (i.e. lowest priority number) until one of them returns non-zero.

When one of the module has returned non-zero, endpoint stops distributing the

message to the remaining of the modules, because it assumes that the module

has taken care about the processing of the message.

The module which returns non-zero on the callback itself may further distribute

the message to other modules. For example, the transaction module, upon

receiving matching message, will process the message then distributes the

message to its transaction user, which in itself must be a module too. The

transaction passes the message to the transaction user (i.e. a module) by calling

on_rx_request() or on_rx_response() callback of that module, after setting the

transaction field in the receive message buffer so that the transaction user

module can distinguish between messages that are outside transactions and

messages that are inside a transaction.

The following diagram shows an example of how modules may cascadely call

other modules.

MODULE

TRANSACTION

rdata

MODULE

DIALOG

MODULE

Event Subscriptn.

(SIMPLE)

rdata

MODULE

APPLICATION

rdata

ENDPOINT

Figure 4 Cascade Module Callback

2.1.4 Outgoing Message Processing by Modules

An outgoing request or response message is represented by a transmit data

buffer (pjsip_tx_data), which among other things, contains the message

structure itself, memory pool, contiguous buffer, and transport info.

When pjsip_transport_send() is called to send a message, transport manager

calls on_tx_request() or on_tx_response() for all modules, starting with modules

with lowest priority (i.e. highest priority number). When these callbacks are

called, the message may have or have not been processed by the transport layer.

The transport layer is responsible for managing these information inside a

transmit buffer:

 transport info, and

 printing the message structure to contiguous buffer.

Modules with priority lower than PJSIP_MOD_PRIORITY_TRANSPORT_LAYER (i.e.

has higher priority number) will receive the message before these information

Page 17

PJSIP Developer’s Guide

are obtained. That means the destination address has not been calculated, and

message has not been printed to contiguous buffer.

If modules want to modify the message structure before it is printed to buffer,

then it must set its priority number higher than transport layer priority. If

modules want to see the actual packet bytes as they are transmitted to the wire

(e.g. for logging purpose), then it should set its priority number to lower than

transport layer.

A practical case where a module wants to set its priority higher than transport layer (i.e. has lower

priority number) is the logging module, where it wants to print outgoing message after it has been

printed to contiguous buffer and destination address has been calculated.

In all cases, modules MUST return PJ_SUCCESS for the return value of these

callbacks. If a module returns other error codes, the transmission will be

cancelled and the error code is returned back to pjsip_transport_send() caller.

2.1.5 Transaction User and State Callback

A special callback in the module definition (on_tsx_state) is used to receive

notification from a particular transaction when transaction state has changed.

This callback is unique because transaction state may change because of non-

message related events (e.g. timer timeout and transport error).

This callback will only be called after the module has been registered as

transaction user for a particular transaction. Only one transaction user is allowed

per transaction. Transaction user can be set to transaction on per transaction

basis.

For transactions created within a dialog, the transaction user is set to the UA

layer module on behalf of a particular dialog. When applications creates the

transaction manually, they may set themselves as the transaction user.

The on_tsx_state() callback will not be called upon receipt of request or response

retransmissions. Note that transmission or receipt of provisional responses are

not considered as retransmissions, which means that receipt or transmission of

provisional responses will always caused this callback to be called.

2.1.6 Module Specific Data

Some PJSIP components have a container where modules can put module specific

data in that component. This container is named as mod_data by convention, and

is an array of pointer to void, which is indexed by the module ID.

For example, an incoming packet buffer (pjsip_rx_data) has the following

declaration for module specific data container:

struct pjsip_rx_data

{

...

struct {

void *mod_data[PJSIP_MAX_MODULE];

} endpt_info;

};

Code 5 Module Specific Data

The mod_data array is indexed by module ID. The module ID is determined when

the module is registered to endpoint.

Page 18

PJSIP Developer’s Guide

2.1.8 Sample Callback Diagrams

Incoming Message Outside Transaction and Outside Dialog

ENDPOINT

(2) lookup /

not found

(1) rdata

endpt_transport_callback()

Transaction

Hash Table

Dialog

Hash Table

USER AGENT

TRANSACTION

DIALOG

TRANSPORT MANAGER

APPLICATION

on_rx_xxx()

(5) rdata

(3) rdata

on_rx_xxx()

(4) lookup /

not found

Figure 6 Processing of Incoming Message

Outside Transaction/Dialog

The processing is as follows:

1) Transport manager (pjsip_tpmgr) passes

all received messages to endpoint (after

parsing the message).

2) Endpoint (pjsip_endpt) distributes the

message to all registered callbacks. First

in the callback list is transaction layer.

Transaction layer looks up the message

in transaction table, and couldn’t find a

matching transaction.

3) Endpoint distributes the message to next

callback in the list, which is user agent.

4) User agent looks up the message in

dialog’s hash table and couldn’t find

matching dialog set.

5) Endpoint continues distributing the

message to next registered callbacks

until it reaches application. Application

processes the message (e.g. respond

statelessly, create UAS transaction, or

proxy the request, or create dialog, etc.)

Incoming Message Inside Transaction

ENDPOINT

(2) lookup /

found !

(1) rdata

endpt_transport_callback()

Transaction

Hash Table

Dialog

Hash Table

USER AGENT

(3) rdata

TRANSACTION

on_rx_xxx()

DIALOG/APPLICATION

TRANSPORT MANAGER

on_rx_xxx()

(4) rdata +tsx

(5) rdata +tsx +dlg

(6) notify state

on_tsx_state()

(7) notify dialog state

Figure 7 Processing of Incoming Message

Inside Transaction

The processing is as follows:

1) Transport manager (pjsip_tpmgr) passes

all received messages to endpoint (after

parsing the message).

2) Endpoint (pjsip_endpt) distributes the

message to all registered callbacks. First

in the callback list is transaction layer.

Transaction layer looks up the message

in transaction table, and found a

matching transaction.

3) Because transaction’s callback returns

PJ_TRUE, endpoint does not distribute

the message further.

4) The transaction processes the response

(e.g. updates the FSM). If the message is

a retransmission, the processing stops

here. Otherwise transaction then passes

the message to it’s transaction user (TU),

which can be a dialog or application.

5) If the TU is a dialog, the dialog processes

the response then pass the response to

it’s dialog user (DU, e.g. application).

6) If the arrival of the message has changed

transaction’s state, transaction will notify

it’s TU about the new state.

7) If TU is a dialog, it may further notify

application about dialog’s state changed.

Page 20

剩余111页未读，继续阅读

zhangbinHn

粉丝: 6
资源: 1

PJSIP开发者指南：构建高性能SIP栈

PJSIP_Developer_Guide

PJSIP开发指南中文版

PJSIP开发指南 英文版 PDF

PJSIP开发指南英文版本 0.5.4

PJSIP开发指南中文版1-6章

PJSIP 开发指南中文版1-6章&JsSIP; demo

PJSIP 开发指南：高性能 SIP 栈开发开发文档

PJSIP开发指南：高性能SIP栈详解

PJSIP开发指南中文版：从入门到进阶

PJSIP开发指南中文版：从入门到精通

最新资源

PJSIP开发指南英文版 PDF