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

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

"PJSIP参考文档" PJSIP是一款小型、高速的SIP栈，编写于C语言，遵循GNU通用公共许可证（GPL）。PJSIP提供了一个灵活的API，允许开发者快速创建基于SIP的应用程序。 **关于PJSIP** PJSIP是一款开源的SIP栈，旨在提供一个小型、高速的SIP解决方案。它提供了一个灵活的API，允许开发者快速创建基于SIP的应用程序。PJSIP分布于GNU通用公共许可证（GPL）下，意味着它是免费的，並且可以自由地使用、修改和分发。 **PJSIP的特点** PJSIP具有以下特点： * 小型 footprint：PJSIP具有小型的代码体积，非常适合资源有限的设备。 * 高性能：PJSIP具有高性能的SIP处理能力，能够满足高并发的需求。 * 灵活的API：PJSIP提供了一个灵活的API，允许开发者快速创建基于SIP的应用程序。 * 开源：PJSIP是开源的，意味着开发者可以自由地使用、修改和分发。 **PJSIP的应用场景** PJSIP可以应用于以下场景： * VoIP应用程序：PJSIP可以用来创建基于SIP的VoIP应用程序，例如软电话、IP电话等。 * IMS应用程序：PJSIP可以用来创建基于IMS的应用程序，例如富媒体通信、视频会议等。 * 企业通信系统：PJSIP可以用来创建企业通信系统，例如统一通信平台、呼叫中心等。 **PJSIP的开发指南** PJSIP提供了一个详细的开发指南，帮助开发者快速上手PJSIP。开发指南包括以下内容： * PJSIP的基本概念：介绍PJSIP的基本概念，例如SIP、SDP、RTP等。 * PJSIP的API：介绍PJSIP的API，包括SIP、SDP、RTP等模块的使用方法。 * PJSIP的应用示例：提供了多个PJSIP的应用示例，帮助开发者快速上手PJSIP。 **PJSIP的版本历史** PJSIP的版本历史记录了PJSIP的每个版本的更新内容，包括新增功能、bug修复等。版本历史记录可以帮助开发者了解PJSIP的发展历程和更新内容。 **PJSIP的许可证** PJSIP分布于GNU通用公共许可证（GPL）下，意味着它是免费的，並且可以自由地使用、修改和分发。但是，需要注意的是，在使用PJSIP时，需要遵守GPL的条款。

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页未读，继续阅读

shawphei000

粉丝: 0
资源: 3

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

pjsip开发文档中文版本(全部章节)

PJSIP介绍、开发指南、PJSIP文档

PJSIP开发指南中文版

go-pjsip中文文档

PJSIP_Developer_Guide.pdf_pjsip_pjsip开发_

PJSIP-Dev-Guide.rar_eclipse pjsip_pjsip_pjsip video .rar_rtp vid

PJSIP协议栈

PJSIP-Dev-Guide.rar_pjsip

pjsip源代码zip

PJSIP-Dev-Guide.zip_developer_pjsip_zip

最新资源