UPnP编程指南

Intel®SDK for UPnP Devices™Programming Guide™Intel® SDK for UPnP Devices Version 1.2.1November 2002™Intel®SDK for UPnP Devices编程指南™Intel® SDK for UPnP Devices Version 1.2.1November 2002翻译说明：由于要研究UPnP协议并在Linux下实现其部分设备的功能，在阅读Intel SDK自带的英文文档时，顺便把该篇入门文章翻译出来，本翻译是本人的第一份完整的技术翻译文档，其中有些词的翻译恐有不妥之处，有疑问的地方以英文文档为准，英文原文在$(LIBUPNP)/upnp/doc/UPnP_Programming_Guide.PDF.本文取自libupnp-SDK-1.3.1版本下的文档，文档中标记还是1.2.1，估计是开发包升级而文档没有升级吧，暂且以此学习之。

本文档翻译为个人兴趣爱好，尚未联系原作者取得许可，也不对文中任何内容和翻译的问题负责，只作学习交流之用，如有好的建议或意见可与我联系，本文档可以任意的复制，分发，传播和改进。

详情参照GPL。

2006年7月1日简体中文第一版译者：Chaoshua ［chaoshua@]目 录1、概述 (3)1.1、UPnP概述 (3)1.1.1、发现（Discovery) (3)1.1.2、描述（Description） (4)1.1.3、控制（Control） (4)1.1.4、事件（Eventing) (4)1.1.5、表示（Presentation） (5)1.1.6、控制点和设备的交互 (5)1.2、SDK架构 (6)1.2.1、设备/控制点程序 (7)1.2.2、SDK API (7)1.2.3、SSDP (7)1.2.4、迷你Web服务器（Mini Web Server) (7)1.2.5、GENA (7)1.2.6、SOAP (8)1.2.7、HTTP (8)1.2.8、迷你服务器 (8)1.2.9、ThreadUtil库（TreadUtil Library) (8)1.3、虚拟目录 (8)2、编写一个UPnP设备 (10)2.1、安装和初始化 (10)2.1.1、初始化SDK (10)2.1.2、设置根目录 (11)2.1.3、注册一个根设备 (11)2.1.4、设备相关初始化 (12)2.1.5、发布设备公告（Advertising the Device) (12)2.2、处理请求 (12)2.2.1、订阅请求 (13)2.2.2、获取变量请求 (14)2.2.3、动作请求 (15)2.3、发送事件（Sending Events） (17)2.4、关闭（Shutting Do w n） (18)3、编写一个UPnP控制点 (19)3.1、安装和初始化 (19)3.1.1、SDK初始化 (19)3.1.2、控制点应用相关的初始化 (20)3.1.3、控制点注册 (20)3.2、搜索感兴趣的事物 (20)3.3、检索描述(R etrieving Descriptions) (22)3.4、监视事件(Watching for Events) (22)3.5、调用动作(Invo k ing Action) (23)3.6、关闭（Shutting Do w n) (25)1、概述UpnP允许不经过用户干预而自动发现和控制网络上其他设备提供的可用服务。

设备（Devices）作为服务器向客户端发布自己的服务。

客户端系统，称为控制点（Control Points),能够搜索网络上特定的服务。

当他们发现拥有他所期望的服务的设备时，他们就能够检索关于设备的服务的更详细的描述信息并在这个控制点上与其进行交互。

本文档给出UPnP的概述并给出如何编写设备和控制点的例子，完整的描述请参见Intel® SDK for UPnP Devices API函数，参考SDK中包含的《Intel® SDK for UPnP™Devices v1.2 API R eference》。

开发包（SDK）中也提供了控制点和设备的示例程序，对于如何编译和运行这些示例程序，请参看开发包对应sample目录下的R EADME文件。

1.1、UPnP概述本节简要描述UPnP，对于更详细的信息，请参见《Universal Plug and Play Device Architecture》，该文档可在UPnP论坛找到：/resources/documents.asp 。

UpnP包含一下五个基本部分／阶段（Phases)：1、发现（Discovery)：这是第一阶段，控制点搜索设备和服务，类似的，设备广播他所能提供的服务通告。

2、描述(Description)：一旦控制点发现了他感兴趣的设备或服务，他将请求该设备提供该设备本身、其他组件成员设备以及他们提供的服务的完整描述。

3、控制(Control)：本阶段允许控制点通过改变设备的状态来控制设备上提供的一个或多个服务。

4、事件(Eventing)：本阶段允许控制点与其感兴趣的服务状态保持同步，控制点向事件服务器订阅一个特定的服务，当该服务状态改变时，接收事件通告。

5、表示(Presentation)：表示阶段允许设备保持一份文档，该文档采用标准HTML语言编写，他可以是该设备的一个用户界面。

接下来的部分将对这五个阶段分别进行描述。

1.1.1、发现（Discovery)在发现阶段，控制点采用SSDP（简单服务发现协议：Simple Service Discovery Protocol)发现设备和服务而设备采用SSDP向控制点宣告他们的存在。

SSDP采用HTTP的一种变体以UDP多播的方式来进行广播，并采用另一种HTTP变体通过UDP单播来进行应答。

一个设备可能包含其他设备，每个设备都有他自己的服务。

设备采用其类型和一个唯一的标志符来进行标识。

服务则用他们的类型来标识。

为了搜索网络上的设备或服务，控制点使用UDP多播包向地址239.255.255.250:1900发送HTTP的M－SEA R CH命令。

任何网络上服务控制点搜索条件的设备发回一个UDP单播进行应答，该应答中包含了指向其描述文档（参加1.1.2节）的U R L地址。

如果一个控制点收到一个或多个可接受的应答，他将转入描述阶段(description phase).一个控制点发出一个搜索请求时，该请求在SSDP头中包含了他愿意等待的时间长度。

匹配的设备将在响应之前随机等待一段时间，该时间介于0和控制点指示的时间之间。

如果控制点在他的搜索时间超时之前没有收到任何应答，他就认为当前网络上没有匹配的设备。

设备没必要等待控制点来搜索他们的服务。

他们可以采用向239.255.255.250:1900多播地址发送SSDP的NOTIF Y命令来宣告他们的设备可用性。

当控制点获得该NOTIF Y多播，他们就可以使用标准的HTTP GET命令来向NOTIF Y消息中提供的U R L地址发出请求以获得设备的描述文档。

设备必须在他们的服务不可用时发出一个通告信息。

1.1.2、描述（Description）当控制点定位一个服务后他希望了解更多，因而他将请求描述文档。

描述是一个X ML文档用来描述一个设备，包括：●制造商信息，版本，其他。

●可被设备采用的图标的U R L地址。

●嵌入式设备列表。

●设备提供的服务列表。

想得到关于描述文档的格式的更多信息，请参见文档《Universal Plug and Play Device Architecture》（《通用即插即用设备架构》）。

控制点采用基于TCP的HTTP来请求描述文档。

控制点执行标准的HTTP GET命令（与检索Web页面类似）。

在服务器端，设备运行一个标准的HTTP服务－－可以是完全的Web服务器如Apache也可以是迷你服务器。

描述文档中的很多条目都是U R L地址。

这些条目也使用HTTP/TCP 检索。

1.1.3、控制（Control）一旦一个控制点发现了一个设备并且检索到他的描述文档，他可能需要控制该设备包含的一个或多个服务。

简单对象访问协议（SOAP：Simple Ob j ect Access Protocol）允许一个访问点查询或改变服务状态表中的元素。

SOAP使用基于TCP传输HTTP的POST和M－POST命令。

SOAP使用X ML来说明采取的活动。

控制点如描述文档里指定的那样为服务创建X ML文档并将其提交给控制U R L。

控制点能请求服务状态表中的当前值并改变他们。

在服务器端，控制服务器等待控制请求。

控制服务器是一个实现了SOAP协议的类似于HTTP 服务器的服务器。

一个设备能运行多于一个控制服务器，这取决于设备提供的服务的组合。

1.1.4、事件（Eventing)一个控制点发现一个设备并检索到他的描述后，他能保持设备提供的服务的状态信息。

感兴趣的控制点为特定服务订阅了从描述文档中发现的设备事件提醒服务U R L。

一个事件提醒在任何服务状态改变的时候发送给控制点，即使这次改变是由该控制点产生的。

订阅和退订请求使用HTTP/TCP连接到事件U R L，该U R L包含在服务的描述文档中。

在订阅时，控制点指定一个事件提醒的U R L。

事件以HTTP/TCP方式到达为服务注册的U R L。

事件提醒包含一个小型的X ML文档，该文档描述了实际的事件，如服务状态表的改变。

在服务器端，一个事件服务器等待订阅和退订请求。

事件服务器是一个类HTTP服务器的实现通用事件提醒架构协议（GENA：General Event Notification Architecture）的服务器。

一个设备将可能根据设备提供的服务的组合（情况）必须运行多于一个的事件服务器。

1.1.5、表示（Presentation）由于设备需要或支持用户交互，在表示阶段一个控制点能下载一个为设备描述用户界面的HTML文档。

这是一个能提供一种控制或状态显示的标准HTML文档。

如检索描述文档一样，检索表示文档的协议也是基于TCP的HTTP协议。

控制点使用描述文档中包含的表示U R L来请求表示文档。

不是所有设备都拥有表示文档也不是所有控制点能够显示包含复杂HTML对象如框架，嵌入式J ava applets等的表示文档。

1.1.6、控制点和设备的交互下图显示了前面章节描述的在UPnP各阶段控制点和设备之间进行交互的（动作）序列。

图后对每一步进行了描述。

这些描述指示出了控制点和设备采用的API调用和SDK中产生的网络包类型。