RealSystem SDK

一、RealSystem SDK

　　 RealServer和RealSystem的客户端都支持开放的流传输协议，并允许和其它基于标准流数据系统进行交互操作。RealSystem SDK提供开发者扩展和自定义RealSystem 的公共接口，该SDK允许开发者进行如下开发：
流式传输新数据类型
　创建RealSystem客户端应用
　自定义RealServer

1 SDK简介

　　 RealSystem是基于COM二进制标准，可使用任何编程语言开发RealSystem 组件。但为了简化跨平台开发，RealSystem与COM标准略有差异。
　　 RealSystem可执行文件和函数库位于SDK的/bin 目录下。开发包中播放器有RealPlayer与TestPlay。实现了RealPlayer的核心功能，但没有图形用户接口。可使用TestPlay来测试你开发的插件，也可以其为基础建立RealSystem客户端。测试程序时，服务器端可采用RealServer。
　　 插件结构是RealSystem的核心，它允许RealServer流式传输任何数据类型，也允许你定制RealServer。在Windows平台上，RealSystem 插件是32为动态链接库；在UNIX 与Macintosh平台上，是共享库。由于RealSystem提供几个跨平台服务，所开发的插件代码不特定针对操作系统。
　　 RealSystem头文件定义RealSystem接口。头文件包含函数变量与返回值的信息。头文件位于所下载SDK的include目录下。
　　 SDK中包含大量事例，你可使用这些事例文件作为模板建立RealSystem组件。应用这些代码需要C或C++的知识，这些代码是与平台无关的。事例在samples 目录下，包括头文件、C++ 文件、与工程文件。

2 SDK安装

　　 安装RealPlayer与TestPlay
运行RealPlayer安装程序，遵循如下步骤：
　　 1)、指定安装位置，缺省为c:/Program Files/Common Files/Real/
　　 2)、将PNEN3260.DLL, PNUI3260.DLL, and PNCRT.DLL放在c:/Program 　　 Files/Common Files/Real/Common目录下
　　 3)、将插件安装在c:/Program Files/Common Files/Real/Plugins
　　 4)、将codecs安装在c:/Program Files/Common Files/Real/Codecs
　　 5)、配置浏览器，使收到.ram 或 .rpm文件时激活RealPlayer
　　 为了使RealPlayer使用RTP数据传输格式代替标准的RDT从RealServer接收数据,在注册表中增加如下键：
　　 HKEY_CLASSES_ROOT
　　 　　 /Software
　　 　　 　　 /RealNetworks
　　 　　 　　 　　 /RealPlayer
　　 　　 　　 　　 　　 /6.0
　　 　　 　　 　　 　　 　　 /Preferences
　　 　　 　　 　　 　　 　　 　　 /UseRTP
　　 键值为1时，使用RTP传输数据；键值为0时，使用RDT传输数据。
　　 TestPlay是作为源代码提供的，在sdk/samples/intermed/testplay中。由于TestPlay与RealPlayer 使用相同的传输引擎、plug-ins和codecs ，如前所述安装RealPlaye最新版本，再编译。
安装、运行RealServer
　　 RealServer运行在UNIX 或Windows 32位操作系统上，运行它需要许可证（license key）。你将在下载RealServer时提供的e-mail里收到许可证，将其拷贝到RealServer设置文件中即可进行安装。
　　 RealServer可与任何支持MIME的网页服务器一起运行，在网页服务器中正确设置MIME使浏览器以RealPlayer播放RealSystem文件，而不是将文件下载到浏览器。下面几项是必须设置的：
　　 　　 application/smil
　　 　　 audio/x-pn-realaudio
　　 　　 audio/x-pn-realaudio-plugin

二 开发框架
　　RealSystem也称为RealMedia 结构 (RMA)，基于微软组件对象模型(COM)。RealSystem组件使用COM的 IUnknown::QueryInterface 方法暴露其接口，接口以"IRMA"前缀开始，IRMA表示"RealMedia接口结构"。RealSystem没有采用COM的全部，而只实现COM的一个子集提供跨平台操作。应用SDK，可建立下列类型的插件。
文件格式Plug-in： 该插件将某种数据类型转化为RealServer可流式传输的包。尽管RealServer主要使用文件格式插件传输， RealSystem 客户端也可用它们来播放本地文件。
　　1.播放Plug-in ： 该插件接收数据包，并在客户端回放。每个文件格式插件有一个相应的播放插件。
　　2.文件系统Plug-in ： RealServer与RealSystem客户端使用文件系统插件从数据源读取文件。例如，可建立一个插件从数据库中读取数据。
　　3.广播Plug-in ： 广播插件将现场数据转化为RealSystem包。尽管你可建立自己的广播插件，RealSystem包括将编码应用与RealServer标准广播插件结合的远程广播库。
　　4.监控Plug-in： 监控插件从RealServer注册表中检索系统信息，如当前连接客户数目、客户所请求的URL。

2．1 创建Plug-In事例
　　RealSystem没有使用Windows CoCreateInstance函数创建插件对象，而是采用RMACreateInstance, 一种"C-风格"入口点，暴露IRMAPlugin 接口，它使用IRMAPlugin 决定插件特征。入口点样例如下：
　　STDAPI
　　RMACreateInstance(IUnknown** ppExFileFormatObj) {
　　*ppExFileFormatObj=(IUnknown*)(IRMAPlugin*)new CMyExampleFileFormat();
　　if (*ppExFileFormatObj != NULL)
　　{
　　　　(*ppExFileFormatObj)-AddRef();
　　　　return PNR_OK;
　　　　}

　　　　return PNR_OUTOFMEMORY;
　　}

2．2 建立RealSystem对象
　　RealSystem组件可使用the C++ new操作符创建对象，为了使对象可传递到其他RealSystem组件，组件应该使用IRMACommonClassFactory。当RealSystem 初始化组件时，向组件传递一个指向系统上下文的指针，组件可使用这个指针调用IRMACommonClassFactory::CreateInstance并创建一个新RealSystem对象。如：
m_pClassFactory-CreateInstance(CLSID_IRMABuffer, (void**)&pStringObj);

2．3 使用IUnknown::AddRef和IUnknown::Release
　　因为RealSystem对象经常被其他RealSystem对象使用，对象必须正确实现引用计数。COM函数 IUnknown::AddRef 和 IUnknown::Release 控制引用计数，从而决定每个对象的生命期。下列规则说明RealSystem组件何时需要AddRef与Release 对象：
下列函数在返回前AddRef对象。当组件用完对象，必须释放。
　　RMACreateInstance
　　IUnknown::QueryInterface
　　IRMAFileSystemObject::CreateFile
　　IRMAFileSystemObject::CreateDir
　　IRMACommonClassFactory::CreateInstance
　　如组件接收对象为一个函数的参数，组件必须AddRef该对象。当组件用完对象，必须释放。如组件以C++ new操作符创建一个对象，组件必须AddRef 对象，用完后释放掉。

2．4 异步操作
　　RealSystem组件异步调用，使用响应接口返回对其调用的数据。例如，文件格式插件通过IRMAFileObject从文件系统插件请求文件数据，文件系统插件然后使用IRMAFileResponse返回所请求的数据。此异步结构允许当文件系统插件准备所请求的数据时文件格式插件执行其他操作。有了RealSystem的异步特性，插件能在其处理数据或等待其它组件响应时处理任何调用。

2．5 使用IRMABuffer创建数据缓冲区Data Buffers
　　IRMABuffer接口允许RealSystem对象创建COM引用管理的数据缓冲区。RealSystem对象通常使用这些缓冲区对象传递数据。例如，文件系统插件通过缓冲对象将流的头数据传递给文件格式插件。创建缓冲对象如下：
　　通过IRMACommonClassFactory创建IRMABuffer接口
　　调用IRMABuffer::SetSize 设置缓冲区大小，执行内存分配。
　　调用 IRMABuffer::GetBuffer 获得指向缓冲对象的指针。
　　使用 IRMABuffer::Set 向缓冲区写数据。
　　传递缓冲区指针给其他组件。
　　用 IUnknown::Release释放缓冲区对象。
　　当组件收到指向缓冲对象的指针时，调用IRMABuffer::GetSize 得到缓冲区大小，而调用IRMABuffer::Get 读取缓冲区数据。

2．6 使用IRMAValues 创建索引列表
　　象IRMABuffer, IRMAValues 接口广泛用在RealSystem系统中。IRMAValues 接口允许RealSystem组件创建名称、数值通用列表。IRMAValues 数值类型如下：
　　unsigned long
　　指向任意数据缓冲区的指针
　　指向以null结尾的C字符串缓冲区的指针
　　RealSystem组件创建IRMAValues 对象过程如下:
　　　　通过 IRMACommonClassFactory 创建IRMAValues接口
　　　　调用IRMAValues::SetPropertyULONG32、IRMAValues::SetPropertyBuffer、或 IRMAValues::SetPropertyCString 方法添加名称/数值。
　　传递对象指针给其他组件。
　　用 IUnknown::Release释放接口。

事例如下所示：
　　IRMAValues* pHeaderObj = NULL;
m_pClassFactory-　　　　CreateInstance(CLSID_IRMAValues, (void**)&pHeaderObj);
if (pHeaderObj != NULL)
　　{ IRMAPluginpHeaderObj-SetPropertyULONG32("StreamCount", 1);
　　　IRMAPluginpHeaderObj-SetPropertyBuffer("OpaqueData",
　　　pHeaderDataReadFromFile);

　　收到指向IRMAValues 接口的指针后，RealSystem组件可使用IRMAValues::GetProperty 根据名称检索数值，此处 为ULONG32、缓冲区、或 Cstring。组件可通过IRMAValues::GetFirstProperty与IRMAValues::GetNextProperty遍历列表。

2．7 使用IRMAPacket创建流数据包
　　RealSystem组件使用IRMAPacket接口创建数据包。例如，文件格式插件需要此接口为服务器准备流数据包；而客户端播放插件使用系统后通道向文件格式插件发送信息包 。RealSystem组件创建包过程如下：
　　通过IRMACommonClassFactory创建IRMAPacket 接口。
　　调用 IRMAPacket::Set 向包传递一个指向IRMABuffer 接口的指针，并定义包属性，如发送时间、自适应智能流管理规则。包属性有助于RealSystem有效传输。
传递指向其他组件的包指针。
　　以 IUnknown::Release释放包接口。
　　事例如下所示：
　　IRMAPacket* pPacketObj = NULL;
　　 m_pClassFactory-　　CreateInstance(CLSID_IRMAPacket, (void**)&pPacketObj);
if (pPacketObj != NULL)
{ IRMAPluginUINT32 deliveryTime = m_NextPacketDeliveryTime; 　　　　　　　　IRMAPluginUINT16 streamNoIRMAPlugin = MY_STREAM_NO;
　IRMAPluginUINT8 ASMFlags = RMA_ASM_SWITCH_ON;
　IRMAPluginUINT16 ASMRuleNo = 0;
　IRMAPluginpPacketObj-Set(pPacketDataReadFromFile, deliveryTime, streamNo, ASMFlags, ASMRuleNo);
　　收到指向包接口指针后，RealSystem组件用IRMAPacket::Get检索包数据。其他方法允许组件检索特定包属性。组件也可调用IRMAPacket::IsLost 决定包是否丢失。

2．8 设计插件
　　开发插件时，记住如下一些通用基本点：
　　1、尽可能保持插件简单、自足、通用。仔细考虑对通道时机和观众的影响。
　　2、记住RealSystem的异步特性。当在处理数据或等待其他对象响应时，你的插件必须能处理任何对它的调用。不要把插件编成依赖特定顺序。
　　3、努力使插件在未压缩时大小在300 KB 以下。
　　4、设计数据类型，满足所有用户，即28.8 Kbps 以上，随连接速度提高而扩展。
　　5、设计代码可在Macintosh、Windows,和UNIX 平台上运行。
　　6、不要依赖MMX 提高客户端回放质量。
　　7、如开发音频数据类型插件，使用RealSystem音频服务。此服务功能强大，可处理音频混合、采样、音量控制与即时声音。
　　8、由于RealPlayer和RealServer已本地化为多种语言，建议使用资源表等方便本地化。
　　9、为数据类型和插件提供优秀的文档。并把插件与文档分开，便于用户下载插件。
　　10、设计内容创建工具，考虑流式传输数据的速率。让设计者决定怎样制作内容。设计好的数据类型将使用自适应智能流特征给流速率分级。

2．9 编译插件
　　在开始开发插件前，应测试、编译几个例程。其中最简单的是"Hello World"插件，它在RealServer控制台上打印出 "Hello World"。"Hello World" 例程在/samples/intro/hellowld/hellowld.cpp 中。例程文件包含评论，解释每个函数功能。在 Windows上，RealNetworks 建议使用Microsoft的Visual C++ 4.2 或6.0。编译过程如下 ：
　　打开Microsoft Developer Studio程序。
　　在文件菜单中点击打开工作空间 。
　　在文件类型框选择Makefiles (*.mak)。
　　在欲测试的例程目录下选择make文件，并点击打开
　　在选择缺省工程设置框选择Release build或Debug build.。
　　点击 Build按钮或点击Build 菜单中Build 文件名。
　　也可在命令行编译，如：
　　　　nmake /f "exffplin.mak" CFG="exffplin - Win32 Debug" nmake /f 　　　　　　　　"exffplin.mak" CFG="exffplin - Win32 Release"
　　在UNIX 中，可采用gcc进行编译，如：
　　　　make -f unix/Makefile.

2．10 测试插件
　　下表是一个测试插件的基本指南：
　　确认所设计的扩展名文件类型与流MIME类型对应。
　　确认设计的文件类型播放正确。
　　确认窗口在播放器控制台内或外缺省位置正确。
　　如已实现，检验定位可正确工作。
　　确定暂停/恢复功能运行正常。
　　检验在流式传输中途停止运行正常。
　　确认在数据缓冲期间所期望行为发生。
　　确定内存用完时处理正确。
确认在较慢的机器上运行可接受。
看看播放器是否能同时在一台机器上播放几个流。
播放长时间流来测试每个包内存泄漏情况。