JRTPLIB 3.5.2手册中文版---part1

 【译注：这是在Joris的主页提供的最新的手册，虽然库已经到了3.9.0版但是手册函数3.5.2版的，可以从Jori的主页上下载英文的手册：http://research.edm.uhasselt.be/~jori/page/index.php?n=CS.Jrtplib】

JRTPLIB 3.5.2

By: Jori Liesenborgs

jori@lumumba.uhasselt.be

March 26, 2006

 译：ljbsdu

1、 简介

       本文档介绍JRTPLIB 3.5.2版，该库是基于面向对象的C++库，目的是帮助使用RTP（实时传输协议）的开发者，RTP由RFC3550详细定义。

       该库让使用者可以使用RTP来收发数据而不必担心SSRC冲突，调度，以及RTCP数据的传输等问题。使用者只需要提供给库要发送的负载数据，库提供给使用者接口获得接收到的RTP和RTCP数据。

1.1 设计理念

       库提供了许多在创建RTP应用时有用的类。大部分的使用者可能只需要使用RTPSession类来创建应用程序。该类内部提供了发送RTP数据以及处理RTCP需要的函数。

       对于诸如混频器和转换器这类应用来说，使用RTPSession可能不是一个好的解决方案。其他组件可用来处理这些应用，例如：传输组件，SSRC表，RTCP调度等，使用这些组件应该可以更容易的处理这类应用。

1.2 从2.X版本的改动

       最大的一个改变可能就是这一版是基于RFC3550而2.x版则是基于已废弃的RFC1889。

       并且，2.X系列是基于这样的理念：使用者只能使用RTPSession类，也就是说其他的类单独使用没有多大用处。相对的，本版本的目的是提供给使用者更多的组件来帮助其灵活的创建RTP应用程序。

       在这个版本中，用于RTP包传输的底层协议代码是特定的，这些代码绑定在一个继承了RTPTransmitter接口的类上。（译者注：这句不好翻译：原文the code which is specific for the underlying protocol by which RTP packet are transported, is bundled in a class which inherits its interface from a class called RTPTransmitter, 基本意思就是用于发送RTP包的部分代码是从一个接口基类RTPTransmitter继承而来，由这个继承类负责包的发送）。这使得使用不同的底层协议支持变得简单了。现在提供了基于IPv4和IPv6的UDP传输。

 

2、 版权许可

该库代码使用以下版权许可：（【这部分没意思，不翻了，总之是free的：译注】）

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the ”Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED ”AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

There are two reasons for using this license. First, since this is the license of the 2.x series, it only seemed natural that this rewrite would contain the same license. Second, since the RTP protocol is deliberately incomplete RTP profiles can, for example, define additional header fields. The best way to deal with this is to adapt the library code itself and that’s why I like to keep the license as free as possible.

 

3、 使用Jrtplib 3.5.2

       本部分给出怎样使用库，首先给出一些简单的例子来展示如何使用RTPSession类。然后将给出对所有API的完整描述。

3.1 从RTPSession 类开始

       要使用RTP，你必须先创建一个RTPSession对象。RTPSession类的构造函数需要一个RTPTransmitte::TransmissionProtocol类型的参数，默认为RTPTransmitt::IPv4UDPProto.也就是说，除非明确指定否则将使用基于IPv4的UDP传输组件。假设这正是你要创建的，那么首先代码将如下：

RTPSession session;

要真正的创建会话，你需要调用Create成员函数，该函数需要两个参数，第一个参数类型为RTPSessionParams，指定了会话的一般选项。该类（RTPSessionParams）的一个参数必须显式的指定，否则会话将不能成功创建，这个参数就是你要发送的数据的时间戳单位，可以通过采样数除以采样时间间隔（以秒为单位）计算出来。假设我们要发送的是8000Hz的音频数据，我们可以这样写代码：

RTPSessionParams sessionparams; Sessionparams.SetOwnTimestampUnit(1.0/8000.0);

RTPSessionParams的其他参数依赖于要使用的RTP配置。一个关于RTPSessionParams类的完整描述参见 3.2.20节。

       Create函数的第二个参数是一个指向RTPTransmissionParams对象的指针。详细描述见传输组件部分。因为可能会有很多的传输组件，所以你需要使用从RTPTransmissionParams继承的适合你的选择的类。对于基于IPv4的UDP传输来说，需要使用的类是RTPUDPv4TransmissionParams。假设我们要使用的RTP端口为8000，那么我们接下来的代码将是：

RTPUDPv4TransmissionParams transparams; Transparams.SetPortbase(8000);

现在我们准备好调用RTPSession的Create成员函数了。函数返回值放到整形变量status中，以便我们检查是否出错。如果返回值为负，表明出现了错误。关于错误码代表的意思描述可以通过调用函数RTPGetErrorString获得。

int status = session.Create(sessionparams, &transparams); if(status < 0) {    std::cerr<<RTPGetErrorString(status)<<std::endl;    exit(-1); }

       如果会话成功创建，那么下一步就是指定RTP和RTCP数据要发往的地址。这可以通过调用RTPSession的成员函数AddDestination来完成。该函数需要一个类型为RTPAddress的参数。RTPAddress类是一个抽象类，对于基于IPv4的UDP传输来说，应该使用的类是RTPIPv4Address。假设我们想发送数据给同一台主机的占用端口号为9000的进程，我们可以这样来写：

uint8_t localip[] = {127, 0, 0, 1}; RTPIPv4Address addr(localip, 9000); status = session.AddDestination(addr); if(status < 0) {    std::cerr<<RTPGetErrorString(status)<<std::endl;    exit(-1); }

       如果库编译时选择使用JThread，那么接收的数据是在后台处理的。如果没有在编译时使用Jthread支持或者在会话参数中指定了不使用线程池，那么你需要定时调用RTPsession的成员函数Poll来处理接收数据，并且在需要的时候发送RTCP数据。现在假设我们使用线程池。

       假设在一分钟的时间里，我们要发送包含20ms静默数据的包，并且我们想在收到其他人发送的包时能够显示，假设我们使用的是在RFC3551中定义的L8类型的数据，要使用的负载类型为96（【即payload type为96，一个很重要的参数：译注】）。首先我们设置几个默认参数：

session.SetDefaultPayloadType(96); session.SetDefaultMark(false); session.SetDefaultTimestampIncrement(160);

       接下来，我们创建一块内存来放160个静默采样数据以及一个RTPTime对象来指定20ms即0.020秒。为了知道什么时候一分钟时间到达我们应该保存当前时间：

uint8_t silencebuffer[160]; for(int i=0; i<160; ++i)    silencebuffer[i] = 128; RTPTime delay(0.020); RTPTime starttime = RTPTime::CurrentTime();

 

【to be continued！】