PJSIP 0.5.4开发者指南：初学者入门与关键API详解

需积分: 2 31 浏览量更新于2024-06-27 收藏 922KB PDF 举报

PJSIP开发指南（英文版 0.5.4）是针对PJSIP这一小型、高性能的SIP（Session Initiation Protocol）栈的开发者手册，它是在C语言编写的。PJSIP遵循GNU通用公共许可证（GPL），同时也提供其他许可选项。这个文档由Benny Prijono在2005-2006年间维护，并且是免费发布的，遵循GNU自由文档许可证第1.2版。对于初学者来说，这份文档提供了丰富的教程和实用信息。以下是该版本的主要更新内容： 1. **新功能添加**： - `dlg_terminate()` 和 `inv_terminate()` 等函数被加入，可能涉及会话管理和终止的相关操作。 - 对事件框架（event framework）进行了增强，包括添加了 presence 和 refer 事件处理包，这对于实时通信功能如在线状态管理和媒体转接至关重要。 2. **API改进**： - 事件子系统（evsub API）得到了进一步审查和扩展，增加了更多的细节描述，帮助开发者更好地理解和利用。 3. **新章节**： - 添加了即时消息（IM）和会话进行中的操作（如媒体合成）的章节，这些对于构建支持多媒体通信的应用非常重要。 - PJSUA（PJSIP用户代理）抽象层的章节也已加入，这将有助于简化用户的接口设计，提高代码可重用性和模块化。 4. **重要注意事项**： - 应用程序在创建UAS（User Agent Server）交易后必须调用 `pjsip_tsx_recv_msg()`，以确保正确处理来自网络的消息。 5. **版本更新历史**： - 从0.5.0到0.5.4，除了以上提及的功能，还新增了通用能力管理功能到终端点，以及对模块结构的调整，以适应不断变化的需求和技术演进。通过阅读这份开发指南，开发者能够了解到PJSIP的核心功能实现、事件处理机制、API使用方法，以及如何集成到自己的项目中。无论是初次接触PJSIP还是需要深入学习其最新特性的开发者，都可以从中找到所需的信息和指导。

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

韩搏

粉丝: 358
资源: 59

PJSIP 0.5.4开发者指南：初学者入门与关键API详解

PJSIP中文开发文档

PJSIP介绍、开发指南

PJSIP_Developer_Guide

PJSIP开发指南 英文版 PDF

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

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

pjsip 开发文档

PJSIP开发者指南：pjproject用户手册

PJSIP开发者指南：SIP协议栈详解

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

最新资源

PJSIP开发指南英文版 PDF