2005年10月20日

文章翻译免责声明
本UPnP文档最初用英文发布,并仅有英文版本通过了UPnP论坛的正式审核。
文章已采用翻译服务和翻译技术在英文版本的基础上翻译成目标语言版本,
UPnP Implementers Corporation及其相关机构不对翻译版本做出任何保证,也
不为由翻译不准确所导致的直接或间接损失承担责任。在使用翻译版本中所包括
的技术信息时,用户同意UPnP Implementers Corporation和UPnP论坛成员对于
英文到目标语言翻译的不完整、或不准确导致的全部或部分损失不承担任何责
任。此外,用户同意应保护UPnP Implementation Corporation免受由语言翻译
而带来的伤害。
UPnP™设备架构
1.0 版,2000 年6 月8 日上午10:41
版权所有© 1999-2000 UPnP™论坛贡献成员。所有权利受到保护。
目录
介绍
0. 寻址
1. 发现
2. 描述
3. 控制
4. 事件触发
5. 展示
术语表
介绍
何为UPnP?
UPnP 是针对智能家电、无线设备以及各种外观尺寸的个人电脑的普遍对等
(peer-to-peer)网络连接而设计的一种架构。它旨在为家庭、小型企业、公共
场所中或连接到互联网的ad-hoc 网或未管理网络提供易于使用、灵活且基于标
准的连接。UPnP 是一个充分利用TCP/IP 和Web 技术的分布式开放型网络体
系结构,除能够在家中、办公室和公共场所联网设备之间的完整控制和数据传输
之外,还可建立无缝紧密的连接网络。
UPnP 不仅仅只是即插即用外设模式的简单扩展。它设计用于支持零配置、
“不可见”联网,以及对众多厂商的广泛设备类型的自动发现。这就意味着,一
台设备能够动态加入一个网络,获取一个IP 地址,通报其功能,以及了解其它
设备的存在和功能。DHCP 和DNS 服务器为可选服务器,仅当他们在网上存在
时可以使用。最后,设备能够顺利地自动离线,而不会造成任何不期望的影响。
UPnP 充分利用了包括IP、TCP、UDP、HTTP 和XML 在内的互联网组件。
正如互联网那样,合约基于陈述性的有线协议,以XML 来表达,并通过HTTP
进行传输。IP 网间协议凭借其以下已经被验证的能力而成为UPnP 的一个有力
选择:跨越不同的物理媒体、支持实际的多厂商互操作,以及实现与互联网、大
量家庭和办公室内联网的协作融合等等。UPnP 的设计明确用于支持这些环境。
此外,当成本、技术或传统因素等阻止与UPnP 连接的媒体或设备运行IP 协议
时,UPnP 还可通过桥接方式支持运行非IP 协议的媒体。
何为UPnP 的“通用性”?不使用设备驱动程序;取而代之的是通用协议。
UPnP 网络不依赖于任意媒体。UPnP 设备可以在任何操作系统上采用任何编程
语言来实现。UPnP 并未针对运行于控制点上的应用而指明或限制API 的设计;
操作系统厂商可以创建满足其客户需求的API。UPnP 通过使用浏览器和传统应
用程序控制来使厂商能够控制设备的用户界面(UI)并实现交互。
UPnP 论坛
UPnP 论坛是一项业界发起的计划,致力于在众多不同厂商的独立设备和个
人计算机之间轻松建立强健的连接。UPnP 论坛寻求开发描述设备协议和基于
XML 的设备模式的标准,以便在一个可伸缩的网络环境中实现设备间互操作性。
UPnP 论坛负责监督针对一致性设备的一项标识计划。
UPnP 论坛设立了具体专业知识方面的工作委员会。这些工作委员会负责制
定建议设备标准、构建范例实施,以及构建适当的测试套件。本文指出了属于
UPnP 论坛工作委员会范围的具体技术决定。
UPnP 厂商能够凭借共享知识产权和标识计划的优势和互操作性的信心构
建出符合一致性要求的设备。如不参加标识计划,厂商还可以构建符合UPnP
设备架构的设备,而不用通过正式标准程序。如果厂商构建非标准设备,将由他
们自己制定技术决策,而非UPnP 论坛工作委员会。
本文内容
此处包含的UPnP 设备架构(原称作DCP 框架)定义了控制器或控制点以
及设备之间的通信协议。UPnP 针对发现、描述、控制、事件触发和展示采用了
以下协议栈。
UPnP 厂商[ 紫色]
UPnP 论坛[ 红色]
UPnP 设备架构[ 绿色]
SOAP[蓝
色] HTTPMU (多播) [黑
色]
GENA[藏
青色]
SSDP[蓝
色]
HTTPU (单播)
[黑色]
SSDP[蓝
色]
HTTP[黑
色]
HTTP[黑
色]
GENA[藏
青色]
UDP[黑色] TCP[黑色]
IP[黑色]
在最高一层,消息在逻辑上仅仅包含关于厂商设备的UPnP 厂商特定信息。
移至下一层协议栈后,厂商内容由UPnP 论坛工作委员会定义之信息提供。来
自以上各层的消息存储在UPnP 特定协议中,并在本文中进行了定义。之后,
以上消息通过采用简单服务发现协议(SSDP)、通用事件通知架构(GENA)
和简单对象访问协议(SOAP)来进行格式化。然后消息通过运行于UDP 上的
多播或单播类HTTP,或是运行于TCP 上的标准HTTP 进行传输。最终,以上
所有消息均通过IP 进行传输。本文其余部分详细描述了这些协议层中每层的内
容和格式。为便于参考,以上[方括弧]中的颜色指出了全文各协议所定义的具体
消息成份。
UPnP 网络互连的基础是IP 寻址。每台设备均必须配有动态主机配置协议
(DHCP)客户端,并在设备首次与网络连接时搜索DHCP 服务器。如果DHCP
服务器可以使用,即网络处于管理状态,则设备必须采用分配给它的IP 地址。
如果没有DHCP 服务器可用,即网络处于未管理状态,则设备必须利用Auto IP
来获取一个地址。简言之,Auto IP 说明了一台设备如何从一组保留地址中智能
地选出一个IP 地址,以及如何能够在处于管理和未管理状态的网络间轻松移动。
如果设备在DHCP 交易过程中获得了一个域名(例如通过一台DNS 服务器或通
过DNS 转发),则设备应当在后来的网络操作中采用该名称;否则即应采用其
IP 地址。
如果获取了一个IP 地址,则UPnP 网络的第1 步是发现。在将一个设备添
加到网络上之后,UPnP 发现协议允许该设备向网络中的控制点宣告其服务。同
样,当一个控制点被添加到网络后,UPnP 发现协议允许该控制点在网上搜索感
兴趣的设备。两种情况下的根本信息交换均为一个发现消息,包含有关该设备或
其服务之一的一些基础信息(例如其类型、标识符和指向更详细信息的一个指
针)。UPnP 发现协议基于简单服务发现协议(SSDP)。以下发现部分说明了
设备如何进行宣告,控制点如何搜索,以及有关发现消息格式的详细信息。
UPnP 网络中的第2 步是描述。控制点在发现一个设备之后仍然对其知之甚
少。为了使控制点了解到更多关于设备及其能力的信息或与设备进行交互,则控
制点必须取得来自该设备在发现消息中所提供之URL 的设备描述。设备可能包
含其它逻辑设备,以及功能单元或服务。对于设备的UPnP 描述通过XML 来表
达,并包括诸如模型名称和号码、序列号、制造商名称和厂商专门网站URL 等
专门针对厂商的制造商信息。该描述还包括一列任意的嵌入式设备或服务,以及
用于控制、事件触发和展示的URL。对于每项服务,此描述均包括一列命令或
动作,而服务(参数或变量)对于每个动作做出响应;针对服务的描述还包括一
列变量;这些变量模型化服务在运行时的状态,并通过数据类型、范围和事件特
征进行描述。以下关于描述的部分说明了设备如何被描述,以及这些描述如何被
控制点取得。
UPnP 网络中的第3 步是控制。当一个控制点取得设备描述后,该控制点可
将动作发至一个设备的服务。为此,控制点将一条适当的控制消息发至服务的控
制URL(在设备描述中提供)。控制消息同样利用简单对象访问协议(SOAP)
通过XML 来表达。类似于功能调用,该服务针对控制消息返回了所有的专门动
作取值。动作的效果可以通过描述服务运行时状态的变量进行描述。以下关于控
制的部分说明了有关动作、状态变量以及控制消息格式的描述。
UPnP 网络的第4 步是事件触发。针对服务的UPnP 描述包括一个服务响应
的动作列表,以及一个对服务器运行时状态进行展示的变量列表。在这些变量变
更时服务会发布更新,一个控制点可以预订接收此信息。服务通过发送事件消息
来发布更新。事件消息包含一个或多个状态变量名和这些变量的当前值。这些消
息同样通过XML 来表达,并采用通用事件通知架构(GENA)格式。当控制点
首次预定时,会发送一个特殊的初始事件消息;此事件消息包含所有事件变量的
名称和值,并允许订阅者对服务状态模式进行初始化。为了支持拥有多个控制点
的环境,事件触发设计用于将任何动作的效果通知所有控制点。因此,所有订阅
者均会收到全部的事件消息。订阅者收到关于所有已变更事件变量的事件消息,
此事件消息无论状态变量为何改变都被发送(由于响应一个要求动作,或由于服
务建模状态的变更)。以下关于事件触发的部分说明了事件消息的预订和格式。
UPnP 网络中的第5 步是展示。如果设备有用于展示的URL,那么控制点
就可以通过此URL 取得一个页面,在浏览器中加载该页面,并且根据页面的功
能,支持用户控制设备和/或浏览设备状态。每一项完成的程度取决于展示页面
和设备的具体功能。以下关于展示的部分说明了关于取得一个展示页面的协议。
读者对象
本文的读者对象包括UPnP 设备厂商、UPnP 论坛工作委员会的成员,以及
需要了解UPnP 协议技术细节的其他人员。
本文假定读者熟悉HTTP、TCP、UDP 和IP 协议族;本文无意对这些协议
进行说明。本文还假定多数读者并不了解XML。虽然它并非一份XML 指南,但
考虑到XML 与UPnP 的紧密关系,文章仍详细介绍了XML 相关问题。本文没
有假定读者了解各种编程或脚本语言。
要求Vs 推荐使用
本文中,特性被描述为要求、推荐使用或可选,表示如下:
要求(或必须)
这些基本特性必须依照UPnP 来实现。
推荐使用(或应当)
这些特性添加了UPnP 支持的功能,应当进行实现。推荐使用的特性充
分利用了UPnP 的能力,通常不会造成成本的大幅提高。注意,对于一
致性测试而言,如果要实施一个推荐特性,则该特性必须满足指定要求,
以符合这些准则。一些推荐使用的特性在将来可能变成要求特性。
可选(或可能)
这些特性既非UPnP 要求,也非其推荐使用,然而一旦实现,则其必须
满足指定要求,以符合这些准则。这些特性在将来不可能成为要求特性。
术语缩写
术语缩写含意
ARP 地址解析协议
DHCP 动态主机配置协议
DNS 域名系统
FXPP 灵活的XML 处理框架
GENA 通用事件通知架构
HTML 超文本标记语言
HTTPMU 基于UDP 的HTTP 多播
HTTPU 基于UDP 的HTTP(单播)
ICANN 指定名称和编号的互联网公司
SOAP 简单对象访问协议(SOAP)
术语缩写含意
SSDP 简单服务发现协议
UPC 通用产品代码
UPnP UPnP
URI 统一资源标识符
URL 统一资源定位器
URN 统一资源名称
UUID 全球唯一标识符
XML 扩展标记语言
参考和资源
RFC2616
HTTP:超文本传输协议1.1IETF RFC。
<http://search.ietf.org/rfc/rfc2616.txt?number=2616>.
RFC2279
UTF-8,ISO 10646 的一种转化形式(字符编码)。IETF RFC。
<http://search.ietf.org/rfc/rfc2279.txt?number=2279>
XML
扩展标记语言,W3C 推荐。<http://www.w3.org/XML/>.
本文每部分均包含关于特定主题资源的额外信息。
致谢
微软UPnP 团队对于代表UPnP 论坛指导委员会和UPnP 厂商团体的众多
技术评论家所给予我们的鼎力相助深表感谢。这些评论家凭借其丰富的技术信
息、远见卓识和聪明才智为撰写本文提供了大力支持。
我们同样感谢微软的软件工程师、测试员和计划经理,他们提供了宝贵的回
馈和技术内容,以确保本文信息的准确性和及时性。
0. 寻址
寻址是UPnP 网络的第0 步。设备通过寻址来获得一个网络地址。寻址支持发
现(第1 步,控制点发现感兴趣的设备)、描述(第2 步,控制点对设备功能
进行了解)、控制(第3 步,一个控制点将命令发至设备)、事件触发(第4
步,控制点监听设备状态的变化),以及展示(第5 步,控制点显示设备的一个
用户界面)。
UPnP 网络的基础在于IP 寻址。每个设备均必须配有一个动态主机配置协
议(DHCP)客户端,并在此设备首次与网络相连时搜索一台DHCP 服务器。
如果有一个可用的DHCP 服务器,即网络处于管理状态,则此设备必须采用分
配给它的IP 地址。如果没有可用的DHCP 服务器,即网络处于未管理状态,则
此设备必须利用自动IP 寻址(Auto-IP)来获取一个地址。
Auto-IP 定义了设备如何:(a) 在DHCP 不可用时做出决定,以及(b) 从一
组本地链接的IP 地址中智能地选出一个IP 地址。这种地址分配方法使设备能够
在处于管理和未管理状态的网络之间轻松移动。
此部分所描述的操作在下列参考文件中得到了进一步阐明。如果本文和参考
文件存在冲突之处,则始终以参考文件为准。
0.1 寻址:决定是否采用Auto-IP
支持AUTO-IP 并针对动态地址分配而配置的一个设备,通过发出一条
DHCPDISCOVER 消息向DHCP 请求IP 地址开始运行。此DHCP 客户端所应
监听DHCPOFFERS 的时间总长取决于具体实现。如果在此期间收到一条
DHCPOFFER,则此设备必须继续进行动态地址分配。如果没有收到有效的
DHCPOFFERS,则此设备可以自动配置一个IP 地址。
0.2 寻址:选择一个地址
要利用Auto-IP 来自动配置一个IP 地址,设备采用了一个取决于具体情况
的算法,以便在169.254/16 范围内选出一个地址。此范围内的前后256 个地址
需要保留,不得使用。
接下来必须对选定地址进行测试,以确定该地址是否已被使用。如果该地址
已被其它设备使用,则必须选出和测试另一地址,重试次数取决于具体的实现。
地址的选择应当随机进行,以免在多个设备试图分配地址时产生冲突。
0.3 寻址:测试地址
为了测试选出的地址,设备必须采用地址解析协议(ARP)来进行探测。地
址解析协议(ARP)探测是一个ARP 请求,其中设备硬件地址用作发送者的硬
件地址,而发送者的IP 地址设为多个0。设备继而会监听对于该ARP 探测,或
同一IP 地址的其它ARP 探测所做出的响应。如果发现任意一个ARP 数据包,
则此设备必须考虑正在使用的地址,并尝试一个新地址。
0.4 寻址:定期检查动态地址的可用性
自动配置了IP 地址的设备必须进行定期检查,以确定一台DHCP 服务器的
存在。这一过程通过发送DHCPDISCOVER 消息来完成。该项检查的频度取决
于具体实现,然而每5 分钟检查一次将可维持要求网络带宽和连接性维护之间的
平衡。如果收到DHCP 信息,设备必须继续进行动态地址分配。一旦DHCP 指
定地址到位,则设备即可释放该自动配置的地址,或者也可选择将该地址保留一
段时间以维持连接性。
要从一个IP 地址转到一个新地址,设备必须取消所有已经公开的宣告并重
新发布新宣告。关于发现的部分说明了宣告及其取消。
0.5 寻址:设备命名与DNS 交互
设备一旦具有了一个有效的网络IP 地址,即可通过该地址在该网络中被定
位和访问。可能在某些情况下用户需要寻找和识别一个设备。在这些情况下,对
使用者而言,设备的一个友好的名称要比一个IP 地址易于使用得多。
此外,名称远比IP 地址要稳定。通过名称查询设备的客户在设备的IP 地址
变更时无需做出任何修改。设备的DNS 名称对其IP 地址的映射可以按照
RFC2136 被手动或动态输入DNS 数据库。支持动态DNS 更新的计算机和设备
能够将其DNS 记录直接记入DNS 中。同时还有可能配置一台DHCP 服务器来
代表这些DHCP 客户端登记DNS 记录。
0.6 寻址:名称到IP 地址的解析
当一台计算机需要访问另一台以DNS 名称来指明的设备时,它要发现其IP
地址。计算机按照RFC1034 和1035 将一个DNS 询问提交至预先配置的DNS
服务器,并从包含目标设备IP 地址的DNS 服务器收到一个响应。计算机能够静
态地采用DNS 服务器列表进行预先配置。或者,计算机还能通过DHCP 采用
DNS 服务器列表进行配置,或在地址分配之后通过一条DHCPINFORM 消息进
行配置。
0.7 寻址参考
Auto-IP
在一个Ad-Hoc IPv4 网络中自动选出一个IP 地址。IETF 草案。
<http://search.ietf.org/internet-drafts/draft-ietf-dhc-ipv4-autoconfig-05.tx
t>.
RFC1034
域名――概念与工具。IETF RFC。
<http://search.ietf.org/rfc/rfc1034.txt?number=1034>.
RFC1035
域名――实施与规范。IETF RFC。
<http://search.ietf.org/rfc/rfc1035.txt?number=1035>.
RFC2131
动态主机配置协议IETF RFC。
<http://search.ietf.org/rfc/rfc2131.txt?number=2131>.
RFC2136
域名系统中的动态更新。IETF RFC。
<http://search.ietf.org/rfc/rfc2136.txt?number=2136>.
由DHCP 客户端和服务器进行的动态DNS 更新
DHCP 和DNS 间的交互。IETF 草案。
<http://search.ietf.org/internet-drafts/draft-ietf-dhc-dhcp-dns-12.txt>.
1. 发现
发现是UPnP 网络中的第1 步。发现紧随设备获取一个网络地址的寻址(第0
步)之后。控制点通过发现来找到感兴趣的设备。发现支持描述(第2 步,控制
点对设备能力进行了解)、控制(第3 步,一个控制点将命令发至设备)、事件
触发(第4 步,控制点监听设备状态的变化),以及展示(第5 步,控制点展
示设备的一个用户界面)。
发现是UPnP 网络中的第1 步。当设备被添加到网络后,UPnP 发现协议允
许该设备向网络中的控制点宣告其服务。同样,当一个控制点被添加到网络后,
UPnP 发现协议允许该控制点在网上搜索感兴趣的设备。两种情况下的基本交换
信息均为一条发现消息,其中包含关于该设备或其服务之一的少量基础性的细节
信息(例如其类型、标识符和指向更详细信息的一个指针)。
当一个新设备被添加到网络后,它会多播大量的发现消息来宣告其嵌入式设
备和服务。所有感兴趣的控制点均能监听标准的多播地址,以获取宣布新能力可
用的通知。
同样,当一个新控制点被添加到网络后,它会多播一条发现消息来搜索感兴
趣的设备、服务,或同时搜索二者。所有设备均必须监听这些消息的标准多播地
址,同时必须在其任何嵌入式设备或服务与发现消息中的搜索标准相符合时做出
响应。
需要重申的是,控制点发现感兴趣的设备可能是由于该设备发送了宣告自己
的发现消息,或由于该设备对一条搜索设备的发现消息做出了响应。在任何一种
情况下,如果控制点对一个设备感兴趣并想了解关于该设备的更多信息,则该控
制点必须采用发现消息中的信息来发送一条描述询问消息。关于描述的部分对描
述消息做了详细说明。
当设备离线后,它应当多播大量的发现消息来撤消其早期宣告,有效地宣布
其嵌入式设备和服务将不再可用。
为了限制网络拥塞,每个IP 数据包针对每条多播消息的有效期限(TTL)
必须默认为4,且应可以配置。
发现在帮助实现使用不同版本UPnP 网络的设备与控制点的互操作性方面
有着至关重要的作用。UPnP 设备架构(在此定义)用主、副两个版本来描述,
通常写作major.minor,且两者均为整数。副版本改进的部分必须兼容属于同一
主版本的前副版本。主版本改进的部分不要求是前版的扩展集,并且不保证向后
兼容。版本信息在发现和描述消息中进行传送。在前者中,每条发现消息均包括
设备支持的UPnP 网络版本。作为备份,后者同样包括相同的信息。此部分说
明了发现消息中版本信息的格式和针对发现消息的具体要求,以维持与副版本改
进部分的兼容性。
标准的多播地址,以及宣告、搜索和撤消机制由简单服务发现协议(SSDP)
来进行定义。此节其余部分详细说明了简单服务发现协议(SSDP),并列举了
设备如何宣告和撤消其宣告,以及控制点如何搜索和设备如何响应等等。
1.1 发现:宣告
当设备添加到网络后,UPnP 发现协议允许该设备宣告其服务给控制点。这
一点通过将发现消息多播到一个标准地址和端口而得以实现。控制点监听此端口
来探测新功能何时在网上可用。为了宣告其全部能力范围,一个设备对应其每个
嵌入式设备和服务而需要多播一系列的发现消息。每条消息均包含关于嵌入式设
备(或服务)的专门信息,以及关于其内含设备的信息。消息应包括直到宣告过
期的持续时间;如果设备仍然可用,则应将宣告一并重新发送(带有新的持续时
间)。如果设备不再可用,则设备应当明确撤消其宣告,然而如果设备本身不能
撤消,则宣告将自动过期。
1.1.1 发现:宣告协议与标准
为了发送(和接收)宣告消息,设备(与控制点)采用了以下总体UPnP
协议栈的子集。(总体UPnP 协议栈在本文开始处列出。)
UPnP 厂商[ 紫色]
UPnP 论坛[ 红色]
UPnP 设备架构[绿色]
HTTPMU(多播) [黑色]
GENA[藏青
色]
SSDP[蓝色]
HTTPMU(多播)[黑色]
UDP[黑色]
IP[黑色]
在最高层,发现消息包含特定厂商信息,例如用于设备描述的URL 和设备
标识符。在协议栈接下来的一层,通过来自UPnP 论坛工作委员会的信息(如
设备类型)对厂商内容进行了补充。来自以上各层的消息存储在UPnP 特定协
议中,并在本文中进行了定义。接下来,以上消息通过一个HTTP 的多播变量
进行传送,该变量已通过采用通用事件通知架构(GENA)方法和标头,以及简
单服务发现协议(SSDP)标头而得以扩展。HTTP 消息通过IP 经UDP 进行传
送。为便于参考,以上[方括弧]中的颜色显示了何种协议定义下面发现消息中的
具体标头与值。
1.1.2 发现:宣告:设备可用――ssdp:alive NOTIFY
在设备被加入网络时,它采用多播方式发送发现消息,以告知设备包含的根
设备信息,所有嵌入式设备以及它包含的服务。每个发现消息都包含四个主要组
成部分:
1. 在NT 标头中发送的潜在搜索目标(例如设备类型);
2. 在USN 标头中发送的宣告复合标识符;
3. 在LOCATION 标头中发送的关于设备更多信息的URL 地址(或有关服
务的内含设备),以及
4. 在CACHE-CONTROL 标头中发送的宣告合法持续时间。
为了告知其能力,设备选择多播多个发现消息。特别是,根设备必须多播:
• 对于根设备,存在三种发现消息。
NT USN *
1 根设备UUID ** 根设备的UUID
2 设备类型:设备版本根设备的UUID 和::和设备类型:设备版本
3 UPnP:rootdevice 根设备的UUID 和::和UPnP:rootdevice
• 对于嵌入式设备,存在两种发现消息。
NT USN *
1 嵌入式设备UUID ** 嵌入式设备的UUID
2 设备类型:设备版本嵌入式设备的UUID 和::和设备类型:设备版本
• 每种服务响应一次。
NT USN *
1 服务类型:服务版本内含设备的UUID 和::和服务类型:服务版本
* 注意USN 标头前缀(位于双冒号前)必须与设备描述中的UDN 元素值相匹
配。(描述部分主要说明UDN 元素。)
** 注意UT 标头值必须与设备描述中的UDN 元素值相匹配。
如果一个根设备有d 个嵌入式设备,s 个嵌入服务,但是只包含k 个不同的
服务类型,这将会发出3+2d+k 次请求。这些宣告向感兴趣的控制点描述了设备
的所有能力。这些消息必须作为一个系列一起发出,具有大约相接近的过期时间,
发送的顺序无关紧要,但是不能对单个消息进行刷新或取消操作。
选择一个适当的持续期是在最小化网络流量和最大化设备状态及时更新之
间求得一个平衡。相对较短的持续时间(最短1800 秒)可以保证控制点在牺牲
额外网络流量的情况下获得设备的当前状态;持续期较长(按照时间顺序)会损
失设备状态的刷新速度,但是可以大大减少网络流量。一般而言,设备厂商应该
选择一个与预期设备使用情况相对应的值:希望短期内成为网络组成部分的设备
持续时间短;希望成为网络长期成员的设备持续时间长。
鉴于UDP 的不可靠特性,设备应该多次发送上述设备发现消息。而且为了
排除控制点无法收到设备或服务宣告的可能性,设备应该定期重新发送它的宣告
(参见:下面的CACHE-CONTROL)。注意:UDP 信息包的长度有一定的限
制(在有些实现方案中可能只有512 字节),并且不保证以上3+2d+k 条消息以
特殊顺序到达。
在设备加入网络时,它必须用NOTIFY 方法发送一个多播请求,并且NTS
标头中的ssdp:alive 采用以下格式。用斜体表示的值为实际值的占位符。
NOTIFY * HTTP/1.1
HOST: 239.255.255.250:1900
CACHE-CONTROL:max-age = seconds until advertisement expires
LOCATION:URL for UPnP description for root device
NT:
NTS:ssdp:alive
SERVER:OS/version UPnP/1.0 product/version
USN:advertisement UUID
(NOTIFY 方法发送的请求没有消息体,但请注意,消息与最后一个HTTP
标头之间必须空一行。)
IP 信息包的TTL 必须缺省为4,并且应该可以配置。
下面的列表提供了上面出现的命令行与标头的详细信息。除特别注明外,所
有标头值均要区分大小写。
命令行
NOTIFY
GENA 定义的用以发送通知和事件的方法。
*
请求通用,不受具体资源的限制。必须是*。
HTTP/1.1
HTTP 版本。
标头
HOST
要求。由互联网编号分配组织(IANA)为SSDP 保留的多播信道和端口。
必须是239.255.255.250:1900。
CACHE-CONTROL
要求。必须带有max-age,指代宣告有效存活时间。如果超过此时间间
隔,控制点可以认为设备(或服务)不再可用。应大于1800 秒(30 分钟)。
具体由UPnP 厂商决定。取整数。
LOCATION
要求。包含根设备UPnP 描述的URL 地址。在某些未受管理的网络中,
URL 主机可能包含IP 地址(与域名相对)。具体由UPnP 厂商决定。单
一URL。
NT
GENA 规定使用的标头。通知类型。必须采用以下一种形式。(参见:上
表。)单一URI。
UPnP:rootdevice
向根设备发送一次。
uuid:device-UUID
向每种设备(根设备或嵌入式设备)发送一次。设备UUID 由UPnP
厂商指定。
urn:schemas-UPnP-org:device:deviceType:v
向每种设备(根设备或嵌入式设备)发送一次。设备类型与版本
由UPnP 论坛工作委员会定义。
urn:schemas-UPnP-org:service:serviceType:v
向每种服务发送一次。服务类型与版本由UPnP 论坛工作委员会
定义。
NTS
GENA 规定使用的标头。通知子类型。必须是ssdp:alive。单一URI。
SERVER
要求。包含操作系统名称、操作系统版本、UPnP/1.0、产品名称以及产
品版本等信息。具体由UPnP 厂商决定。字符串。
USN
SSDP 要求使用的标头。唯一服务名称。必须是以下一种。(参见:上表。)
前缀(位于双冒号前)必须与设备描述中的UDN 元素值相匹配。(描述
部分主要说明UDN 元素。)单一URI。
uuid:device-UUID::UPnP:rootdevice
向根设备发送一次。设备UUID 由UPnP 厂商指定。
uuid:device-UUID
向每种设备(根设备或嵌入式设备)发送一次。设备UUID 由UPnP
厂商指定。
uuid:device-UUID::urn:schemas-UPnP-org:device:deviceType:v
向每种设备(根设备或嵌入式设备)发送一次。设备UUID 由UPnP
厂商指定。设备类型与版本由UPnP 论坛工作委员会定义。
uuid:device-UUID::urn:schemas-UPnP-org:service:serviceType:v
向每种服务发送一次。设备UUID 由UPnP 厂商指定。服务类型
与版本由UPnP 论坛工作委员会定义。
(NOTIFY 方法发送的请求没有响应消息。)
1.1.3 发现:宣告:设备不可用――ssdp:byebye NOTIFY
在设备及其服务将要从网络中退出时,设备应该对于每个未超期的
ssdp:alive 消息以多播方式传送ssdp:byebye 消息。但如果设备突然从网络退出,
它可能来不及发出这个通知消息。因此,发现消息必须在CACHE-CONTROL
标头中包含超时值(如上所述);如果不重新发出宣告,发现消息最后会因超时
而必须从控制点的高速缓存中除去。
(注:当控制点将要从网络中退出时,不需要采取与发现相关的动作。)
当一个设备即将从网络中退出时,它应该为每一条ssdp:alive 消息发送一条
多播请求,以明确撤销其发现消息。每个多播请求必须采用NOTIFY 方法,并
且NTS 标头中的ssdp:byebye 采用以下格式。用斜体表示的值为实际值的占位
符。
NOTIFY * HTTP/1.1
HOST: 239.255.255.250:1900
NT:search target
NTS:ssdp:byebye
USN:advertisement UUID
(NOTIFY 方法发送的请求没有消息体,但请注意,消息与最后一个HTTP
标头之间必须空一行。)
IP 信息包的TTL 必须缺省为4,并且可以配置。
下面的列表提供了上面出现的命令行与标头的详细信息。除特别注明外,所
有标头值均要区分大小写。
命令行
NOTIFY
GENA 定义的用以发送通知和事件的方法。
*
请求通用,不受具体资源的限制。必须是*。
HTTP/1.1
HTTP 版本。
标头
HOST
要求。由互联网编号分配组织(IANA)为SSDP 保留的多播信道和端口。
必须是239.255.255.250:1900。
NT
GENA 规定使用的标头。通知类型。(参见以上ssdp:alive NOTIFY 中
NT 标头的要求值列表。)单一URI。
NTS
GENA 规定使用的标头。通知子类型。必须是ssdp:byebye。单一URI。
USN
SSDP 要求使用的标头。唯一服务名称。(参见以上ssdp:alive NOTIFY
中USN 标头的要求值列表。)单一URI。
(NOTIFY 方法发送的请求没有响应消息。)
鉴于UDP 的不可靠性,设备应该发送多次以上消息。因此,如果控制点无
法获得设备或服务不可用的通知,原始发现消息最终将会因过期失效而被移除。
1.2 发现:搜索
当一个控制点加入到网络中时,UPnP 发现协议允许控制点寻找网络上感兴
趣的设备。消息搜索是通过多播方式实现的,包括类型、或目标,相当于设备或
服务的类型或标识符。设备响应消息包括的发现消息本质上与新连接设备的宣告
消息相同,前者是单播,而后者是多播。
1.2.1 发现:搜索协议与标准
为了搜索设备(并被控制点发现),控制点(和设备)使用以下总体UPnP
协议栈的子集。(总体UPnP 协议栈在本文开始处列出。)
UPnP 厂商[ 紫色]
UPnP 论坛[ 红色]
UPnP 设备架构[绿色]
HTTPU(单播)〔黑色〕SSDP[蓝色]
HTTPMU(多播)〔黑色〕SSDP[蓝色]
UDP〔黑色〕
IP[黑色]
在最高层,搜索消息包含特定厂商信息,如控制点、设备和服务标识符。在
协议栈接下来的一层,通过来自UPnP 论坛工作委员会的信息(如设备或服务
类型)对厂商内容进行了补充。来自以上各层的消息存储在UPnP 特定协议中,
并在本文中进行了定义。按照先后顺序,通过HTTP 多播变量分别传送搜索请
求,该变量已经通过简单服务发现协议(SSDP)方法标头得到了扩展。搜索响
应通过HTTP 单点变量(已经采用SSDP 进行了扩展)完成传送。(当控制点
搜索设备时无需GENA。)两种HTTP 消息都通过IP 上的TCP 进行发送。为
便于参考,上面[方括弧]中的颜色显示了何种协议定义下面发现消息中的具体标
头与值。
1.2.2 发现:搜索:M-SEARCH 形式请求
当一个控制点加入到网络中时,它应该采用以下格式的M-SEARCH 方法发
送多播请求。用斜体表示的值为实际值的占位符。
M-SEARCH * HTTP/1.1
HOST: 239.255.255.250:1900
MAN:"ssdp:discover"
MX:seconds to delay response
ST:search target
(采用M-SEARCH 方法发送的请求没有消息体,但请注意,消息与最后一
个HTTP 标头之间必须空一行。)
IP 信息包的TTL 必须缺省为4,并且可以配置。
下面的列表提供了上面出现的命令行与标头的详细信息。除特别注明外,所
有标头值均要区分大小写。
命令行
M-SEARCH
SSDP 定义的搜索请求方法。
*
请求通用,不受具体资源的限制。必须是*。
HTTP/1.1
HTTP 版本。
标头
HOST
要求。由互联网编号分配组织(IANA)为SSDP 保留的多播信道和端口。
必须是239.255.255.250:1900。
MAN
要求。与NTS 和ST 标头不同,MAN 标头的值采用双引号。必须是
"ssdp:discover"。
MX
要求。最长等待时间。设备响应在0 和这个值之间随机选择响应延迟的值,
这样可以为控制点响应平衡网络负载。如果大量设备需要响应或如果网络
延迟过长,那么该值应该适当增大。具体由UPnP 厂商决定。取整数。
ST
SSDP 要求使用的标头。搜索目标。必须是以下一种。(如上ssdp:alive
NOTIFY 中的NT 标头)单一URI。
ssdp:all
搜索所有设备和服务。
UPnP:rootdevice
只搜索根设备。
uuid:device-UUID
搜索特殊设备。设备UUID 由UPnP 厂商指定。
urn:schemas-UPnP-org:device:deviceType:v
搜索同类设备。设备类型与版本由UPnP 论坛工作委员会定义。
urn:schemas-UPnP-org:service:serviceType:v
搜索同类服务。服务类型与版本由UPnP 论坛工作委员会定义。
鉴于UDP 的不可靠性,控制点应该多次发送每个M-SEARCH 消息。因此,
为了排除无法接收控制点M-SEARCH 消息的可能性,设备应该定期重新发送其
宣告信息(参见:如上述ssdp:alive NOTIFY 中包含的CACHE-CONTROL 标
头)。
1.2.3 发现:搜索:响应
为了被找到,设备必须向发送查找请求的多播通道的源IP 地址与端口发送
响应信息。
传送给M-SEARCH 的响应消息与宣告消息有意设计得类似,遵循上述
ssdp:alive NOTIFY(如上)相同的的形式,处理将NT 标头改做ST 标头。响应
必须采用以下格式发送:用斜体表示的值为实际值的占位符。
HTTP/1.1 200 OK
CACHE-CONTROL:max-age = seconds until advertisement expires
DATE:when response was generated
EXT:
LOCATION:URL for UPnP description for root device
SERVER:OS/version UPnP/1.0 product/version
ST:search target
USN:advertisement UUID
(采用M-SEARCH 方法不包含响应消息体,但是请注意,消息与最后一个
HTTP 标头之间必须间隔一空行。)
(采用IP 信息包响应请求时无需将TTL 限定为4。)
以下列表提供了上面出现的标头的详细信息。除特别说明外所有标头值区分
大小写。
标头(header)
CACHE-CONTROL
要求。必须带有max-age,指代宣告有效持续时间。如果超过此时间间
隔,控制点可以认为设备(或服务)不再可用。应大于1800 秒(30 分钟)。
具体由UPnP 厂商决定。取整数。
DATE
推荐使用。响应生成时间。RFC1123 日期。
EXT
要求。确定MAN 标头已经被理解。(只限标头,无值。)
LOCATION
要求。包含根设备UPnP 描述的URL 地址。在某些未受管理的网络中,
URL 主机可能包含IP 地址(与域名相对)。具体由UPnP 厂商决定。单
一URL。
SERVER
要求。包含操作系统名称、操作系统版本、UPnP/1.0、产品名称以及产
品版本等信息。具体由UPnP 厂商决定。字符串。
ST
SSDP 要求使用的标头。搜索目标。单一URI。如果请求中包含ST 标头,
必须是
ssdp:all
如果根设备带有d 种嵌入式设备与s 种嵌入服务且只有K 种不同
服务类型,那么其响应次数为3+2d+k。ST 标头值必须与采用
ssdp:alive 的NOTIFY 消息中的NT 标头保持统一。(详见如上说
明。)单一URI。
UPnP:rootdevice
向根设备响应一次。必须是UPnP:rootdevice。单一URI。
uuid:device-UUID
向每种设备(根设备或嵌入式设备)响应一次。必须是
uuid:device-UUID。设备UUID 由UPnP 厂商指定。单一URI。
urn:schemas-UPnP-org:device:deviceType:v
向每种设备(根设备或嵌入式设备)响应一次。必须是
urn:schemas-UPnP-org:device:deviceType:v。设备类型与版本
由UPnP 论坛工作委员会定义。
urn:schemas-UPnP-org:service:serviceType:v
向每种服务响应一次。必须是
urn:schemas-UPnP-org:service:serviceType:v。服务类型与版
本由UPnP 论坛工作委员会定义。
USN
SSDP 要求使用的标头。唯一服务名称。(详见以上ssdp:alive NOTIFY
中USN 标头要求值列表。)单一URI。
鉴于UDP 的不可靠性,每种响应设备都应发送多次。为了排除控制点未能
接收响应的可能性,设备应该定期重新发送其宣告(参见:上述ssdp:alive
NOTIFY 中包含的CACHE-CONTROL 标头)。
如果搜索请求出现错误,设备必须发送以下任意一种错误响应。
错误
MAN header != ssdp:discover
412 预处理失败。如果MAN 标头值不等于ssdp:discover,那么设备必须
用HTTP 错误412 预处理失败做出响应。
其它错误可能被以下UPnP 协议栈层返回。参考有关这些协议的文件了解详细
信息。
1.3 发现参考
GENA
通用事件通知架构。IETF 草案。
HTTPMU
HTTPU
在UDP 上实现HTTP 协议多播以及HTTP 协议单播。IETF 草案。
SSDP
简单服务发现协议。IETF 草案。
2. 描述
描述是UPnP 网络的第二步。描述紧随寻址(第0 步,设备获得网络地址)与
发现(第1 步,控制点发现感兴趣的设备)步骤之后。描述可以支持控制(第3
步,控制点向设备发送命令)、事件触发(第4 步,控制点监听设备状态的变化)
以及展示(第5 步,控制点显示设备的一个用户界面)。
在控制点发现了一个设备之后,控制点仍然对设备知之甚少――可能仅仅知
道发现消息中的相关信息,如设备(或服务)的UPnP 类型、设备的全球唯一
标识符和设备UPnP 描述的URL 地址。为了让控制点更多的了解设备及其功能、
或者与设备交互,控制点必须从发现消息中得到设备描述的URL,并通过URL
取得设备描述。
对于一个设备的UPnP 描述一般分成两个逻辑部分: 设备描述(描述所包
含的物理与逻辑设备)以及一个或多个服务描述(描述设备对外暴露的能力)。
UPnP 设备描述包括特定厂商、制造商信息,如模块名称和编号、序列号、制造
商名称、特定厂商网站URL 等(详细信息如下)。对于设备中的每种服务,设
备描述都包含服务类型、名称、服务描述URL、控制URL 以及事件URL。设备
描述还包含所有嵌入式设备描述与URL 地址集。本部分主要介绍UPnP 设备描
述,控制、事件触发与展示部分将分别介绍如何使用控制URL、事件URL 与展
示URL。
注意一个物理设备可以包含多个逻辑设备。多个逻辑设备既可以是嵌入多个
设备(服务)的单一根设备,也可以是多个根设备(可能没有嵌入式设备)。前
者是一个有关根设备的UPnP 设备描述,其中包含所有嵌入式设备描述。后者
是多个UPnP 设备描述,每个根设备对应一种描述。
UPnP 设备描述由UPnP 厂商编写。采用XML 句法,并且遵循标准UPnP
设备模版。UPnP 设备模板由UPnP 论坛工作委员会生成;该模板来源于UPnP
模板语言――来自XML 标准结构。本部分主要说明了UPnP 设备描述格式、
UPnP 设备模板、以及涵盖各种设备的UPnP 模板语言等内容。
UPnP 服务描述包括一系列命令,或动作,服务的响应与每种动作的参数,
或变量。服务描述还包括一系列变量。这些变量描述了服务运行时的状态,其中
包括数据类型、取值范围和事件特性的描述。本部分主要说明了动作描述、变量、
状态变量、以及这些变量的性质。事件触发部分主要说明事件的特性。
如同UPnP 设备描述一样,UPnP 服务描述由UPnP 厂商提供。描述采用
XML 句法,并且基于标准UPnP 服务模版。UPnP 服务模板由UPnP 论坛工作
委员会生成;来源于UPnP 模板语言,并在要求的时候使用人类语言将其适当
扩大。UPnP 模板语言来源于XML 标准结构。本部分主要说明了UPnP 服务描
述格式、UPnP 服务模板、人类语言的主要增加以及涵盖各种服务的UPnP 模板
语言等内容。
UPnP 厂商可以通过扩展服务(包括其它UPnP 服务)或嵌入其它设备使其
设备与众不同。一旦控制点取得特殊的设备描述,控制点可以使用这些新增特性
用于控制和事件触发。设备和服务描述权威地记录了设备的实现。
取得UPnP 设备描述非常简单:控制点在发现消息的URL 上发出HTTP
GET 请求,然后设备返回设备描述。取得UPnP 服务描述也是一个相似的流程,
需要使用设备描述中的URL。响应和请求的协议栈、方法、标头和正文详细解
释如下:
只要来自设备的发现宣告没有过期,控制点就可以认为设备及其服务可用。
只要设备及其服务可用,设备和服务描述就处于静止状态,因此,可以在任何地
点获得。如果设备取消了其宣告,那么控制点就必须认为设备及其服务不再可用。
如果设备需要改变其中一个描述,那么它必须取消已经发布的宣告消息并重新发
布宣告信息。因此,如果设备再次出现在网络上时,控制点应该认为设备与服务
描述有了变化。
和发现一样,描述在设备与控制点使用不同版本UPnP 网络互操作性方面
有着至关重要的作用。正如发现部分介绍的一样,UPnP 设备架构(此处定义)
使用主版本和副版本来描述。副版本改进的部分必须兼容属于同一主版本的前副
版本。主版本改进的部分不要求是前版的扩展集,并且并不保证向后兼容。版本
信息用作发现消息的备份信息被包含在描述消息中。本部分主要说明了描述消息
的格式。
剩余部分首先说明如何描述设备,详细阐述特定厂商信息、嵌入式设备以及
控制URL、事件触发URL 和展示URL。其次,说明UPnP 设备模板。再次,
说明如何描述服务,详细阐述动作、变量、状态变量、以及变量的性质。然后,
说明UPnP 服务模板和UPnP 模板语言。最后,本部分详细说明控制点如何从
设备取得设备和服务描述。
2.1 描述:设备描述
一个设备的UPnP 描述包含多个特定厂商信息、所有嵌入式设备定义、设
备展示URL、以及所有服务列表,包括控制URL 和事件触发URL。除了定义非
标准设备之外,UPnP 厂商可以为标准设备添加新的嵌入式设备和服务。为了解
释这一点,下面是针对实际元素和值的带有占位符(用斜体表示)的列表。其中
一些占位符由UPnP 论坛工作委员会( 红色)或UPnP 厂商( 紫色)指定。对
于非标准设备,所有占位符都由UPnP 厂商具体指定。(在后面的参考信息中,
由UPnP 设备架构定义的元素以绿色表示。)紧随其后的是对于元素、属性和
值的详细说明。
<?xml version="1.0"?>
<root xmlns="urn:schemas-upnp-org:device-1-0">
<specVersion>
<major>1</major>
<minor>0</minor>
</specVersion>
<URLBase>base URL for all relative URLs</URLBase>
<device>
<deviceType>urn:schemas-upnp-org:device:deviceType:v</deviceType>
<friendlyName>short user-friendly title</friendlyName>
<manufacturer>manufacturer name</manufacturer>
<manufacturerURL>URL to manufacturer site</manufacturerURL>
<modelDescription>long user-friendly title</modelDescription>
<modelName>model name</modelName>
<modelNumber>model number</modelNumber>
<modelURL>URL to model site</modelURL>
<serialNumber>manufacturer’s serial number</serialNumber>
<UDN>uuid:UUID</UDN>
<UPC>Universal Product Code</UPC>
<iconList>
<icon>
<mimetype>image/format</mimetype>
<width>horizontal pixels</width>
<height>vertical pixels</height>
<depth>color depth</depth>
<url>URL to icon</url>
</icon>
XML to declare other icons, if any, go here
</iconList>
<serviceList>
<service>
<serviceType>urn:schemas-upnp-org:service:serviceType:v</serviceType>
<serviceId>urn:upnp-org:serviceId:serviceID</serviceId>
<SCPDURL>URL to service description</SCPDURL>
<controlURL>URL for control</controlURL>
<eventSubURL>URL for eventing</eventSubURL>
</service>
Declarations for other services defined by a UPnP Forum working committee (if any)
go here
Declarations for other services added by UPnP vendor (if any) go here
</serviceList>
<deviceList>
Description of embedded devices defined by a UPnP Forum working committee (if any)
go here
Description of embedded devices added by UPnP vendor (if any) go here
</deviceList>
<presentationURL>URL for presentation</presentationURL>
</device>
</root>
以下列出了上述列表中出现的元素、属性和值的详细信息。所有元素和属性
都要区分大小写;HTTP 规定URL 要区分大小写;其它值没有特别说明时不区
分大小写。元素的顺序无关紧要。除非有特别说明:所要求的元素必须出现一次
(无重复),推荐或可选元素最多只能出现一次。
xml
所有XML 文件都要求:区分大小写。
root
要求。必须采用urn:schemas-UPnP-org:device-1-0 作为xmlns 属性值,
参考UPnP 模板语言(如下描述)。区分大小写。包含所有描述根设备
的其它元素,即包含以下子元素:
specVersion
要求。包含以下子元素:
major
要求。UPnP 设备架构主版本。必须为1。
minor
要求。UPnP 设备架构副版本。必须为0。
URLBase
可选。定义基础URL。用于构建完全合格的URL。描述中其它地
方出现的所有相关URL 都附属于这个基础URL。如果URLBase
为空,或者没有提供,那么基础URL 即为用以重新获得设备描述
的URL。具体由UPnP 厂商决定。单个URL。
device
要求。包含以下子元素:
deviceType
要求。UPnP 设备类型。
• 对于UPnP 论坛工作委员会定义的标准设备,必须以
urn:schemas-UPnP-org:device 开头:后面带有设备类
型后缀、冒号和整数设备版本(如上面列表所示)。
• 对于UPnP 厂商指定的非标准设备,必须以urn:开头,
带有厂商所有的ICANN 域名,还有:device:,后面是设
备类型后缀、冒号和整数设备版本, 即
urn:domain-name:device:deviceType:v。
设备类型后缀由UPnP 论坛工作委员会定义或由UPnP 厂商
来规定,必须不多于64 个字符,版本后缀不计算在内,并
且用冒号隔开。单一URI。
friendlyName
要求。对于用户的简短描述。应该完成本地化( 参见:
ACCEPT-/CONTENT-LANGUAGE 标头)。具体由UPnP 厂商决
定。字符串。不得多于64 个字符。
manufacturer
要求。制造商名称。可以进行本地化( 参见:
ACCEPT-/CONTENT-LANGUAGE 标头)。具体由UPnP 厂商决
定。字符串。不得多于64 个字符。
manufacturerURL
可选。制造商网站。可以进行本地化( 参见:
ACCEPT-/CONTENT-LANGUAGE 标头)。可能与基础URL 相
关。具体由UPnP 厂商决定。单一URL。
modelDescription
推荐使用。对于用户的长篇描述。应该完成本地化(参见:
ACCEPT-/CONTENT-LANGUAGE 标头)。具体由UPnP 厂商决
定。字符串。不得多于128 个字符。
modelName
要求。型号名称。可以进行本地化( 参见:
ACCEPT-/CONTENT-LANGUAGE 标头)。具体由UPnP 厂商决
定。字符串。不得多于32 个字符。
modelNumber
推荐使用。型号。可以进行本地化(参见:
ACCEPT-/CONTENT-LANGUAGE 标头)。具体由UPnP 厂商决
定。字符串。不得多于32 个字符。
modelURL
可选。型号网站。可以进行本地化(参见:
ACCEPT-/CONTENT-LANGUAGE 标头)。可能与基础URL 相
关。具体由UPnP 厂商决定。单一URL。
serialNumber
推荐使用。序列号。可以进行本地化(参见:
ACCEPT-/CONTENT-LANGUAGE 标头)。具体由UPnP 厂商决
定。字符串。应该少于64 个字符。
UDN
要求。唯一设备名称。设备的全球唯一标识符,无论是根设备还
是嵌入式设备。随着时间的推移,必须对具体设备例程保持一致
(即必须在重启后继续保持不变)。必须与设备发现消息中的NT
标头值相匹配。必须与所有发现消息中的USN 标头前缀相匹配。
(“发现”章节将说明NT 和USN 标头。)必须以uuid:开头:后
面带有UPnP 厂商指定的UUID 后缀。单一URI。
UPC
可选。通用产品代码。12 位全数字代码,用于确定销售包装。由
统一编码委员会进行管理。具体由UPnP 厂商决定。单一UPC。
iconList
仅当设备有一个或多个图标时要求。具体由UPnP 厂商决定。包
含以下子元素:
icon
推荐使用。控制点UI 中描述设备的图标。可以进行本地化(参
见:ACCEPT-/CONTENT-LANGUAGE 标头)。下列每个尺
寸推荐一个图标(宽度x 高度x 深度):16×16x1、16×16x8、
32×32x1、32×32x8、48×48x1、48×48x8。包含以下子元素:
mimetype
要求。图标的MIME 类型(参见:RFC2387)。单一
MIME 图像类型。
width
要求。图标的水平尺寸,用像素、整数表示。
height
要求。图标的垂直尺寸,用像素、整数表示。
depth
要求。色彩位的数量,用像素、整数表示。
url
要求。面向图标图像的指针。(XML 不支持直接嵌入二
进制数据。参见下面的说明。)通过HTTP 取得。可能
与基础URL 相关。具体由UPnP 厂商决定。单一URL。
serviceList
要求。包含以下子元素:
service
要求。对于UPnP 论坛工作委员会定义的每项服务要重复一
次。如果UPnP 厂商通过添加额外的标准UPnP 服务来区分
设备,则对于额外服务也要重复一次。包含以下子元素:
serviceType
要求。UPnP 服务类型。不得包含散列符(#,在UTF-8
中为23 Hex)。
• 对于由UPnP 论坛工作委员会定义的标准服务类型,
必须以urn:schemas-UPnP-org:service:开头,随后
是服务类型后缀和整数服务版本(如上面列表所示)。
• 对于由UPnP 厂商指定的非标准服务类型,必须以
urn:开头,随后是厂商所有的ICANN 域名,然后
是:service:,接着是服务类型后缀、冒号和整数服务
版本,即urn:domain-name:service:serviceType:v。
由UPnP 论坛工作委员会定义或UPnP 厂商具体指定的
服务类型后缀不得多于64 个字符,版本后缀不计算在内,
并且用冒号隔开。单一URI。
serviceId
要求。服务标识符。在这一设备描述中必须保持唯一性。
• 对于由UPnP 论坛工作委员会定义的标准服务,必须
以urn:UPnP-org:serviceId:开头,后面是服务ID 后
缀(如上面列表所示)。(注意在此时要使用UPnP-org
来代替schemas-UPnP-org,因为XML 模式并没有
针对每个服务ID 进行定义。)
• 对于由UPnP 厂商指定的非标准服务,必须以urn:
开头, 随后是厂商拥有的ICANN 域名, 然后
是:serviceId: , 接着是服务ID 后缀, 即
urn:domain-name:serviceId:serviceID。
服务ID 后缀由UPnP 论坛工作委员会定义或由UPnP 厂
商指定,不得超过64 个字符。单一URI。
SCPDURL
要求。服务描述的URL(以前的服务控制协议定义URL)。
(参见:下面关于服务描述的章节。)可能与基础URL
相关。具体由UPnP 厂商决定。单一URL。
controlURL
要求。控制的URL(参见:关于控制的章节)。可能与
基础URL 相关。具体由UPnP 厂商决定。单一URL。
eventSubURL
要求。事件的URL(参见:关于事件的章节)。可能与
基础URL 相关。在设备内部可能是唯一的;不会有两个
服务拥有相同的事件URL。如果服务没有事件变量,则
它应该没有事件(参见:关于事件的章节);如果服务
没有事件,则该元素必须展示出来,但是应该为空,即
<eventSubURL></eventSubURL>。具体由UPnP 厂商
决定。单一URL。
deviceList
仅当根设备带有嵌入式设备时要求。包含以下子元素:
device
要求。对于UPnP 论坛工作委员会定义的每项嵌入式设备要
重复一次。如果UPnP 厂商通过嵌入其它UPnP 设备来区分
设备,则对于每个嵌入式设备要重复一次。根据上面的定义,
包含面向根子元素设备的子元素。
presentationURL
推荐使用。设备展示的URL(参见:关于展示的章节)。可
能与基础URL 相关。具体由UPnP 厂商决定。单一URL。
为了获得未来可伸缩性,在处理上述XML 时要遵守灵活XML 处理框架
(FXPP),设备和控制点必须忽略:(a) 任何未知元素及其子元素或内容,以
及(b)任何未知属性及其值。
注意“和”字符(&,在UTF-8 中为0×26)不允许出现在XML 中。如果需
要作为XML 元素(如一个URL)的值的一部分,“和”符号必须转换为&amp;
(HTML)或%26(URL 转义码)。
XML 不支持直接嵌入的二进制数据,如UPnP 设备描述中的图标。二进制
数据可以转换为文本(从而嵌入XML 中)使用bin.base64(用于二进制数据的
一种MIME 型的基础64 编码)或bin.hex(代表八位字节的十六进制数字)的
XML 数据类型。此外,通过在XML 中嵌入一个URL 并传输数据以响应单独的
HTTP 请求,数据可以进行间接传递并保持原样;UPnP 设备描述中的图标将以
后一种方式进行传送。
由UPnP 论坛工作委员会进行标准化的设备有一个完整版本。设备的每一个
以后的版本必须包括以前的版本,也就是说,与设备的早期版本相比,它必须包
括相同或以后版本的所有嵌入式设备和服务。尽管以后的设备版本越来越大,但
是一个设备的所有版本的UPnP 设备类型仍然保持一致。
2.2 描述:UPnP 设备模板
上面的列表也显示出UPnP 设备描述与UPnP 设备模板之间的关系。正如上
面所说明的,UPnP 设备描述由UPnP 厂商按照UPnP 设备模板用XML 来编写。
UPnP 设备模板由UPnP 论坛工作委员会进行制作,作为一种对设备进行标准化
的方式。
根据预留位置的适当的规范,上面的列表可能是一个UPnP 设备模板或一个
UPnP设备描述。注意一些由UPnP论坛工作委员会定义的占位符(用红色表示),
即UPnP 设备类型标识符,要求的UPnP 服务,以及要求的UPnP 嵌入式设备
(如果有)。如果这些内容都已经定义,则列表就是UPnP 设备模板,成为针
对这一设备类型的标准。UPnP 设备模板是UPnP 论坛工作委员会的主要成果之
一。
进一步说,上面列表中剩余的占位符将由UPnP 厂商来规定(以紫色表示),
即具体厂商的信息。如果这些占位符已经指定(及其它),则列表就是UPnP
设备描述,适合于提供给控制点以便支持控制、事件和展示。
换句话说,UPnP 设备模板用来定义整体设备类型,而每个UPnP 设备描述
则是将厂商具体信息添加到模板中。第一个由UPnP 论坛工作委员会创建;以
后的由UPnP 厂商来制作。
2.3 描述:服务描述
关于服务的UPnP 描述定义了动作及其变量,还有状态变量及其数据类型、
范围和事件特征。
每个服务可能有零或多个动作。每个动作可能有零或更多变量。这些变量的
任何组合可能是输入或输出参数。如果一个动作有一个或多个输出变量,那么这
些变量中的一个可能被标记为返回值。每个变量都应该对应一个状态变量。这一
直接处理编程模式可以加强简单性。
每个服务必须有一个或多个状态变量。
除了定义非标准服务,UPnP 厂商可以为标准设备添加新的动作和服务。
为了解释这几点,下面是针对实际元素和值的带有占位符(用斜体表示)的
列表。对于标准的UPnP 服务,其中一些占位符由UPnP 论坛工作委员会(用
红色表示)定义或由UPnP 厂商( 紫色)指定。对于非标准服务,所有占位符
都由UPnP 厂商具体指定。(在后面的参考信息中,由UPnP 设备架构定义的
元素以绿色表示。)紧随其后的是对于元素、属性和值的详细说明。
<?xml version="1.0"?>
<scpd xmlns="urn:schemas-UPnP-org:service-1-0">
<specVersion>
<major>1</major>
<minor>0</minor>
</specVersion>
<actionList>
<action>
<name>actionName</name>
<argumentList>
<argument>
<name>formalParameterName</name>
<direction>in xor out</direction>
<retval />
<relatedStateVariable>stateVariableName</relatedStateVariable>
</argument>
Declarations for other arguments defined by UPnP Forum working committee (if any)
go here
</argumentList>
</action>
Declarations for other actions defined by UPnP Forum working committee (if any)
go here
Declarations for other actions added by UPnP vendor (if any) go here
</actionList>
<serviceStateTable>
<stateVariable sendEvents="yes">
<name>variableName</name>
<dataType>variable data type</dataType>
<defaultValue>default value</defaultValue>
<allowedValueList>
<allowedValue>enumerated value</allowedValue>
Other allowed values defined by UPnP Forum working committee (if any) go here
</allowedValueList>
</stateVariable>
<stateVariable sendEvents="yes">
<name>variableName</name>
<dataType>variable data type</dataType>
<defaultValue>default value</defaultValue>
<allowedValueRange>
<minimum>minimum value</minimum>
<maximum>maximum value</maximum>
<step>increment value</step>
</allowedValueRange>
</stateVariable>
Declarations for other state variables defined by UPnP Forum working committee
(if any) go here
Declarations for other state variables added by UPnP vendor (if any) go here
</serviceStateTable>
</scpd>
以下列出了上述列表中出现的元素、属性和值的详细信息。所有元素和属性
均区分大小写;除特别注明外,值不区分大小写。除特别注明外,元素的顺序无
关紧要。除特别注明外,所要求的元素必须出现一次(无重复),推荐或可选元
素最多只能出现一次。
xml
要求所有XML 文件采用。区分大小写。
scpd
要求。必须采用urn:schemas-UPnP-org:service-1-0 作为xmlns 属性值,
参考UPnP 模板语言(如下描述)。区分大小写。包含所有描述服务的
其它元素,即包含以下子元素:
specVersion
要求。包含以下子元素:
major
要求。UPnP 设备架构主版本。必须为1。
minor
要求。UPnP 设备架构副版本。必须为0。
actionList
仅当服务带有动作时要求。(每个服务都可以有不少于0 个动作。)
包含以下子元素:
action
要求。对于UPnP 论坛工作委员会定义的每项动作要重复一次。
如果UPnP 厂商通过添加额外的动作来区分服务,则对于每个额
外的动作都要重复一次。包含以下子元素:
name
要求。动作的名称。不得包含连字符(-,在UTF-8 中为2D
Hex)和散列符(#,在UTF-8 中为23 Hex)。
• 对于UPnP 论坛工作委员会定义的标准动作,不得以X_
和A_开头。
• 对于UPnP 厂商指定的非标准动作和标准服务的添加项
目,必须使用X_开头。
字符串。应该不超过32 个字符。
argumentList
仅当为动作定义参数时要求。(每个动作都可以有不少于0
个参数。)包含以下子元素:
argument
要求。为每个参数重复一次。包含以下子元素:
name
要求。正式参数的名称。应该是动作所影响的模型的
状态变量的名称。不得包含连字符(-,在UTF-8 中
为2D Hex)。字符串。应该不超过32 个字符。
direction
要求。无论变量是输入还是输出参数。必须采用in xor
out 格式。任何in 变量必须列在任何out 变量的前面。
retval
可选。最多确定一个out 变量作为返回值。如果包括,
必须是第一个out 变量。(只限元素,无值。)
relatedStateVariable
要求。必须是一个状态变量的名称。
serviceStateTable
要求。(每个服务必须有不少于0 状态变量。)包含以下子元素:
stateVariable
要求。对于UPnP 论坛工作委员会定义的每个状态变量都要重复
一次。如果UPnP 厂商通过添加额外的状态变量来区分服务,则
对于每个额外变量都要重复一次。sendEvents 属性将定义当这一
状态变量的值发生变化时是否生成事件消息;非事件状态变量采
用sendEvents=“no”,缺省为sendEvents=“yes”。包含
以下子元素:
name
要求。状态变量的名称。不得包含连字符(-,在UTF-8 中为
2D Hex)。
• 对于UPnP 论坛工作委员会定义的标准变量,不得以X_
和A_开头。
• 对于UPnP 厂商指定的非标准变量和标准服务的添加项
目,必须使用X_开头。
字符串。应该不超过32 个字符。
dataType
要求。与XML 模式,部分2:数据类型中定义的数据类型相
同。由UPnP 论坛工作委员会定义的类型用于标准状态变量;
由UPnP 厂商指定的类型用于扩展。必须是以下值中的一种:
ui1
无符号的1 字节int。与没有引导标志(leading sign)的
int 格式相同。
ui2
无符号的2 字节int。与没有引导标志(leading sign)的
int 格式相同。
ui4
无符号的4 字节int。与没有引导标志(leading sign)的
int 格式相同。
i1
1 字节int。与int 格式相同。
i2
2 字节int。与int 格式相同。
i4
4 字节int。与int 格式相同。必须在-2147483648 和
2147483647 之间。
int
固定点,整数。可能有引导标志(leading sign)。可能
有引导零(leading zero)。(没有当前符号。)(小数
左侧没有数字组,如没有逗号。)
r4
4 字节浮点。与浮点格式相同。必须在3.40282347E+38
到1.17549435E-38 之间。
r8
8 字节浮点。与浮点格式相同。负值必须在
-1.79769313486232E308 和-4.94065645841247E-324
之间,正值必须在4.94065645841247E-324 和
1.79769313486232E308 之间,也就是说IEEE 64 位(8
字节)加倍。
number
与r8 相同。
fixed.14.4
与r8 相同,但是小数点左侧不超过14 个数字,右侧不超
过4 个数字。
float
浮点数字。尾数(小数的左侧)和/或指数可能有引导标
志(leading sign)。尾数和/或指数可能有引导零(leading
zero)。尾数中的小数符号是一个句点,也就是说,尾数
的整个数字由句点分割成分数(fractional digit)。尾数由
E 与指数分开。(无当前符号。)(尾数中没有数字组,
如没有句点。)
char
统一字符字符串。一个字符长。
string
统一字符字符串。没有长度限制。
date
ISO 8601 格式子集中的日期没有时间数据。
dateTime
ISO 8601 格式的日期,带有可选时间但是没有时区。
dateTime.tz
ISO 8601 格式的日期,带有可选时间但是没有可选时区。
time
ISO 8601 格式子集中的时间,没有日期和时区。
time.tz
ISO 8601 格式子集中的时间,带有可选时区但是没有日
期。
boolean
0,false,或者用no 表示false;1,true,或者用yes 表
示true。
bin.base64
MIME 型Base64 编码二进制BLOB。取3 个字节,将其
分为4 部分,每6 位形成一组,与一个8 位字节相匹配。
(3 个8 位字节编码为4。)没有大小限制。
bin.hex
十六进制数字代表8 位字节。将每个半位元组作为一个十
六进制数字,编码为一个独立的字节。(1 个8 位字节编
码为2。)没有大小限制。
uri
统一资源标识符。
uuid
全球唯一ID。十六进制数字代表8 位字节。可选的嵌入
式连字符可以忽略。
defaultValue
推荐使用。期望的初值。由UPnP 论坛工作委员会定义或委
托给UPnP 厂商。必须匹配数据类型。必须满足
allowedValueList 或allowedValueRange 限制。
allowedValueList
推荐使用。列举合法的字符串值。禁止数据类型而不是字符
串。最多可以规定allowedValueRange 和allowedValueList
其中之一。子元素进行了排序( 例如, 参见
NEXT_STRING_BOUNDED)。包含以下子元素:
allowedValue
要求。字符串变量的合法值。由UPnP 论坛工作委员会定
义的类型用于标准状态变量;由UPnP 厂商指定的类型用
于扩展。应该不超过32 个字符。
allowedValueRange
推荐使用。为合法数值定义范围;为数值定义解决方法。仅
面对数字数据类型进行定义。最多可以规定
allowedValueRange 和allowedValueList 其中之一。包含以
下子元素:
minimum
要求。包括下限。由UPnP 论坛工作委员会定义或委托给
UPnP 厂商。单一数值。
maximum
要求。包括上限。由UPnP 论坛工作委员会定义或委托给
UPnP 厂商。单一数值。
step
推荐使用。增量运算的大小,也就是操作v = v + s 中s
的值。由UPnP 论坛工作委员会定义或委托给UPnP 厂
商。单一数值。
对于未来的可伸缩性,在处理上述XML 时,要遵守灵活的XML 处理框架
(FXPP),设备和控制点必须忽略:(a) 任何未知元素及其子元素或内容,以
及(b)任何未知属性及其值。
注意“和”字符(&,在UTF-8 中为26 Hex)不允许出现在XML 中。如果
需要作为XML 元素(如一个URL)的值的一部分,“和”符号必须转换为&amp;
(HTML)或%26(URL 转义码)。
注意对于一个服务而言在逻辑上依然可能虽然没有动作但是有状态变量和
活动;虽然不太可能发生,但是这样的服务将成为独立的信息来源。然而,没有
状态变量的服务是被禁止的。
与设备描述不同,服务描述及相关值应该不使用特定位置的值;其中包括服
务描述、动作变量值、以及状态变量值。与此相反,大多数动作变量和状态变量
都应该使用与位置相独立的值表示方法;应用应该进行转换和/或格式化,将信
息从标准形式变为适合场所的正确的语言和/或格式。例如,日期用与位置相对
立的格式(ISO 8601)来表示,用整数表示,没有场所独特的格式(如没有货
币符号、没有数字组)。串值应该用标准的‘场所’或统一方法来表示。带有
allowedValueList 的变量应该使用UPnP 标准语言的令牌值,而且不反映要显示
在场所化用户界面上的字符串。
然而,一些情况下动作的行为取决于具体的场所。在这种情况下,变量应定
义用于指示场所,或者可以使用与ACCEPT-/CONTENT-LANGUAGE 标头相同
的编码方法(RFC1766)。如果有多个独立于场所之外的动作,则服务可以包
括一个动作以便设置一个状态变量来指示地点,而且也不需要将地点标识符分别
传递给每个动作。
由UPnP 论坛工作委员会进行标准化的服务有一个完整版本。服务每一个以
后的版本必须包括以前的版本,也就是说,它必须准确地包括服务的早期版本定
义的所有动作和状态变量。尽管以后的服务版本越来越大,但是一个服务的所有
版本的UPnP 服务类型仍然保持一致。
2.4 描述:UPnP 服务模板
上面的列表也显示出UPnP 服务描述与UPnP 服务模板之间的关系。正如上
面所说明的,UPnP 对于服务的描述由UPnP 厂商按照UPnP 服务模板用XML
来编写。UPnP 服务模板由UPnP 论坛工作委员会进行制作,作为一种对设备进
行标准化的方式。
根据占位符的适当的规范,上面的列表可能是一个UPnP 服务模板或一个
UPnP服务描述。注意一些由UPnP论坛工作委员会定义的占位符(用红色表示),
即动作及其参数、状态及其数据类型、范围和事件特征。如果这些内容都已经指
定,则上述列表就是UPnP 服务模板,并成为针对这一服务类型的标准。除UPnP
设备模板(参见:关于描述的章节)之外,UPnP 服务模板也是UPnP 论坛工作
委员会的主要成果之一。
进一步说,上面列表中剩余的占位符将由UPnP 厂商来规定(以紫色表示),
即额外的具体厂商的动作和状态变量。如果这些占位符已经指定(与其它的内容
一样),则上述列表可能是UPnP 服务描述,适合于一个设备内的服务效果控
制。
换句话说,UPnP 服务模板用来定义整体服务类型,而每个UPnP 服务描述
则是将厂商具体内容添加到模板中。第一个由UPnP 论坛工作委员会创建;以
后的由UPnP 厂商来制作。
2.5 描述:非标准厂商扩展
如上所述,UPnP 厂商可能通过包括额外的服务以及嵌入式设备来区分他们
的设备并扩展标准设备。同样地,UPnP 厂商也可以通过包括额外的动作或状态
变量来扩展标准服务。UPnP 厂商不得通过修改标准化的allowedValueList 来扩
展标准服务。下表中列出针对每种类型的命名惯例,并给出详细说明。
扩展类型标准非标准
设备类型urn:schemas-UPnP-org:device:deviceType:v urn:domain-name:device:deviceType:v
服务类型urn : urn:domain-name:service:serviceType:v
schemas-UPnP-org:service:serviceType:v
服务ID urn:UPnP-org:serviceId:serviceID urn:domain-name:serviceId:serviceID
动作名称不要以X_或A_开头。用X_开头。
状态变量名称不要以X_或A_开头。用X_开头。
设备或服务描述
中的XML 元素
由UPnP 模板语言进行定义。
由XML 名称空间确定范围并位于以X_开头的一个
元素内的任意XML。
设备或服务描述
中的XML 属性
由UPnP 模板语言进行定义。由XML 名称空间确定范围并以X 开头的任意属性。
正如上表的最后二行所说明的一样,UPnP 厂商也可以向设备或服务描述添
加非标准XML。每个添加项必须在厂商提供的XML 名称空间的范围内。任意
XML 必须包括以X_开头的元素,该元素必须是包含子元素的标准元素的子元素。
非标准属性也可以添加到标准元素中,但是这些属性必须在XML 名称范围内而
且以X_开头。
为了说明这一点,下面是针对实际元素和值的带有占位符(用斜体表示)的
列表。其中一些占位符将由UPnP 厂商( 紫色)来指定,另外一些由UPnP 设
备架构(绿色)进行定义。
<RootStandardElement xmlns="urn:schemas-UPnP-org:device-1-0"
xmlns:n="domain-name:schema-name">
other XML
<AnyStandardElement n:X_VendorAttribute="arbitrary string value">
other XML
</AnyStandardElement>
other XML
</RootStandardElement>
RootStandardElement
要求。一个标准的根元素。xmlns 属性定义了名称空间,在这种情况下,
一个标准UPnP 名称空间和一个非标准名称空间(带有前缀n)。
• 对于设备描述,必须是root。
• 对于服务描述,必须是scpd。
AnyStandardElement
要求。任何标准元素,无论是根元素还是其它元素,无论是文本内容
还是元素本身,必须已经成为标准的设备或服务描述的组成部分。
X_VendorAttribute 必须以X_开头。(前缀A_已经保留。)可能有一
个任意的字符串值。
<EltOnlyStandardElement n:X_VendorAttribute="vendor value">
<n:X_VendorElement xmlns:n="domain-name:schema-name">
arbitrary XML
</n:X_VendorElement>
</EltOnlyStandardElement>
EltOnlyStandardElement
要求。元素只包含元素的内容。必须已经成为标准的设备或服务描述的组
成部分。
• 对于设备描述,必须是下列之一:root、specVersion、device、iconList、
icon、serviceList、service 和/或deviceList。
• 对于服务描述,必须是下列之一:scpd、actionList 、action 、
argumentList 、argument、serviceStateTable、stateVariable 、
allowedValueList 和/或allowedValueRange。
X_VendorElement
要求。必须用X_开头。(前缀A_已经保留。)必须有面向xmlns 属
性的值。可以包括任意XML。
根据灵活的XML 处理框架(FXPP)的规定,不了解这些XML 添加
项的控制点必须将其忽略。
2.6 描述:用于设备的UPnP 模板语言
上面的段落说明了UPnP设备描述并说明了一个描述如何从UPnP设备模板
进行例示。根据说明,UPnP 设备模板由UPnP 论坛工作委员会进行制作,这些
模板均源自于UPnP 模板语言。这一模板语言可以为设备和服务定义有效模板。
下面是与设备相关的这一语言的列表和说明。
UPnP 模板语言用XML 句法编写,源自XML 模式(部分1:结构,部分2:
数据类型)。XML 模式提供了一套XML 解释,以便表达语言概念,如要求与可
选元素、元素嵌套以及取值的数据类型等(还有其它与此处无关的属性)。UPnP
模板语言使用这些XML 模式解释来定义specVersion、URLBase、deviceType
以及上面详细介绍的元素。由于UPnP 模板语言使用另外一种精确的语言来解
释,所以它是无岐义的。同时因为UPnP 模板语言、UPnP 设备模板和UPnP
设备描述全部为机器可读型,所以自动工具可以自动进行检查以确保后两者拥有
所有要求的元素,在正确的嵌套内,而且有正确数据类型的值。
下面是面向设备的UPnP 模板语言,在此由UPnP 设备架构进行定义。它定
义的元素用于UPnP 设备模板中;它们在这里用绿色表示,在上面的列表中同
样用绿色表示。下面是定义这些元素的地方;上面是使用它们的地方。
紧随其后的是对于XML 模式元素、属性和所用值的简单说明。章节尾部关
于XML 模式的参考中还有更多详细内容。
用于设备的UPnP 模板语言
<?xml version="1.0"?>
<Schema name="device-1-0"
xmlns="urn:schemas-microsoft-com:xml-data"
xmlns:dt="urn:schemas-microsoft-com:datatypes">
<ElementType name="root" content="eltOnly">
<element type="specVersion" />
<element type="URLBase" minOccurs="0" maxOccurs="1" />
<element type="device" />
</ElementType>
<ElementType name="specVersion" content="eltOnly">
<element type="major" />
<element type="minor" />
</ElementType>
<ElementType name="major" dt:type="int" content="textOnly" />
<ElementType name="minor" dt:type="int" content="textOnly" />
<ElementType name="URLBase" dt:type="uri" content="textOnly" />
<ElementType name="device" content="eltOnly">
<element type="deviceType" />
<element type="friendlyName" />
<element type="manufacturer" />
<element type="manufacturerURL" minOccurs="0" maxOccurs="1" />
<element type="modelDescription" minOccurs="0" maxOccurs="1" />
<element type="modelName" />
<element type="modelNumber" minOccurs="0" maxOccurs="1" />
<element type="modelURL" minOccurs="0" maxOccurs="1" />
<element type="serialNumber" minOccurs="0" maxOccurs="1" />
<element type="UDN" />
<element type="UPC" minOccurs="0" maxOccurs="1" />
<element type="iconList" minOccurs="0" maxOccurs="1" />
<element type="serviceList" />
<element type="deviceList" minOccurs="0" maxOccurs="1" />
<element type="presentationURL" minOccurs="0" maxOccurs="1" />
</ElementType>
<ElementType name="deviceType" dt:type="uri" content="textOnly" />
<ElementType name="friendlyName" dt:type="string" content="textOnly" />
<ElementType name="manufacturer" dt:type="string" content="textOnly" />
<ElementType name="manufacturerURL" dt:type="uri" content="textOnly" />
<ElementType name="modelDescription" dt:type="string" content="textOnly" />
<ElementType name="modelName" dt:type="string" content="textOnly" />
<ElementType name="modelNumber" dt:type="string" content="textOnly" />
<ElementType name="modelURL" dt:type="uri" content="textOnly" />
<ElementType name="serialNumber" dt:type="string" content="textOnly" />
<ElementType name="UDN" dt:type="uri" content="textOnly" />
<ElementType name="UPC" dt:type="string" content="textOnly" />
<ElementType name="iconList" content="eltOnly">
<element type="icon" minOccurs="1" maxOccurs="*" />
</ElementType>
<ElementType name="icon" content="eltOnly">
<element type="mimetype" />
<element type="width" />
<element type="height" />
<element type="depth" />
<element type="url" />
</ElementType>
<ElementType name="mimetype" dt:type="string" content="textOnly" />
<ElementType name="width" dt:type="int" content="textOnly" />
<ElementType name="height" dt:type="int" content="textOnly" />
<ElementType name="depth" dt:type="int" content="textOnly" />
<ElementType name="url" dt:type="uri" content="textOnly" />
<ElementType name="serviceList" content="eltOnly">
<element type="service" minOccurs="1" maxOccurs="*" />
</ElementType>
<ElementType name="service" content="eltOnly">
<element type="serviceType" />
<element type="serviceId" />
<element type="SCPDURL" />
<element type="controlURL" />
<element type="eventSubURL" />
</ElementType>
<ElementType name="serviceType" dt:type="uri" content="textOnly" />
<ElementType name="serviceId" dt:type="uri" content="textOnly" />
<ElementType name="SCPDURL" dt:type="uri" content="textOnly" />
<ElementType name="controlURL" dt:type="uri" content="textOnly" />
<ElementType name="eventSubURL" dt:type="uri" content="textOnly" />
<ElementType name="deviceList" content="eltOnly">
<element type="device" minOccurs="1" maxOccurs="*" />
</ElementType>
<ElementType name="presentationURL" dt:type="uri" content="textOnly" />
</Schema>
ElementType
用全新的衍生语言定义一个元素。名称属性定义了元素的名称。dt:type
属性用全新的衍生语言定义了元素值的数据类型。
element
参考一个元素的目的是宣布嵌套。minOccurs 属性定义了元素必须发生的
最少次数;缺省为minOccurs = 1;可选元素有minOccurs = 0。
maxOccurs 属性定义了元素必须发生的最多次数;缺省为maxOccurs =
1;元素显示一次或多次使用maxOccurs = *。
2.7 描述:用于服务的UPnP 模板语言
上面的段落说明了UPnP服务描述并解释了一个描述如何从UPnP设备模板
进行例示。与UPnP 设备模板相同,UPnP 设备模板也是由UPnP 论坛工作委员
会进行制作,这些模板均源自于UPnP 模板语言。这一模板语言可以为设备和
服务定义有效模板。像上面说明的一样,UPnP 模板语言用XML 句法编写,源
自XML 模式(部分1:结构,部分2:数据类型)。下面是与服务相关的语言
列表。它定义的元素用于UPnP 服务模板中;它们在这里用绿色表示,在上面
的列表中同样用绿色表示。下面是定义这些元素的地方;上面是使用它们的地方。
紧随其后的是对于XML 模式元素、属性和所用值的简单说明。章节尾部关
于XML 模式的参考中还有更多详细内容。
用于服务的UPnP 模板语言
<?xml version="1.0"?>
<Schema name="service-1-0"
xmlns="urn:schemas-microsoft-com:xml-data"
xmlns:dt="urn:schemas-microsoft-com:datatypes">
<ElementType name="scpd" content="eltOnly">
<element type="specVersion" />
<element type="actionList" minOccurs="0" maxOccurs="1" />
<element type="serviceStateTable" />
</ElementType>
<ElementType name="specVersion" content="eltOnly">
<element type="major" />
<element type="minor" />
</ElementType>
<ElementType name="major" dt:type="int" content="textOnly" />
<ElementType name="minor" dt:type="int" content="textOnly" />
<ElementType name="actionList" content="eltOnly">
<element type="action" minOccurs="1" maxOccurs="*" />
</ElementType>
<ElementType name="action" content="eltOnly">
<element type="name" />
<element type="argumentList" minOccurs="0" maxOccurs="1" />
</ElementType>
<ElementType name="name" dt:type="string" content="textOnly" />
<ElementType name="argumentList" content="eltOnly">
<element type="argument" minOccurs="1" maxOccurs="*" />
</ElementType>
<ElementType name="argument" content="eltOnly">
<element type="name" />
<element type="direction" />
<element type="retval" minOccurs="0" maxOccurs="1" />
<element type="relatedStateVariable" />
</ElementType>
<ElementType name="direction" dt:type="string" content="textOnly" />
<ElementType name="retval" content="empty" />
<ElementType name="relatedStateVariable" dt:type="string" content="textOnly" />
<ElementType name="serviceStateTable" content="eltOnly">
<element type="stateVariable" minOccurs="1" maxOccurs="*" />
</ElementType>
<ElementType name="stateVariable" content="eltOnly">
<element type="name" />
<element type="dataType" />
<element type="defaultValue" minOccurs="0" maxOccurs="1" />
<group minOccurs="0" maxOccurs="1" order="one">
<element type="allowedValueList" />
<element type="allowedValueRange" />
</group>
<AttributeType name="sendEvents" />
<attribute default="yes" type="sendEvents" required="no" />
</ElementType>
<ElementType name="dataType" dt:type="string" content="textOnly" />
<ElementType name="defaultValue" dt:type="string" content="textOnly" />
<ElementType name="allowedValueList" content="eltOnly">
<element type="allowedValue" minOccurs="1" maxOccurs="*" />
</ElementType>
<ElementType name="allowedValue" content="textOnly" />
<ElementType name="allowedValueRange" content="eltOnly">
<element type="minimum" />
<element type="maximum" />
<element type="step" minOccurs="0" maxOccurs="1" />
</ElementType>
<ElementType name="minimum" dt:type="number" content="textOnly" />
<ElementType name="maximum" dt:type="number" content="textOnly" />
<ElementType name="step" dt:type="number" content="textOnly" />
</Schema>
attribute
参考新的衍生语言中的属性,旨在宣布可能出现元素的地点。与任何XML
元素类似,属性元素可能有它自己的属性。使用这一元素内要求的属性指
示为是否属性必须出现;可选属性表示为required = no。
AttributeType
用全新的衍生语言定义一个新的属性。与任何XML 元素类似,属性元素
可能有它自己的属性。使用这一元素内的名称属性来定义属性的名称,因
为它将用在衍生语言中。
element
参考一个元素的目的是宣布嵌套。minOccurs 属性定义了元素必须发生的
最少次数;缺省为minOccurs = 1;可选元素有minOccurs = 0。
maxOccurs 属性定义了元素必须发生的最多次数;缺省为maxOccurs =
1;元素显示一次或多次使用maxOccurs = *。
ElementType
用全新的衍生语言定义一个元素。名称属性定义元素名称。dt:type 属性
用全新的衍生语言定义元素值的数据类型。型号属性指示使用全新的衍生
语言的元素是否包含此处没有明确规定的元素;当只有以前规定的元素可
以使用时,model = closed。内容属性指示包含哪些内容;只包含其它元
素的元素应该用content = eltOnly;只包含字符串的元素应该用content =
textOnly。
group
将内容组织到一个组中以便规定顺序。minOccurs 属性定义了组必须
发生的最少次数。maxOccurs 属性定义了组必须发生的最大次数。
order 属性限制了元素的顺序;当最多只能出现一个元素时,order =
one。
2.8 描述:增加UPnP 模板语言
服务的一些属性在XML 模式形式中很难捕捉到。尤其是,在描述动作对于
状态变量的效果时十分有用。这一过程信息很难用XML 这样的陈述式语言来描
述,因此下面是推荐UPnP 论坛工作委员会使用的词汇表,在定义服务动作时
使用或由UPnP 厂商在他们希望记录额外动作的效果时使用。
ASSIGN(v 、a )
变量v 成为变量a 的值,即v = a 。v 和a 必须是相同的数据类型。
DECREMENT(v)
等同于INCREMENT(v),将allowedValueRange 步骤作为-step。
DECREMENT_BOUNDED(v)
等同于INCREMENT_BOUNDED(v),将allowedValueRange 步骤作
为-step。
DECREMENT_WRAP(v)
等同于INCREMENT_WRAP(v),将allowedValueRange 步骤作为-step。
INCREMENT(v)
变量v 成为v 加allowedValueRange 步骤的值,即v = v + step。等同于
DECREMENT(v),将allowedValueRange 步骤作为-step。v 必须有
一个数字数据类型,而且必须有一个allowedValueRange 定义。
INCREMENT_BOUNDED(v)
变量v 成为v 加allowedValueRange 步骤的值,即v = v + step。
如果步骤大于0 而且v + step 将大于allowedValueRange 最大值,那
么v 成为最大值。
如果步骤小于0 而且v + step 将小于allowedValueRange 最小值,那
么v 成为最小值。
等同于DECREMENT_BOUNDED(v),将allowedValueRange 步骤作
为-step 。v 必须有一个数字数据类型, 而且必须有一个
allowedValueRange 定义。
INCREMENT_WRAP(v 、c)
变量v 成为v 加allowedValueRange 步骤的值,即v = v + step。
如果步骤大于0,而且v + step 将大于allowedValueRange 最大值,那
么v 将成为最小值加步骤减1,即v = minimum + step – 1;如果步骤为
1,则简化为v = minimum。
如果步骤小于0,而且v + step 将小于allowedValueRange 最小值,那
么v 将成为最大值加步骤加1,即v = maximum + step + 1;如果步骤为
-1,则简化为v = maximum。
等同于DECREMENT_WRAP(v),将allowedValueRange 步骤作为
-step。v 必须有一个数字数据类型,而且必须有一个allowedValueRange
定义。
NEXT_STRING_BOUNDED(v)
变量v 将成为v 的当前值之后的下一个allowedValue。如果v 已经是最
后一个allowedValue,那么v 没有变化。v 必须是一个字符串数据类型,
而且必须有一个allowedValueList 定义。
NEXT_STRING_WRAP(v)
变量v 将成为v 的当前值之后的下一个allowedValue。如果v 已经是最
后一个allowedValue,那么v 将成为第一个allowedValue。v 必须是一
个字符串数据类型,而且必须有一个allowedValueList 定义。
PREV_STRING_BOUNDED(v)
变量v 将成为v 的当前值之前的上一个allowedValue。如果v 已经是第
一个allowedValue,那么v 没有变化。v 必须是一个字符串数据类型,而
且必须有一个allowedValueList 定义。
PREV_STRING_WRAP(v)
变量v 将成为v 的当前值之前的上一个allowedValue。如果v 已经是第
一个allowedValue,那么v 将成为最后一个allowedValue。v 必须是一
个字符串数据类型,而且必须有一个allowedValueList 定义。
SET(v 、c)
变量v 成为常量c 的值,即v = c 。v 和c 必须是相同的数据类型。
TOGGLE(v)
变量v 将成为v 的boolean negation 值,即v = NOT v。v 必须是布尔
(boolean)值。
2.9 描述:取得描述
如上面所说明的,在控制点发现了一个设备之后,控制点仍然对设备知之甚
少。为了让控制点更多地了解设备和它的功能,控制点必须从发现消息中得到设
备描述的URL,通过URL 取得UPnP 设备描述。然后,控制点必须使用设备描
述中提供的URL 取得一个或多个服务描述。这是一个基于HTTP 的简单流程,
使用总体UPnP 协议栈的下列子集。(总体UPnP 协议栈在本文开始处列出。)
UPnP 厂商[ 紫色]
UPnP 论坛[ 红色]
UPnP 设备架构[绿色]
HTTP[黑色]
TCP[黑色]
IP[黑色]
在最高一层,描述消息包含具体的厂商信息,如设备类型、服务类型和要求
的服务。在协议栈接下来的一层,通过来自UPnP 论坛工作委员会的信息(如
型号名称、型号和具体URL)对厂商内容进行了补充。来自以上各层的消息存
储在UPnP 特定协议中,并在本文中进行了定义。依次,上述消息均通过IP 上
的TCP 上的HTTP 来提供。为便于参考,上面[方括弧]中的颜色显示了何种协
议定义下面所列描述消息中的具体标头和消息体元素。
使用这一协议栈,取得UPnP 设备描述就十分简单:控制点向发现消息中的
URL 发出HTTP GET 请求,设备在HTTP 响应的消息体中返回其描述。同样,
在取得UPnP 服务描述时,控制点向设备描述中的URL 发出HTTP GET 请求,
设备在HTTP 响应的消息体中返回其描述。响应和请求的标头和消息体将在下
面详细说明。
首先,一个控制点必须以下列格式发送一个带有方法GET 的请求。用斜体
表示的值为实际值的占位符。
GET path to description HTTP/1.1
HOST:host for description:port for description
ACCEPT-LANGUAGE:language preferred by control point
(无面向取得描述的请求的消息体,但请注意,消息与最后一个HTTP 标头
之间必须空一行。)
以下列出了上述列表中出现的命令行和标头的详细信息。除特别说明外,所
有标头值要区分大小写。
命令行
GET
方法由HTTP 定义。
描述的路径
设备描述URL(发现消息中的LOCATION 标头)或服务描述URL(设
备描述中的SCPDURL 元素)的路径部分。单一、相对URL。
HTTP/1.1
HTTP 版本。
标头
HOST
要求。设备描述URL(发现消息中的LOCATION 标头)或服务描述URL
(设备描述中的SCPDURL 元素)的域名或IP 地址及可选端口部分。如
果该端口为空或未给出,则假定为端口80。
ACCEPT-LANGUAGE
对于取得设备的描述。用于描述的优选语言。如果该语言中没有描述可用,
则设备可以返回使用缺省语言的描述。RFC1766 语言标签。
在控制点发送请求之后,设备采取第二个步骤,用描述的副本做出响应。其
中包括预期的传输时间,设备必须在30 秒内做出响应。如果在这段时间内没有
响应,控制点应该再次发送请求。设备必须采用以下格式发送响应:用斜体表示
的值为实际值的占位符。
HTTP/1.1 200 OK
CONTENT-LANGUAGE:language used in description
CONTENT-LENGTH:Bytes in body
CONTENT-TYPE:text/xml
DATE:when responded
正如上面的详细说明所指出的,这一响应的消息体是UPnP 设备或服务描
述。
以上标头清单所含信息如下:除特别说明外,所有标头值要区分大小写。
标头
CONTENT-LANGUAGE
仅当请求包括ACCEPT-LANGUAGE 标头时要求。描述的语言。RFC1766
语言标签。
CONTENT-LENGTH
要求。消息体长度以字节来表示,为整数。
CONTENT-TYPE
要求。必须是text/xml。
DATE
推荐使用。响应生成时间。RFC1123 日期。
SERVER
(描述消息不要求SERVER 标头。)
2.10 描述参考
FXPP
灵活的XML 处理框架。规定未知的XML 元素及其子元素必须被忽略。
IETF 草案。
ISO 8601
ISO(国际标准化组织)。用日期和时间来表示,1988-06-15。公布在:
<http://www.iso.ch/markete/8601.pdf>。
RFC1123
包括日期格式,如HTTP DATE 标头。IETF RFC。
RFC1766
语言标签的格式,如HTTP ACCEPT-LANGUAGE 标头。IETF RFC。
RFC2387
代表内容类型的格式,如用于图标的mimetype 元素。IETF RFC。
UPC
通用产品代码。12 位全数字代码,用于确定销售包装。由统一编码委员
会进行管理。
<http://www.uc-council.org/main/ID_Numbers_and_Bar_Codes.html>。
XML
扩展标记语言。W3C 推荐。
XML 模式(部分1:结构,部分2:数据类型)。
语法定义UPnP 模板语言。使用XML 进行定义。W3C 工作草案。部分1:
结构。部分2:数据类型。
3. 控制:
控制是UPnP 网络的第3 步。首先是“寻址”(第0 步),设备会获得一个网
络地址;之后是“发现”(第1 步),控制点会发现相关设备;再后是“描述”
(第2 步),控制点会了解设备能力。控制独立于事件(第4 步),通过事件
控制点可了解设备的状态变化。通过控制,控制点向设备发出动作,并轮询相关
状态值。控制和事件是展示(第5 步)的补充,通过展示控制点会显示设备提供
的用户界面。
控制是UPnP 网络的第3 步。在接收设备和服务描述之后,控制点可以向这些
服务发出动作,同时控制点也可以轮询服务的状态变量值。发出动作实质上是一
种远程过程调用;控制点将动作发送到设备服务,在动作完成(或失败)后,服
务返回相应的结果或错误。状态变量值轮询是这种场景下的特例,动作及其结果
都是预定义的。
为了控制一个设备,控制点向设备服务发出一个动作。这一般由控制点向服务的
控制URL 地址(在设备描述的服务元素controlURL 子元素部分提供)发送一个
适当的控制消息。而服务则会对此动作做出响应,返回相关结果或错误。动作的
效果可以通过改变描述服务运行时状态的变量进行建模。在这些状态变量改变
时,事件将被发布到所有相关的控制点。该部分介绍了控制消息的协议栈和格式。
“事件”部分介绍了事件发布。
控制点可能会轮询服务的状态变量值以获得状态变量的当前值。与发出一个动作
的过程相似,控制点向服务的控制URL 发送一个适当的查询消息。而服务则返
回相应的变量值;每个服务必须保持状态表的一致性,以便控制点能够轮询并接
收到有意义的值。本部分还介绍了这些查询消息的格式。“事件”部分介绍了变
量值的自动通知。
只要设备的发现宣告没有过期,控制点就会假定该设备及其服务可用。如果设备
取消其宣告,则控制点必将认为该设备及其服务不再可用。
UPnP 定义了发出动作和轮询变量值的方法,但UPnP 不会规定或约束在控制点
上运行应用的API 设计;操作系统厂商可以创建满足其客户需求的API。
本章节其余部分详细介绍了如何对控制和查询消息进行格式编排并发送到设备。
3.1 控制:协议
要发出动作和轮询变量值,控制点(和设备)会使用以下总体UPnP 协议栈的
子集。(总体UPnP 协议栈在本文开始处列出。)
UPnP 厂商[ 紫色]
UPnP 论坛[ 红色]
UPnP 设备架构[绿色]
SOAP[蓝色]
HTTP[黑色]
TCP[黑色]
IP[黑色]
在最高一层,控制消息包括特定的厂商信息,如变量值。在协议栈接下来的一层,
通过来自UPnP 论坛工作委员会的信息(如动作名称、变量名称、变量名称)
对厂商内容进行了补充。来自以上各层的消息存储在UPnP 特定协议中,并在
本文中进行了定义。采用简单对象访问协议(SOAP)标头和消息体元素依次对
上述消息进行格式编排,并通过HTTP、TCP/IP 进行发送。为便于参考,上文[方
括弧]中的颜色显示出哪个协议定义下列订阅消息中的具体标头元素。
3.2 控制:动作
控制点会向设备的服务发出动作,并接收结果或错误返回。该动作、结果和错误
密封在SOAP 中,通过HTTP 请求发送,并通过HTTP 响应接收。
3.2.1 控制:动作:调用
简单对象访问协议(SOAP)定义使用XML 和HTTP 的远程过程调用。UPnP
使用SOAP 来向设备提供控制消息,并将结果或错误返回控制点。
SOAP 定义额外的HTTP 标头,以确保这些不会与其它HTTP 扩展混淆,SOAP
遵循HTTP 扩展框架,在MAN 标识中指定SOAP 独特URI,并在HTTP 方法
中采用M-作为前缀。在这种情况下,此方法为M-POST。使用M-POST 要求
HTTP 服务器发现并了解SOAP 独特URI 和SOAP 特定标头。
为了向防火墙和代理提供更大的管理灵活性,SOAP 规定首先必须在不带MAN
标头或M-前缀的情况下尝试请求。如果请求被拒绝并返回“405 Method Not
Allowed”信息,则必须使用MAN 标头和M-前缀发送第二个请求。如果请求拒
绝并返回“501 Not Implemented”或“510 Not Extended”信息,则请求失败。
(其它HTTP 请求应根据HTTP 规范进行处理。)
下面是一个使用POST 方法发送的控制消息列表(没有MAN 标头),随后是标
头和消息体的解释。在这之后是一个采用M-POST 方法和MAN 标头发送的控
制消息列表。
为了向设备的服务发出一个动作,控制点必须采用以下格式的POST 方法发送
一个请求。用斜体表示的值为实际值的占位符。
POST path of control URL HTTP/1.1
HOST: host of control URL:port of control URL
CONTENT-LENGTH: bytes in body
CONTENT-TYPE: text/xml; charset="utf-8"
SOAPACTION: "urn:schemas-upnp-org:service:serviceType:v#actionName"
<s:Envelope
xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"
s:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<s:Body>
<u:actionName xmlns:u="urn:schemas-upnp-org:service:serviceType:v">
<argumentName>in arg value</argumentName>
other in args and their values go here, if any
</u:actionName>
</s:Body>
</s:Envelope>
以下列出了上述列表中出现的命令行、标头和消息体元素的详细信息。所有标头
值和元素名称均区分大小写;除特别注明外,值不区分大小写。除特别注明外,
元素的顺序无关紧要。除特别注明外,所要求的元素必须出现一次(无重复),
推荐或可选元素最多只能出现一次。
命令行
POST
方法由HTTP 定义。
路径控制URL。
控制此服务的URL 路径组件(设备描述服务元素的controlURL 子元素)。
单一、相对URL。
HTTP/1.1
HTTP 版本。
标头
HOST
要求。控制此服务的域名或IP 地址、以及URL 可选端口组件(设备描述
服务元素的controlURL 子元素)。如果该端口为空或未给出,则假定为
端口80。
ACCEPT-LANGUAGE
(控制消息中未使用ACCEPT-LANGUAGE 标头。)
CONTENT-LENGTH
要求。消息体长度以字节来表示,为整数。
CONTENT-TYPE
要求。必须是text/xml。应包括使用的字符编码,如utf-8。
MAN
(采用方法POST 不要求MAN 标头。)
SOAPACTION
SOAP 规定使用的标头。必须是要调用的服务类型、散列符号和动作名称,
均用双引号括起来。如果用于采用M-POST 方法的请求,标头名称必须
符合MAN 标头中定义的HTTP 名字空间。单一URI。
消息体:
信包
SOAP 规定使用的元素。Xmlns 名字空间属性必须为
“http://schemas.xmlsoap.org/soap/envelope/”。必须包括带有值为
“http://schemas.xmlsoap.org/soap/encoding/”的encodingStyle 属性。
包含以下子元素:
消息体
SOAP 规定使用的元素。应符合SOAP 名字空间。包含以下子元素:
actionName
要求。元素名称即要调用的动作名称。xmlns 名字空间属性必须
为双引号中包含的服务类型。必须为消息体的第一个子元素。包
含以下有序子元素:
argumentName
如果且仅当动作带有输入变量时要求。传送给动作的值。输
入变量中的每个动作重复一次。(元素名称不符合名字空间;
元素嵌套上下文足够。)单一数据类型由UPnP 服务描述定
义。
为了获得未来可伸缩性,在处理上述XML 时要遵守灵活XML 处理框架(FXPP),
设备和控制点必须忽略:(a) 任何未知元素及其子元素或内容,以及(b)任何未知
属性及其值。
如果一个带有POST 的请求被拒绝并返回“405 Method Not Allowed”信息,
则控制点必须采用以下格式的M-POST 和MAN 方法发送第二个请求。用斜体
表示的值为实际值的占位符。
M-POST path of control URL HTTP/1.1
HOST: host of control URL:port of control URL
CONTENT-LENGTH: bytes in body
CONTENT-TYPE: text/xml; charset="utf-8"
MAN: "http://schemas.xmlsoap.org/soap/envelope/"; ns=01
01-SOAPACTION: "urn:schemas-upnp-org:service:serviceType:v#actionName"
(带有M-POST 方法的请求消息消息体与带有POST 方法的请求消息体相同。
详见如上说明。)
命令行
M-POST
方法由HTTP 扩展框架定义。
控制URL 的路径。
控制此服务的URL 路径组件(设备描述服务元素的controlURL 子元素)。
单一、相对URL。
HTTP/1.1
HTTP 版本。
标头
HOST
要求。控制此服务的域名或IP 地址、以及URL 可选端口组件(设备描述
服务元素的controlURL 子元素)。如果该端口为空或未给出,则假定为
端口80。
ACCEPT-LANGUAGE
(控制消息中未使用ACCEPT-LANGUAGE 标头。)
CONTENT-LENGTH
要求。消息体长度以字节来表示,为整数。
CONTENT-TYPE
要求。必须是text/xml。应包括使用的字符编码,如utf-8。
MAN
要求。必须为“http://schemas.xmlsoap.org/soap/envelope/”。ns 指令
定义用于其它SOAP 标头的名字空间(如01)(如SOAPACTION)。
SOAPACTION
SOAP 规定使用的标头。必须是要调用的服务类型、散列符号和动作名称,
均用双引号括起来。如果用于采用M-POST 方法的请求,标头名称必须
符合MAN 标头中定义的HTTP 名字空间。单一URI。
3.2.2 控制:动作:响应
该服务必须完成动作调用,并在30 秒内响应,包括预计的传送时间。应对需要
用较长时间的动作进行定义,以便在动作完成后尽早返回并发送一个事件。如果
服务在此时间内未能响应,则控制点的操作应视具体应用而定。服务必须采用以
下格式发送响应:用斜体表示的值为实际值的占位符。
HTTP/1.1 200 OK
CONTENT-LENGTH: bytes in body
CONTENT-TYPE: text/xml; charset="utf-8"
DATE: when response was generated
EXT:
SERVER: OS/version UPnP/1.0 product/version
<s:Envelope
xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"
s:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<s:Body>
<u:actionNameResponse xmlns:u="urn:schemas-upnp-org:service:serviceType:v">
<argumentName>out arg value</argumentName>
other out args and their values go here, if any
</u:actionNameResponse>
</s:Body>
</s:Envelope>
以下列出了上述列表中出现的命令行、标头和消息体元素的详细信息。所有标头
值和元素名称均区分大小写;除特别注明外,值不区分大小写。除特别注明外,
元素的顺序无关紧要。除特别注明外,所要求的元素必须出现一次(无重复),
推荐或可选元素最多只能出现一次。
响应行
HTTP/1.1
HTTP 版本。
200 OK
HTTP 成功代码。
标头
CONTENT-LANGUAGE
(控制消息中未使用ACCEPT-LANGUAGE 标头。)
CONTENT-LENGTH
要求。消息体长度以字节来表示,为整数。
CONTENT-TYPE
要求。必须是text/xml。应包括使用的字符编码,如utf-8。
DATE
推荐使用。响应生成时间。RFC1123 日期。
EXT
要求。确定MAN 标头已被理解。(只限标头,无值。)
SERVER
要求。一系列操作系统名称、操作系统版本、UPnP/1.0、产品名称以及
产品版本信息。字符串。
消息体
信包
SOAP 规定使用的元素。xmlns 名字空间属性必须为
“http://schemas.xmlsoap.org/soap/envelope/”。必须包括带有值为
“http://schemas.xmlsoap.org/soap/encoding/”的encodingStyle 属性。
包含以下子元素:
消息体
SOAP 规定使用的元素。应符合SOAP 名字空间。包含以下子元素:
actionNameResponse
要求。元素名称即前置于响应的动作名称。xmlns 名字空间属性
必须为双引号中包含的服务类型。必须为消息体的第一个子元素。
包含以下子元素:
argumentName
如果且仅当动作带有输出变量时要求。值从动作中返回。输
出变量中的每个动作重复一次。如果动作带有标记为retval
的变量,则此变量必须为第一个元素。(元素名称不符合名
字空间;元素嵌套上下文足够。)单一数据类型由UPnP 服
务描述定义。
为了获得未来可伸缩性,在处理上述XML 时要遵守灵活XML 处理框架(FXPP),
设备和控制点必须忽略:(a) 任何未知元素及其子元素或内容,以及(b)任何未知
属性及其值。
如果服务在调用控制点发送的动作时出现错误,则服务必须在30 秒内发送响应,
包括预计的传送时间。不能使用输出变量来传达错误信息;输出变量只能用于返
回数据;错误响应必须采用以下格式发送。用斜体表示的值为实际值的占位符。
HTTP/1.1 500 Internal Server Error
CONTENT-LENGTH: bytes in body
CONTENT-TYPE: text/xml; charset="utf-8"
DATE: when response was generated
EXT:
SERVER: OS/version UPnP/1.0 product/version
<s:Envelope
xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"
s:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<s:Body>
<s:Fault>
<faultcode>s:Client</faultcode>
<faultstring>UPnPError</faultstring>
<detail>
<UPnPError xmlns="urn:schemas-upnp-org:control-1-0">
<errorCode>error code</errorCode>
<errorDescription>error string</errorDescription>
</UPnPError>
</detail>
</s:Fault>
</s:Body>
</s:Envelope>
以下列出了上述列表中出现的命令行、标头和消息体元素的详细信息。所有标头
值和元素名称均区分大小写;除特别注明外,值不区分大小写。除特别注明外,
元素的顺序无关紧要。除特别注明外,所要求的元素必须出现一次(无重复),
推荐或可选元素最多只能出现一次。
响应行
HTTP/1.1
HTTP 版本。
500 内部服务器错误
HTTP 错误代码。
标头
CONTENT-LANGUAGE
(控制消息中未使用ACCEPT-LANGUAGE 标头。)
CONTENT-LENGTH
要求。消息体长度以字节来表示,为整数。
CONTENT-TYPE
要求。必须是text/xml。应包括使用的字符编码,如utf-8。
DATE
推荐使用。响应生成时间。RFC1123 日期。
EXT
要求。确定MAN 标头已被理解。(只限标头,无值。)
SERVER
要求。一系列操作系统名称、操作系统版本、UPnP/1.0、产品名称以及
产品版本信息。字符串。
消息体
信包
SOAP 规定使用的元素。xmlns 名字空间属性必须为
“http://schemas.xmlsoap.org/soap/envelope/”。必须包括带有值为
“http://schemas.xmlsoap.org/soap/encoding/”的encodingStyle 属性。
包含以下子元素:
消息体
SOAP 规定使用的元素。应符合SOAP 名字空间。包含以下子元素:
错误
SOAP 规定使用的元素。调用动作时遇到的错误。应符合SOAP
名字空间。包含以下子元素:
faultcode
SOAP 规定使用的元素。值必须符合SOAP 名字空间。值必
须为Client。
faultstring
SOAP 规定使用的元素。值必须为UPnPError。
详细信息
SOAP 规定使用的元素。
UPnPError
UPnP 规定使用的元素。
errorCode
UPnP 规定使用的元素。代码识别遇到过哪些错误。
立即查看下表的值。整数。
errorDescription
UPnP 规定使用的元素。简短描述。立即查看下表的
值。字符串。推荐< 256 字符。
下表概括定义了errorCode 和errorDescription 元素的错误类型和相应值。
errorCode errorDescription 描述
401 Invalid Action
这一服务中该名称没有动作。
402 Invalid Args 可能如下所示:not enough in args、too many in args、no in arg by that name、one or
more in args 均为错误数据类型。
403 Out of Sync 不同步
501 Action Failed 可能在当前服务状态下返回,以避免调用此动作。
600-699 TBD 一般动作错误。由UPnP 论坛技术委员会定义。
700-799 TBD 面向标准动作的特定动作错误。由UPnP 论坛工作委员会定义。
800-899 TBD 面向非标准动作的特定动作错误。由UPnP 厂商定义。
为了获得未来可伸缩性,在处理上述XML 时要遵守灵活XML 处理框架(FXPP),
设备和控制点必须忽略:(a) 任何未知元素及其子元素或内容,以及(b)任何未知
属性及其值。
3.3 控制:查询变量
除了向设备的服务发出动作,控制点还可以对服务进行轮询,以通过发送查询消
息获得状态变量值。查询消息只能查询一个状态变量,必须发送多个查询消息以
查询多个状态变量。
此查询消息与该服务的事件(如果有)相分离。如果变量适度,则变量值查询通
常会生成比通过事件触发收到的值更新的值。Eventing 部分描述了事件适度。
3.3.1 控制:查询:调用
要查询状态变量值,控制点必须采用以下格式发送请求。用斜体表示的值为实际
值的占位符。
POST path of control URL HTTP/1.1
HOST: host of control URL:port of control URL
CONTENT-LENGTH: bytes in body
CONTENT-TYPE: text/xml; charset="utf-8"
SOAPACTION: "urn:schemas-upnp-org:control-1-0#QueryStateVariable"
<s:Envelope
xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"
s:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<s:Body>
<u:QueryStateVariable xmlns:u="urn:schemas-upnp-org:control-1-0">
<u:varName>variableName</u:varName>
</u:QueryStateVariable>
</s:Body>
</s:Envelope>
以下列出了上述列表中出现的命令行、标头和消息体元素的详细信息。所有标头
值和元素名称均区分大小写;除特别注明外,值不区分大小写。除特别注明外,
元素的顺序无关紧要。除特别注明外,所要求的元素必须出现一次(无重复),
推荐或可选元素最多只能出现一次。
命令行
POST
方法由HTTP 定义。
控制URL 的路径。
控制此服务的URL 路径组件(设备描述服务元素的controlURL 子元素)。
单一、相对URL。
HTTP/1.1
HTTP 版本。
标头
HOST
要求。控制此服务的域名或IP 地址、以及URL 可选端口组件(设备描述
服务元素的controlURL 子元素)。如果该端口为空或未给出,则假定为
端口80。
ACCEPT-LANGUAGE
(控制消息中未使用ACCEPT-LANGUAGE 标头。)
CONTENT-LENGTH
要求。消息体长度以字节来表示,为整数。
CONTENT-TYPE
要求。必须是text/xml。应包括使用的字符编码,如utf-8。
MAN
(采用方法POST 不要求MAN 标头。)
SOAPACTION
SOAP 规定使用的标头。必须为“ urn :
schemas-upnp-org:control-1-0#QueryStateVariable”。如果用于采
用M-POST 方法的请求,标头名称必须符合MAN 标头中定义的HTTP
名字空间。单一URI。
消息体
信包
SOAP 规定使用的元素。xmlns 名字空间属性必须为
“http://schemas.xmlsoap.org/soap/envelope/”。必须包括带有值为
“http://schemas.xmlsoap.org/soap/encoding/”的encodingStyle 属性。
包含以下子元素:
消息体
SOAP 规定使用的元素。应符合SOAP 名字空间。包含以下子元素:
QueryStateVariable
UPnP 规定使用的元素。动作名称。xmlns 名字空间属性必须为
“urn:schemas-upnp-org:control-1-0”。必须为消息体的第
一个子元素。包含以下顺序排列的子元素:
varName
UPnP 规定使用的元素。变量名称。必须符合
QueryStateVariable 名字空间。值是要查询的状态变量的名
称。字符串。
为了获得未来可伸缩性,在处理上述XML 时要遵守灵活XML 处理框架(FXPP),
设备和控制点必须忽略:(a) 任何未知元素及其子元素或内容,以及(b)任何未知
属性及其值。
如果一个带有POST 的请求被拒绝并返回“405 Method Not Allowed”信息,
则控制点必须采用上述M-POST 和MAN 方法发送第二个请求。
3.3.2 控制:查询:响应
要响应状态变量值的查询,服务必须在30 秒内响应,包括预计的传送时间。如
果服务在此时间内未能响应,则控制点的操作应视具体应用而定。服务必须采用
以下格式发送响应:用斜体表示的值为实际值的占位符。
HTTP/1.1 200 OK
CONTENT-LENGTH: bytes in body
CONTENT-TYPE: text/xml; charset="utf-8"
DATE: when response was generated
EXT:
SERVER: OS/version UPnP/1.0 product/version
<s:Envelope
xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"
s:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<s:Body>
<u:QueryStateVariableResponse xmlns:u="urn:schemas-upnp-org:control-1-0">
<return>variable value</return>
</u:QueryStateVariableResponse>
</s:Body>
</s:Envelope>
以下列出了上述列表中出现的命令行、标头和消息体元素的详细信息。所有标头
值和元素名称均区分大小写;除特别注明外,值不区分大小写。除特别注明外,
元素的顺序无关紧要。除特别注明外,所要求的元素必须出现一次(无重复),
推荐或可选元素最多只能出现一次。
响应行
HTTP/1.1
HTTP 版本。
200 OK
HTTP 成功代码。
标头
CONTENT-LANGUAGE
(控制消息中未使用ACCEPT-LANGUAGE 标头。)
CONTENT-LENGTH
要求。消息体长度以字节来表示,为整数。
CONTENT-TYPE
要求。必须是text/xml。应包括使用的字符编码,如utf-8。
DATE
推荐使用。响应生成时间。RFC1123 日期。
EXT
要求。确定MAN 标头已被理解。(只限标头,无值。)
SERVER
要求。一系列操作系统名称、操作系统版本、UPnP/1.0、产品名称以及
产品版本信息。字符串。
消息体
信包
SOAP 规定使用的元素。xmlns 名字空间属性必须为
“http://schemas.xmlsoap.org/soap/envelope/”。必须包括带有值为
“http://schemas.xmlsoap.org/soap/encoding/”的encodingStyle 属性。
包含以下子元素:
消息体
SOAP 规定使用的元素。应符合SOAP 名字空间。包含以下子元素:
QueryStateVariableResponse
所要求的元素由UPnP 和SOAP 定义。xmlns 名字空间属性必须
为“urn:schemas-upnp-org:control-1-0”。必须为消息体的
第一个子元素。包含以下子元素:
返回
UPnP 规定使用的元素。(元素名称不符合名字空间;元素
嵌套上下文足够。)值为当前状态变量值,应要求在varName
元素中列出。
为了获得未来可伸缩性,在处理上述XML 时要遵守灵活XML 处理框架(FXPP),
设备和控制点必须忽略:(a) 任何未知元素及其子元素或内容,以及(b) 任何未
知属性及其值。
如果服务不能为此变量提供一个值,则该服务必须在30 秒内发送一个响应,包
括预计的传送时间。响应必须采用以下格式:用斜体表示的值为实际值的占位符。
HTTP/1.1 500 Internal Server Error
CONTENT-LENGTH: bytes in body
CONTENT-TYPE: text/xml; charset="utf-8"
DATE: when response was generated
EXT:
SERVER: OS/version UPnP/1.0 product/version
<s:Envelope
xmlns:s="http://schemas.xmlsoap.org/soap/envelope/"
s:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<s:Body>
<s:Fault>
<faultcode>s:Client</faultcode>
<faultstring>UPnPError</faultstring>
<detail>
<UPnPError xmlns="urn:schemas-upnp-org:control-1-0">
<errorCode>error code</errorCode>
<errorDescription>error string</errorDescription>
</UPnPError>
</detail>
</s:Fault>
</s:Body>
</s:Envelope>
以下列出了上述列表中出现的命令行、标头和消息体元素的详细信息。所有标头
值和元素名称均区分大小写;除特别注明外,值不区分大小写。除特别注明外,
元素的顺序无关紧要。除特别注明外,所要求的元素必须出现一次(无重复),
推荐或可选元素最多只能出现一次。
响应行
HTTP/1.1
HTTP 版本。
500 内部服务器错误
HTTP 错误代码。
标头
CONTENT-LANGUAGE
(控制消息中未使用ACCEPT-LANGUAGE 标头。)
CONTENT-LENGTH
要求。消息体长度以字节来表示,为整数。
CONTENT-TYPE
要求。必须是text/xml。应包括使用的字符编码,如utf-8。
DATE
推荐使用。响应生成时间。RFC1123 日期。
EXT
要求。确定MAN 标头已被理解。(只限标头,无值。)
SERVER
要求。一系列操作系统名称、操作系统版本、UPnP/1.0、产品名称以及
产品版本信息。字符串。
消息体
信包
SOAP 规定使用的元素。xmlns 名字空间属性必须为
“http://schemas.xmlsoap.org/soap/envelope/”。必须包括带有值为
“http://schemas.xmlsoap.org/soap/encoding/”的encodingStyle 属性。
包含以下子元素:
消息体
SOAP 规定使用的元素。应符合SOAP 名字空间。包含以下子元素:
错误
SOAP 规定使用的元素。为何该服务不会为变量返回一个值。应
符合SOAP 名字空间。包含以下子元素:
faultcode
SOAP 规定使用的元素。应符合SOAP 名字空间。值必须为
Client。
faultstring
SOAP 规定使用的元素。描述errorCode 的一般UPnP 字符
串。立即查看下表的值。
detail
SOAP 规定使用的元素。包含以下子元素:
UPnPError
UPnP 规定使用的元素。包含以下子元素:
errorCode
UPnP 规定使用的元素。代码识别遇到过哪些错误。
立即查看下表的值。整数。
errorDescription
UPnP 规定使用的元素。简短描述。立即查看下表的
值。字符串。推荐< 256 字符。
下表概括定义了errorCode 和errorDescription 元素的错误类型和相应值。
errorCode errorDescription 描述
404 Invalid Var 这一服务中该名称没有动作。
600-624 TBD 一般动作错误。由UPnP 论坛技术委员会定义。
625-649 TBD 留作未来使用。
650-674 TBD 面向标准动作的特定动作错误。由UPnP 论坛工作委员会定义。
675-699 TBD 面向非标准动作的特定动作错误。由UPnP 厂商定义。
为了获得未来可伸缩性,在处理上述XML 时要遵守灵活XML 处理框架(FXPP),
设备和控制点必须忽略:(a) 任何未知元素及其子元素或内容,以及(b)任何未知
属性及其值。
3.4 控制参考
FXPP
灵活的XML 处理框架。规定未知的XML 元素及其子元素必须被忽略。
IETF 草案。
HTTP 扩展框架
描述针对HTTP 的通用扩展机制。W3C RFC。
RFC1123
包括日期格式,如HTTP DATE 标头。IETF RFC。
SOAP
简单对象访问协议。针对远程过程调用,用XML 定义的、在HTTP 之上
的协议。IETF 草稿和W3C 技术报告。
XML
扩展标记语言。W3C 推荐。
4. 事件
事件是UPnP 网络的第4 步。首先是“寻址”(第0 步),设备会获得一个网
络地址;之后是“发现”(第1 步),控制点会发现相关设备;再后是“描述”
(第2 步),控制点会了解设备能力。“事件触发”与“控制”(第3 步)紧
密相连,第3 步中控制点向设备发送动作。通过“事件触发”,控制点监听设备
的状态变化。控制和事件触发是展示(第5 步)的补充,通过展示控制点会显示
设备提供的用户界面。
控制点发现(1)设备和(2)取得该设备及其服务的描述之后,就拥有了事件
触发功能的要素。正如描述部分所述,一个即插即用服务描述包括服务响应的动
作列表和运行时描述服务状态的变量列表。如果一个或多个状态变量可以被事件
触发,服务将会在这些变量发生变化时发布更新,控制点可以订阅以获得此信息。
通过这一部分, 发布者指事件的来源(通常为设备服务), 订阅者指事件目的地
(通常为控制点)。
要订阅事件,订阅者可发送一条订阅消息。如果订阅者收到此消息,将回复此订
阅的持续时间。要保持订阅,订阅者必须在订阅过期之前进行续订。当订阅者不
再需要发布者发送的事件时,订阅者应当取消其订阅。下面将详细介绍订阅、续
订和取消消息的相关信息。
发布者通过发送事件消息提醒订阅者状态变量改变。事件消息包含多个状态变量
名称和这些变量的当前值,以XML 表示。在订阅者第一次订阅时,需要发送一
个专门的初始化事件消息。该事件消息包含所有事件变量的名称和值,并且允许
订阅者初始化其服务状态模型。为了支持多个控制点,在动作生效后所有订阅者
均会收到通知。由此,将向所有订阅者发送全部事件消息,订阅者会收到所有事
件触发变量的事件消息(不只是一部分)。不管状态变量因何种原因发生改变(无
论为了响应所要求的动作,还是由于服务模拟的状态发生变化)均会发送事件消
息。以下部分详细阐明了事件消息格式的相关信息。
某些状态变量值的改变太快,以致事件触发功能没有意义。另一个方法就是过滤
或缓和由于变量值变化而发送的事件消息数量。某些状态变量所包含的值过大而
使事件触发功能没有意义;因此,或出于其它原因,服务可以将一个或多个状态
变量指定为非事件触发,并且永不向订阅者发送事件消息。为确定此类非事件触
发变量的当前值,控制点必须要对服务进行明确轮询。本部分将介绍服务描述如
何对可变事件触发进行说明。控制部分介绍了如何对服务的变量值进行轮询。
要发送和接收订阅及事件消息,控制点和服务可采用以下总体UPnP 协议栈的
子集。(总体UPnP 协议栈列于本文开始部分)
UPnP 厂商[ 紫色]
UPnP 论坛[ 红色]
UPnP 设备架构[绿色]
HTTP [黑色] GENA [navy]
TCP [黑色]
IP [黑色]
最高一层的订阅和事件消息包含诸如订阅和订阅持续时间或具体变量值等特定
厂商信息。在协议栈接下来的一层,通过来自UPnP 论坛工作委员会的信息(如
服务标识符或变量名)对厂商内容做了补充。根据本文规定,来自上层的消息驻
留在UPnP 特定协议中。而上述消息通过已采用通用事件通知架构(GENA)方
法和标头进行扩展的HTTP 依次被发送。HTTP 消息通过TCP/IP 进行发送。为
便于参考,上文[方括弧]中的颜色显示出哪个协议定义下列订阅消息中的具体标
头元素。
本部分其余部分首先对订阅进行了说明,包括订阅信息、续订信息和取消信
息的详细情况。其次,详细阐述了事件消息如何进行格式安排并发送到控制点,
以及初始化事件消息。最后,介绍了与事件触发相关的UPnP 模板语言。
4.1 事件:订阅
当且仅当在一个或多个状态变量被事件触发时,服务才具有事件触发功能。
如果服务具有事件触发功能,它则可向相关订阅者发布事件消息。发布者保
留订阅者列表,向每个订阅者传达以下信息。
唯一的订阅标识符
要求。必须保证标识符在订阅期间的唯一性,无论这一时期有多长;由发
布者为响应订阅消息而生成。建议全部采用唯一的标识符,以确保唯一性;
单一URI。
事件消息交付URL
要求。由订阅者在订阅消息中提供;单一URL。
事件编号
要求。初始化事件消息的编号为0。必须按顺序对每个后续事件消息编号
进行排序;如果订阅者收到带有顺序号的事件编号,则可以验证事件消息
是否丢失。必须回置到1。应为4 字节(32 位)。一个整数。
订阅持续时间
要求。订阅期满前的时间或持续时间;一个整数或关键字“infinite”(无
限)。
发布者应视其合理维护和交付能力,接受尽可能多的订阅。
发布者希望在电源故障时仍可接受订阅。如果问题非常很小且仅限于设备,
重复利用存储的订阅可以加快恢复,从而使控制点从整个网络故障中得以恢复。
订阅者列表可通过下面介绍的订阅、续订和取消消息以及本部分后面介绍的
事件消息进行更新。
要订阅服务事件,订阅者需向发布者发送一个包含发布者URL、服务标识
符和事件消息交付URL 的订阅消息。订阅消息还应包括要求的订阅持续时间。
面向发布者的URL 和服务标识符可在描述消息中找到。正如描述部分所述,描
述消息包含设备描述。就每个设备而言,设备描述均包含(在其它事物中)一个
事件URL(在eventSubURL 中)和一个服务标识符(在serviceId 元素中),
分别用来对应面向发布者的URL 和服务标识符。面向发布者的URL 必须是唯一
的,与设备中的特定服务相对应。
订阅消息是一个接收所有事件消息的请求。未提供在变量基础上订阅事件消
息的机制。订阅者将接收来自服务的所有事件消息。在设计服务时,应将这一因
素考虑在内。
如果发布者接受订阅消息,它将返回唯一的订阅标识符和订阅持续时间。持
续时间选择应与控制点从网络上退出出频度的假设相匹配;如果控制点每几分钟
就会从网络中退出,那么持续时间也相应较短,以便发布者迅速终止所有期满订
阅者;如果控制点的存在为半永久,那么持续时间也应较长,从而最大限度地减
少与续订相关的处理和流量。
接受订阅后,发布者应尽快向订阅者发送第一个或初始化事件消息。该消息
包含所有事件触发变量的名称和当前值。(每个变量的数据类型和范围在设备描
述中进行了说明。描述部分对这一问题进行了详细介绍。)
为了保持订阅,订阅者必须在订阅过期之前通过发送续订消息进行续订。续
订消息被发送到与订阅消息相同的URL,但续订消息不包括事件消息的交付
URL,而是包括订阅标识符。对续订消息的响应与对订阅消息的响应相同。
如果订阅过期,该订阅标识符将失效,发布者停止向订阅者发送事件消息,
并会清除其订阅者列表。如果订阅者试图发送订阅消息之外的任何消息,发布者
将会以该订阅标识符失效为由而拒收此消息。
当订阅者不再需要来自特定服务的事件触发时,订阅者应取消其订阅。取消
订阅通常可以减少服务、控制点和网络负载。如果一个订阅者突然从网络上退出,
它可能无法再发送取消消息。根据规定,除非续订否则订阅最终将会期满。
订阅者应时刻注意来自发布者的发现消息。如果发布者取消了其宣告,订阅
者应假定其订阅已被取消。
下面对订阅、续订和取消消息的特定格式的请求、响应和错误进行了介绍。
4.1.1 事件触发:订阅:带有NT 和CALLBACK 的订阅
对于设备中的每项服务,描述消息均包含一个事件触发URL(设备描述中
服务元素的eventSubURL 子元素)和UPnP 服务标识符(设备描述中服务元素
的serviceId 子元素)。为订阅特定服务的事件,订阅消息将被发送到该服务的
事件触发URL。(注意,事件触发URL 可能相对于基本URL。)消息中含该服
务的标识符以及事件消息交付URL。订阅消息还可能包含所要求的订阅持续时
间。
要订阅服务事件,订阅者必须通过以下格式,发送一个采用SUBSCRIBE
方法并带有NT 和CALLBACK 标头的请求。用斜体表示的值为实际值的占位符。
SUBSCRIBE publisher path HTTP/1.1
HOST: publisher host:publisher port
CALLBACK: <delivery URL>
NT: upnp:event
TIMEOUT: Second-requested subscription duration
(采用SUBSCRIBE 方法的请求没有消息体,但请注意,该消息与最后一
个HTTP 标头之间必须空一行。)
以下列出了上述列表中出现的命令行和标头的详细信息。除特别注明外,所
有标头值均要区分大小写。
命令行
SUBSCRIBE
方法由GENA 定义。开始订阅或续订。
发布者路径
事件触发URL(设备描述中服务元素的eventSubURL 子元素)路
径组成。单一、相对URL。
HTTP/1.1
HTTP 版本。
标头
HOST
要求。事件触发URL(设备描述中服务元素的eventSubURL 子元
素)的域名或IP 地址和可选端口组件。如果该缺少或为空,则假定
为端口80。
CALLBACK
GENA 规定使用的标头。事件消息发往的位置。由UPnP 厂商规定。
如果有多于1 个URL,则当服务发送事件时,它将依次尝试这些URL
直至成功为止。一个或多个URL 用角括号分开。
NT
GENA 规定使用的标头。通知类型。必须采用upnp:event 形式。
SID
(订阅不采用SID 标头。)
TIMEOUT
建议采用。直到订阅期满所要求的持续时间,秒数或无限时间。由
UPnP 论坛工作委员会推荐。由UPnP 厂商规定。关键字“second”
(秒)后为一个整数(无空格)或关键字“infinite”(无限)。
如果有足够的资源维持订阅,发布者应接受它。为接受订阅,发布者会分配
一个唯一的订阅标识符和持续时间,并发送一个初始化事件消息(本部分后面将
详细介绍)。要接受订阅请求,发布者必须在30 秒(包括预计的传输时间)内
以下列格式发送一个响应。用斜体表示的值为实际值的占位符。
HTTP/1.1 200 OK
DATE: when response was generated
SERVER: OS/version UPnP/1.0 product/version
SID: uuid:subscription-UUID
TIMEOUT: Second-actual subscription duration
(采用SUBSCRIBE 方法的请求没有消息体,但请注意,该消息与最后一
个HTTP 标头之间必须空一行。)
有关上面列表中标头的详细信息如下。除特别注明外,所有标头值均要区分
大小写。
标头
DATE
建议采用。响应生成时间。RFC1123 日期。
SERVER
要求。一系列操作系统名称、操作系统版本、UPnP/1.0、产品名称
以及产品版本信息。字符串。
SID
GENA 规定使用的标头。订阅标识符。必须是唯一的。必须以uuid
开头:由UPnP 厂商规定。单一URI。
TIMEOUT
要求。直到订阅期满的实际持续时间,秒数或无限时间。由UPnP
论坛工作委员会推荐。由UPnP 厂商规定。应大于1800 秒(30 分
钟)。关键字“second”(秒)后为一个整数(无空格)或关键字
“infinite”(无限)。
若发布者不能接受新订阅,或是订阅请求存在错误,发布者必须返回以下一
个错误进行响应。该响应必须在30 秒(包括预计的传输时间)内发出。
错误
不兼容标头
400 Bad Request。如果SID 标头和一个NT 或CALLBACK 标头一
起出现,发布者必须返回HTTP 错误400 Bad Request 进行响应。
缺少或无效的CALLBACK
412 Precondition Failed。如果CALLBACK 标头缺少或不包含有效
的HTTP URL,发布者必须返回HTTP 错误412 Precondition Failed.
进行响应。
无效NT
412 Precondition Failed。如果NT 标题不符合upnp:event,发布者
必须返回HTTP 错误412 Precondition Failed.进行响应。
不能接收订阅
5xx。如果发布者不能接受订阅,它必须返回HTTP 500 系列错误代
码进行响应。
其它错误可能被UPnP 下的协议栈层返回。参考这些协议的相关文档了解
详细信息。
4.1.2 事件触发:续订:通过SID 续订
为续订特定服务的事件,续订消息将被发往该服务的事件触发URL。(注
意:事件触发URL 可能相对于基础URL。)然而,与最初的订阅消息不同,续
订消息既不包含服务标识符也不包含事件消息交付URL,而是包含由发布者分
配的订阅标识符,为续订提供明确的参考。与订阅消息相同,续订消息还可能包
含所要求的订阅持续时间。
续订消息采用与订阅消息相同的方法,但这两种消息使用的是一组不相关的
标头;续订消息使用SID 标头,而订阅消息使用NT 和CALLBACK 标头。包含
SID 和NT 或CALLBACK 标头的消息是一个错误。
要续订服务事件,订阅者必须以下列格式发送一个采用SUBSCRIBE 方法
和SID 标头的请求。用斜体表示的值为实际值的占位符。
SUBSCRIBE publisher path HTTP/1.1
HOST: publisher host:publisher port
SID: uuid:subscription UUID
TIMEOUT: Second-requested subscription duration
(采用SUBSCRIBE 方法的请求没有消息体,但请注意,该消息与最后一
个HTTP 标头之间必须空一行。)
以下列出了上述列表中出现的命令行和标头的详细信息。除特别注明外,所
有标头值均要区分大小写。
命令行
SUBSCRIBE
方法由GENA 定义。开始订阅或续订。
发布者路径
事件URL(设备描述中服务元素的eventSubURL 子元素)的路径
组成。单一、相对URL。
HTTP/1.1
HTTP 版本。
标头
HOST
要求。事件触发URL(设备描述中服务元素的eventSubURL 子元
素)的域名或IP 地址和可选端口组件。如果该缺少或为空,则假定
为端口80。
CALLBACK
(续订事件订阅不使用CALLBACK 标头。)
NT
(续订事件订阅不使用NT 标头。)
SID
GENA 规定使用的标头。订阅标识符。发布者必须指定订阅标识符来
响应订阅请求。必须是唯一的。必须以uuid 开头:由UPnP 厂商规
定。单一URI。
TIMEOUT
推荐使用。直到订阅期满所要求的持续时间,秒数或无限时间。由
UPnP 论坛工作委员会推荐。由UPnP 厂商规定。关键字“second”
(秒)后为一个整数(无空格)或关键字“infinite”(无限)。
要接受续订,发布者需重新分配一个订阅持续时间,且必须以与响应新订阅
请求相同的格式发送一个响应。(无初始化事件消息。)
若发布者不能接受续订,或是续订请求存在错误,发布者发送下列一个错误
进行响应。该响应必须在30 秒(包括预计的传输时间)内发出。
错误
不兼容标头
400 Bad Request。如果SID 标头和一个NT 或CALLBACK 标头一
起出现,发布者必须返回HTTP 错误400 Bad Request 进行响应。
无效SID
412 Precondition Failed。如果SID 没有响应一个未过期的已知订阅,
则发布者必须返回HTTP 错误412 Precondition Failed.进行响应。
缺少SID
412 Precondition Failed。如果SID 标头缺少或为空,发布者必须返
回HTTP 错误412 Precondition Failed.进行响应。
不能接受续订
5xx。如果发布者不能接受续订,则必须返回HTTP 500 系列错误代
码进行响应。
其它错误可能会被UPnP 下的协议栈层返回。参考这些协议的相关文档了
解详细信息。
4.1.3 事件:取消订阅:UNSUBSCRIBE
当不再需要来自特定服务的事件时,需要向该服务的事件触发URL 发送取
消消息。(注意:事件触发URL 可能相对于基本URL。)该信息包含订阅标识
符。取消订阅通常可以减少服务、控制点和网络负载。如果一个控制点突然从网
络上退出,它可能无法再发送取消消息。根据规定,除非续订否则订阅最终将会
自行期满。
要取消服务事件的订阅, 订阅者必须以下列格式发送一个采用
UNSUBSCRIBE 方法的请求。用斜体表示的值为实际值的占位符。
UNSUBSCRIBE publisher path HTTP/1.1
HOST: publisher host:publisher port
SID: uuid:subscription UUID
(采用UNSUBSCRIBE 方法的请求没有消息体,但请注意,该消息与最后
一个HTTP 标头之间必须空一行。)
以下列出了上述列表中出现的命令行和标头的详细信息。除特别注明外,所
有标头值均要区分大小写。
命令行
UNSUBSCRIBE
方法由GENA 定义。取消订阅。
发布者路径
事件URL(设备描述中服务元素的eventSubURL 子元素)的路径
组成。单一、相对URL。
HTTP/1.1
HTTP 版本。
标头
HOST
要求。事件URL(设备描述中服务元素的eventSubURL 子元素)
的域名或IP 地址和可选端口组件。如果该端口缺少或为空,则假定
为端口80。
CALLBACK
(取消事件订阅不使用CALLBACK 标头。)
NT
(取消事件订阅不使用NT 标头。)
SID
GENA 规定使用的标头。订阅标识符。发布者必须分配订阅标识符来
响应订阅请求。必须是唯一的。必须以uuid 开头:由UPnP 厂商规
定。单一URI。
TIMEOUT
(取消事件订阅不使用TIMEOUT 标头。)
要取消订阅,发布者必须在30 秒(包括预计的传输时间)内以下面的格式
发送一个响应。
HTTP/1.1 200 OK
如果取消请求出现错误,设备必须返回以下一种错误进行响应。该响应必须
在30 秒(包括预计的传输时间)内发出。
错误
不兼容标头
400 Bad Request。如果SID 标头和一个NT 或CALLBACK 标头一
起出现,则发布者必须返回HTTP 错误400 Bad Request 进行响应。
无效SID
412 Precondition Failed。如果SID 没有响应一个未过期的已知订阅,
则发布者必须返回HTTP 错误412 Precondition Failed.进行响应。
缺少SID
412 Precondition Failed。如果SID 标头缺少或为空,发布者必须返
回HTTP 错误412 Precondition Failed.进行响应。
其它错误可能会被UPnP 下的协议栈层返回。参考这些协议的相关文档了
解详细信息。
4.2 事件:事件消息
服务通过发送事件消息来发布其状态变量的变更。这些消息包含一个或多个
状态变量名称和这些变量的当前值。事件消息应尽可能快地发送,以使订阅者获
得有关服务的准确信息,并支持订阅者显示响应用户界面。如果有一个以上变量
的值同时发生改变,发布者应将这些变化捆绑在一个事件消息中,以减少处理和
网络流量。
如上所述,在订阅者第一次订阅时,需要发送一个初始化事件消息。该事件
消息包含所有事件触发变量的名称和值,并且允许订阅者初始化其服务状态模
型。该消息应在发布者接受订阅后尽可能快地发送。
事件消息均标有事件编号。为便于进行错误检查,发布者必须保持每个订阅
有一个单独的事件编号(解释如下)。当发布者发送初始化事件消息时,订阅事
件编号被初始化为0。对于以后的每条事件消息,发布者会增加订阅事件编号,
包括事件消息更新的编号。任何事件编号的实施均需处理溢出,并将事件编号回
置到1(而不是0)。订阅者还要在下一个事件编号不是前一个编号的增量的情
况下,处理这一特例情况。应作为4 字节(32 位)整数来实施。
如果订阅者未响应事件消息,发布者应继续向订阅者发送事件消息,直到订
阅期满为止。
为修复事件订阅,例如,如果订阅者已丢失一条或多条事件消息,订阅者必
须取消订阅并重新进行订阅。这样,订阅者将获得一个新的订阅标识符、一个新
的初始化事件消息和一个新的事件编号。
4.2.1 事件:事件消息:NOTIFY
要发送事件消息,发布者必须以下列格式发送一个采用NOTIFY 方法的请
求。以下斜体表示的值为实际值的占位符。
NOTIFY delivery path HTTP/1.1
HOST: delivery host:delivery port
CONTENT-TYPE: text/xml
CONTENT-LENGTH: Bytes in body
NT: upnp:event
NTS: upnp:propchange
SID: uuid:subscription-UUID
SEQ: event key
<e:propertyset xmlns:e="urn:schemas-upnp-org:event-1-0">
<e:property>
<variableName>new value</variableName>
</e:property>
Other variable names and values (if any) go here.
</e:propertyset>
以下列出了上述列表中出现的命令行、标头和消息体元素的详细信息。除特
别注明外,所有标头值均要区分大小写。所有消息体元素和属性均区分大小写;
除特别注明外,消息体值不区分大小写。除特别注明外,元素的顺序无关紧要。
除特别注明外,所要求的元素必须出现一次(无重复),推荐或可选元素最多只
能出现一次。
命令行
NOTIFY
方法由GENA 定义。通知客户关于事件的情况。
交付路径
交付URL(订阅消息中的CALLBACK 标头)的路径组成。事件消
息的目的地。单一、相对URL。
HTTP/1.1
HTTP 版本。
标头
HOST
要求。交付URL(订阅消息中的CALLBACK 标头)的域名或IP 地
址和可选端口组件。如果该缺少或为空,则假定为端口80。
ACCEPT-LANGUAGE
(事件消息中未使用ACCEPT-LANGUAGE 标头。)
CONTENT-LENGTH
要求。消息体长度以字节来表示,为整数。
CONTENT-TYPE
要求。必须为text/xml。
NT
GENA 规定使用的标头。通知类型。必须采用upnp:event 形式。
NTS
GENA 规定使用的标头。通知子类型。必须采用upnp:propchange
形式。
SID
GENA 规定使用的标头。订阅标识符。必须是唯一的。必须以uuid
开头:由UPnP 厂商规定。单一URI。
SEQ
UPnP 规定使用的标头。事件编号。初始化事件消息必须为0。发送
给特定订阅者的每条事件消息必须以1 为增量。长度应为8 字节。为
防止溢出,必须回置到1。一个整数。
消息体
propertyset
要求。Xmlns 名字空间属性必须为urn :
schemas-upnp-org:event-1-0。所有子元素必须符合这一名字空
间。包含以下子元素:
特性
要求。事件消息中的变量名称和值重复一次。值必须符合
propertyset 名字空间。包含以下子元素:
variableName
要求。元素是更改的状态变量名称( 服务描述中
stateVariable 元素的名字子元素)。值必须符合propertyset
名字空间。值是指这一状态变量的新值。单一数据类型由
UPnP 服务描述确定。
为了获得未来可伸缩性,在处理上述XML 时要遵守灵活XML 处理框架
(FXPP),设备和控制点必须忽略:(a) 任何未知元素及其子元素或内容,以
及(b)任何未知属性及其值。
要确认收到了这一事件消息,订阅者必须要在30 秒(包括预计的传输时间)
内做出响应。如果订阅者未在30 秒内做出响应,发布者应停止向订阅者发送此
消息,但应保持订阅并向订阅者发送未来事件消息,直到订阅期满或取消为止。
订阅者必须采用以下格式发送响应:
HTTP/1.1 200 OK
(采用NOTIFY 方法的请求无消息体,但请注意,消息与最后一个HTTP
标头之间必须空一行。)
如果事件消息存在错误,则订阅者必须返回下面一种错误进行响应。该响应
必须在30 秒(包括预计的传输时间)内发出。
错误
SID 缺少
412 Precondition Failed。如果SID 标头缺少或为空,订阅者必须返
回HTTP 错误412 Precondition Failed.进行响应。
无效SID
412 Precondition Failed。如果SID 不响应一个已知的订阅,订阅者
必须返回HTTP 错误412 Precondition Failed.进行响应。(当服务接
收到这一错误响应时,必须终止这一SID。)
NT 或NTS 标头缺少
400 Bad Request。如果NT 或NTS 标头缺少,订阅者必须返回HTTP
错误400 Bad Request 进行响应。
无效NT 标头
412 Precondition Failed.如果NT 标头不符合upnp:event,订阅者
必须返回HTTP 错误412 Precondition Failed.进行响应。
无效NTS 标头
412 Precondition Failed。如果NTS 标头不符合upnp:propchange,
订阅者必须返回HTTP 错误412 Precondition Failed.进行响应。
其它错误可能会被UPnP 下的协议栈层返回。参考这些协议的相关文档了
解详细信息。
4.3 事件:用于事件的UPnP 模板语言
UPnP 模板语言定义了用于设备和服务的合适模板。从较小程度上讲,它还
可提供事件消息消息体模板。描述部分介绍了与设备和服务相关的UPnP 模板
语言。如该部分所述,UPnP 模板语言以XML 句法编写,源于XML 模式(第1
部分:结构,第2 部分:数据类型)。以下是与事件相关的语言列表。它定义的
元素用于事件消息;它们在此处用绿色表示,在以上列表中同样用绿色表示。下
面是定义这些元素的地方(虽然是最低限度的定义);上面是使用这些元素的地
方。
紧随其后是对XML 模式元素、属性和所用值的简单说明。本部分结尾关于
XML 模式的参考中还介绍了更详细的内容。
用于事件触发的UPnP 模板语言
<?xml version="1.0" ?>
<Schema name="urn:schemas-upnp-org:event-1-0"
xmlns="urn:schemas-microsoft-com:xml-data"
xmlns:dt="urn:schemas-microsoft-com:datatypes">
<ElementType name="propertyset" content="eltOnly">
<element type="property" minOccurs="1" maxOccurs="*" />
</ElementType>
<ElementType name="property" content="eltOnly" />
</Schema>
元素
引用一个元素旨在表明嵌套。MaxOccurs 属性定义了元素必须出现
的最多次数;缺省为maxOccurs = 1;可显示一次或多次的元素具有
maxOccurs = *。
ElementType
用全新的衍生语言定义一个元素。名称属性定义元素名称。模式属性
表明全新衍生语言中的元素是否包含此处没有明确规定的元素;当可
能只包含未规定的子元素时,model = open.内容属性表明可能包含
的内容;只包含其它元素的元素带有content = eltOnly。
正如描述部分所述, 服务的UPnP 模板语言还规定了状态变量的
sendEvents 属性。这一属性的缺省值为yes。要表示一个状态变量可以被事件
触发,则在服务描述中该属性的值为yes(或者该属性被省略);要表示状态变
量不能被事件触发,则属性值为no。注意,如果服务的所有状态变量均不能被
事件触发,则该服务就没有内容可以发布,且控制点不能订阅、也不会收到来自
该服务的事件消息。
4.4 事件:增加UPnP 模板语言
可以使用UPnP 模板中没有涵盖的注释来增加设备和服务的描述。从较小
程度上讲,这些注释中的值可以用来捕获事件过滤或事件适度。
如上所述,某些状态变量值的改变太快,以致事件触发功能没有意义。以下
是面向UPnP 论坛工作委员会或UPnP 厂商的推荐词汇表,用于记录由于变量
值改变而发出的事件消息数量适度。
maximumRate = n
可选。超过n 秒频度的状态变量v 不会成为事件消息的一部分。如果
v 是唯一变化的变量,那么事件消息的生成频度通常不会超过n 秒。
如果v 在事件消息发出后的n 秒内停止变化,则事件消息必须以新的
v 值发送。建议采用可模拟不断变化的属性的变量。一个整数。
minimumDelta = n
可选。状态变量v 不会成为事件消息的一部分,除非它的值自上次包
含v 的事件消息发送后改变超过n * allowedValueRange 步,例如,
除非v 已增加了n 倍。(控制部分介绍的内容参见:INCREMENT、
INCREMENT_BOUNDED 和INCREMENT_WRAP。)仅定义了带
编号的变量和实际数据类型。建议采用模拟计数器的变量。一个整数。
发布者可以在事件发出时发送任何更改的调节变量。发布者应努力尝试满足
上述适度规则,但可以在发出事件后刷新最近的变化。
注意适度仅对事件有影响,而不会影响到状态表的更新。具体而言,
QueryStateVariable 可以通过事件触发返回一个比已发布的值更新的值。换言
之,适度意味着不是所有状态表变化都会导致事件发生。
关于哪些变量用于事件触发及任何可能的调整,由适当的UPnP 论坛工作
委员会(面向标准服务)或UPnP 厂商(面向非标准服务)来决定。
4.5 事件参考
FXPP
灵活的XML 处理框架。规定必须忽略未知的XML 元素及其子元素。
IETF 草案。
GENA
通用事件通知架构。IETF 草案。
XML 模式(第1 部分:结构,第2 部分:数据类型)。
语法定义UPnP 模板语言。使用XML 定义。W3C 工作草案。第1
部分:结构。第2 部分:数据类型。
5. 展示
展示是UPnP 网络的第5 步。首先“寻址”(第0 步)设备获得一个网络
地址,之后“发现”(第1 步)控制点发现新设备,然后“描述”(第2 步)
控制点了解该设备能力。展示展示了一个基于HTML 的用户界面,用以控制和/
或浏览设备状态。展示是“控制”(第3 步:控制点向设备发出动作)和“事件
触发”(第4 步:控制点监听设备的状态变化)的补充。
在控制点(1)发现设备和(2)取得设备描述之后,控制点即准备开始提供展示。
如果设备拥有进行展示的URL,那么控制点就可以通过此URL 取得一个页面,
在浏览器中加载该页面,并根据页面功能,支持用户控制设备和/或浏览设备状
态。每一项完成的程度取决于展示页面和设备的具体功能。
展示URL 包含在设备描述的presentationURL 元素中。设备描述通过描述
消息提供。描述部分就设备描述和描述信息做了详细阐述。
取得展示页面是一个基于HTTP 的简单过程,使用整体UPnP 协议栈的以
下子集。(总体UPnP 协议栈在本文开始列出。)
UPnP 厂商[ 紫色]
UPnP 设备架构[绿色]
HTTP[黑色]
TCP[黑色]
IP[黑色]
在最高层,展示页面由UPnP 厂商规定。沿着协议栈向下,UPnP 设备架构
规定该页面以HTML 编写。该页面通过TCP/IP 层上的HTTP 层提供。为便于参
考,包括[方括号]中的颜色,以与本文其它部分保持一致。
为获得展示页面,控制点发出一个HTTP GET 请求到展示URL,设备返回
一个展示页面。
与UPnP 设备和服务模板、以及标准设备和服务类型不同,展示页面的功
能完全由UPnP 厂商规定。展示页面并非由UPnP 论坛工作委员会提供支持。
页面必须是HTML 页面;应为HTML 3.0 或更高版。其它设计方面均由厂商规
定。这包括但不限于控制点浏览器的所有功能、所使用的脚本语言或浏览器插件、
以及与设备进行交互的方式。为实现展示页面,UPnP 厂商可能希望使用UPnP
机制来控制和/或触发事件,以充分利用设备现有的功能,但并不强制规定必须
这样做。
展示页面应使用HTML 中提供的机制进行本地化(如带有charset 属性的
META 标记)。控制点应使用HTTP 的ACCEPT- / CONTENT-LANGUAGE 特
性,尽可能地取得本地化的展示页面。具体来讲,控制点可能在展示页面请求中
包含一个HTTP ACCEPT-LANGUAGE 标头; 如果请求中出现了一个
ACCEPT-LANGUAGE 标头,响应必须要包含一个CONTENT-LANGUAGE 标
头,以确定该页面的语言。
5.1 展示参考
HTML
超文本标记语言。W3C 推荐。<<http://www.w3.org/MarkUp/>
术语表
动作
服务发出的命令。包含一个或多个输入或输出变量。可能具有一个返
回值。如欲了解更多信息,请参阅描述和控制部分。
变量
服务所发出的动作参数。可以采用in xor out 格式。如欲了解更多信
息,请参阅描述和控制部分。
控制点
取得设备和服务描述、向服务发送动作、进行服务状态变量轮询和接
收来自服务的事件。
设备
逻辑设备。一个容器。可以嵌入其它逻辑设备。嵌入一个或多个服务。
如欲了解更多信息,请参阅描述部分。
设备描述
逻辑设备的正式定义,采用UPnP 模板语言表达。以XML 句法编写。
由UPnP 厂商通过填写UPnP 设备模板中的占位符来指定,包括:
制造商名称、型号名称、型号、序列号、以及控制、事件触发和展示
的URL。如欲了解更多信息,请参阅描述部分。
设备类型
标准设备类型由urn:schemas-upnp-org:device:来指定,后面带有
UPnP 论坛工作委员会指定的唯一名称来表示。与UPnP 设备模板为
一对一的关系。UPnP 厂商可以指定其它设备类型; 这些由
urn:domain-name:device:指定。后面带有厂商指定的唯一名称来表
示,其中域名为厂商注册域名。如欲了解更多信息,请参阅描述部分。
事件
服务发出的状态变量的一个或多个变化的通知。如欲了解更多信息,
请参阅事件部分。
发布者
事件消息来源。通常为设备服务。如欲了解更多信息,请参阅事件部
分。
根设备
不嵌入任何其它逻辑设备的设备。如欲了解更多信息,请参阅描述部
分。
服务
逻辑功能单位。控制的最小单位。暴露状态并使用状态变量来模拟物
理设备的状态。如欲了解更多信息,请参阅控制部分。
服务描述
逻辑服务的正式定义,采用UPnP 模板语言表达。以XML 句法编写。
由UPnP 厂商填写UPnP 服务模板(原为SCPD)中的所有占位符
来指定。如欲了解更多信息,请参阅描述部分。
服务类型
标准服务类型由urn:schemas-upnp-org:service:指定。后面带有
UPnP 论坛工作委员会指定的唯一名称和一个整数版本号码来表示。
与UPnP服务模板为一对一的关系。UPnP厂商可以指定其它的服务;
由urn:domain-name:service:指定。后面带有的厂商指定的唯一名
称、冒号和一个版本号来表示,其中域名为厂商注册域名。如欲了解
更多信息,请参阅描述部分。
SOAP
简单对象访问协议。一种基于XML 的远程调用机制,通过HTTP 发
送命令和接收值。如欲了解更多信息,请参阅控制部分。
SSDP
简单服务发现协议。一种使用基于UDP 的HTTP 协议多播变量的多
播发现和搜索机制。如欲了解更多信息,请参阅发现部分。
状态变量
一个物理服务的模型的一个方面。由服务发出。具有名称、数据类型、
可选缺省值、可选限制值、并可在该值改变时触发事件。如欲了解更
多信息,请参阅描述和控制部分。
订阅者
事件消息接收方。通常为控制点。如欲了解更多信息,请参阅事件部
分。
UPnP 设备模板
模板列出设备类型、所要求的嵌入式设备(如有)和所要求的服务。
以XML 句法编写,源自UPnP 模板语言。由UPnP 论坛工作委员会
定义。与标准设备类型为一对一的关系。如欲了解更多信息,请参阅
描述部分。
UPnP 服务模板
模板列出动作名称、这些动作的参数、状态变量和这些状态变量的属
性。以XML 句法编写,源自UPnP 模板语言。由UPnP 论坛工作委
员会定义。与标准服务类型为一对一的关系。如欲了解更多信息,请
参阅描述部分。
UPnP 模板语言
定义了UPnP 设备和服务模板中使用的元素和属性。以XML 句法编
写,源自XML 模式(第1 部分:结构,第2 部分:数据类型)。由
此处的UPnP 设备架构定义。如欲了解更多信息,请参阅描述部分。
文件结束
文章翻译免责声明
本UPnP文档最初用英文发布,并仅有英文版本通过了UPnP论坛的正式审核。
文章已采用翻译服务和翻译技术在英文版本的基础上翻译成目标语言版本,
UPnP Implementers Corporation及其相关机构不对翻译版本做出任何保证,也
不为由翻译不准确所导致的直接或间接损失承担责任。在使用翻译版本中所包括
的技术信息时,用户同意UPnP Implementers Corporation和UPnP论坛成员对于
英文到目标语言翻译的不完整、或不准确导致的全部或部分损失不承担任何责
任。此外,用户同意应保护UPnP Implementation Corporation免受由语言翻译
而带来的伤害。

问:什么是 UpnP?
答:
通用即插即用 (UPnP) 是一种用于 PC 机和智能设备(或仪器)的常见对等网络连接的体系结构,尤其是在家庭中。UPnP 以 Internet 标准和技术(例如 TCP/IP、HTTP 和 XML)为基础,使这样的设备彼此可自动连接和协同工作,从而使网络(尤其是家庭网络)对更多的人成为可能。

问:UPnP 对消费者意味着什么?
答:
简单、更多选择和更新颖的体验。包含通用即插即用技术的网络产品只需实际连到网络上,即可开始正常工作。实际上,UPnP 可以和任何网络媒体技术(有线或无线)协同使用。举例来说,这包括:Category 5 以太网电缆、Wi-Fi 或 802.11B 无线网络、IEEE 1394 ("Firewire")、电话线网络或电源线网络。当这些设备与 PC 互连时,用户即可充分利用各种具有创新性的服务和应用程序。

问:什么是 UPnP 论坛?
答:
“通用即插即用论坛”是一个开放式业界协会,成立于 1999 年 6 月,旨在帮助定义 UPnP 标准以简化家庭(长远上讲则是企业)智能设备的联网。为实现上述目标,该论坛正在制定和公布 UPnP 设备控制协议及服务控制协议。截止到 2001 年 6 月初,已有 350 多家公司成为 UPnP 论坛的成员。UPnP 论坛受由 22 名成员组成的 UPnP Steering Committee(UPnP 指导委员会)的管理。此外还设立了技术委员会、市场推广委员会及各种工作委员会(分别面向某种特定的设备),旨在努力实现该机构的目标。有关论坛成员的列表及加入论坛的信息,请见论坛 Web 站点

问:UPnP 的技术要素是什么?
答:
UPnP 范围广泛,原因是它面向的是家庭网络、临近网络及小型企业和商住楼中的网络。在网络控制设备的管理下,它支持任何两个设备之间的数据通讯。UPnP 不依赖于特定的操作系统、编程语言或物理媒体。
UPnP 支持零配置网络及自动查找功能,这样以来,设备即可动态加入网络,获取 IP 地址,宣布自己的名称,根据需要提供功能,并了解其它设备的存在和功能。DHCP 和 DNS 服务器为可选项。只要在网络上可用,即可加以使用。此外,设备还可自动平稳地脱离网络,而不会遗留任何不必要的状态。
UPnP 汲取了 Internet 的成功之处并继承了它的组件,包括 IP、TCP、UDP、HTTP 及 XML。UPnP 中涉及了多供应商之间的协作,旨在建立标准的设备控制协议 (DCP)。与 Internet 类似,这些协议以公告式线协议为基础,表示为 XML 形式,且通过 HTTP 进行通讯。
问:什么是 NAT?为什么使用它?
答:
“网络地址转换”是一种 Internet Engineering Task Force (IETF) 标准,用于允许专用网络(使用专用地址范围,例如 10.0.x.x、192.168.x.x、172.x.x.x)上的多台 PC 机或设备共享单个、可全局路由的 IPv4 地址。经常使用 NAT 的一个主要原因就是 IPv4(最新一代 Internet)地址的资源日渐紧缺。
在构成公用 Internet 与专用局域网之间屏障的网关设备中,可以使用 NAT。当专用局域网的 IP 数据包经过网关时,NAT 将把专用 IP 地址和端口号转换为公用 IP 地址和端口号,从而跟踪这些转换以保持各个会话不变。Microsoft® Windows® XP 和 Windows Me 操作系统中的“Internet 连接共享”及许多 Internet 网关设备都使用 NAT,尤其是在通过 DSL 或电缆调制解调器连接宽带网的情况下。随着越来越多的家庭和小型企业将自己的 PC 机连接起来并共享 Internet 连接,NAT 的使用量正急剧增加。
问:NAT 的问题在哪?
答:
简言之:NAT 会“瓦解”许多家庭或小型企业中日渐需要的最新型 PC 和家庭网络技术,例如多玩家游戏、实时通讯及其它对等服务。如果在公用 Internet 上使用专用地址或同时使用同一端口号,这些应用程序就会中止。应用程序必须使用公共地址,且每个会话都须使用唯一的端口号。大型机构有专门的 IT 人员来确保其公司应用程序在 NAT 上正常使用,但较小的机构和消费者却不具备这样奢侈的条件。UPnP NAT Traversal 可以自动解决 NAT 给应用程序带来的许多问题,使之成为小型企业和消费者理想的解决方案。
问:谁提出的 NAT Traversal 解决方案?
答:
NAT Traversal 解决方案是 UPnP IGD Working Committee 为制定 Internet 网关设备 (IGD) 规范所从事工作的一部分。UPnP 的成员公司可以加入该委员会,也可以只选择跟踪其工作进展。委员会的主席是 Intel 公司的 Prakash Iyer (prakash.iyer@intel.com)。许多公司,包括 Microsoft,都在为此而努力。
问:是否有其它途径来解决 NAT Traversal 的问题?如果有,为什么将 UPnP 视为最佳选择?
答:
是的,确实有其它途径来解决此问题,但目前还没有其它机制来作为解决该问题的业界标准,从而能对消费者自动实现,而对开发人员则普遍可行。其它方案或者要求用户进行人工干预,或者要求 Internet 网关设备制造商进行专门的开发,并要求软件开发人员处理 NAT Traversal 对特殊应用程序的需要。因此,只有 UPnP 能解决该重大问题。
用户的工作: NAT Traversal 的手工干预法要求用户使用浏览器(PC 机上一种基于图形用户界面的工具)或 PC 上的命令行界面工具来更改家中 Internet 网关设备上的某些设置。尽管有些热衷技术的用户不会有很大困难,但许多用户却感到困难重重。此外,许多用户甚至不知道 NAT Traversal 问题正对其 Internet 服务的使用造成干扰。用户可能想体验一种多玩家游戏或使用其它某些对等服务,却发现由于某种原因而无法连接。这会导致用户采取疑难解答步骤、寻求电话支持、感到不满,甚至以后不打算使用新的服务或不打算尝试新的技术感受。
开发人员的工作: 为避免要求用户手动解决此 NAT Traversal 问题,有些 Internet 网关设备制造商已编写出应用层网关支持,并将其包含到设备中。该应用层网关软件的设计思路是特殊的应用程序。换言之,设备制造商将编写和测试特殊的代码,自动使一个应用程序完成 NAT。如果该应用程序软件进行了更新,则设备制造商所编写的应用层代码将必须重新进行更新和测试。当只需要考虑几个对等或相关的应用程序时,这种一对一解决 NAT Traversal 问题的方式对于设备制造商而言是可管理的,但它无法对数百或数千个应用程序伸展自如,这时不仅开发成本高,并可能需要有关这些应用程序各自原理方面的知识。解决该问题较好的方法就是让设备制造商为设备添加能理解 UPnP 的软件或固件,然后让其它设备和软件能利用同一技术与 NAT 设备进行通讯。现在只有 UPnP 能够完成这种职责。
问:UPnP NAT Traversal 解决方案的作用是什么?
答:
支持 UPnP 的 NAT Traversal 可确保下列情况的实现:
  • 多玩家游戏
  • 对等连接
  • 实时通讯
  • 远程协助(Windows XP 的功能之一)
对于 IHV 而言,该解决方案免去了编写和维护应用层网关 (ALG) 数据库以通过 NAT 的必要。它受 Windows XP 和 Direct Play(一种 Windows 编程资源)的支持,因此为 DPlay 编写的软件应用程序将能自动对 NAT Traversal 使用 UPnP 解决方案。
通过提供下列操作的方法,UPnP 论坛的 IGD 规范可进行自动 NAT Traversal:
  • 了解公用 IP 地址
  • 列举现有的端口映射
  • 添加和删除端口映射
  • 指定映射的租用期
问:哪些制造商在实施 UPnP NAT Traversal 解决方案?
答:
目前,大多数大型网关(DSL/电缆路由器)制造商都宣布计划从 2001 年(不迟于 7 月份)在提供的产品中实施 UPnP NAT Traversal 解决方案。其中包括:MicrosoftWindowsXP 中)、Linksys、D-Link、Intel、Netgear and Buffalo TechnologyArescom
其中的一些制造商已宣布将为已拥有其设备的用户提供固件或软件升级,从而为支持 UPnP 的 NAT Traversal 提供支持。
问:用户怎样才能知道哪些 Internet 网关设备支持 UPnP?
答:
用户可以查阅 Internet 网关设备制造商的 Web 站点,或者阅读产品包装上的标签,以确定是否提供该功能。后面几个月内,有些零售商将会知道这个情况。在未来的几个月中,UPnP 论坛会提供一个 UPnP 徽标。制造商可以在自己的产品包装、营销资料或产品上包含该徽标,以表明该产品满足 UPnP 论坛的测试要求。
问:开发人员实施该方案时有哪些可用的资源?
答:
资源有很多,范围从白皮书到互操作性测试事件 (PlugFests)。有关技术性的文章,请访问 http://www.upnp.org/resources.htm。有关未来的重大事件,请参阅 http://www.upnp.org/events.htm。Microsoft 在 MSDN Online 上提供有关 Windows XP 的开发人员信息。

问:哪里还有更多的信息?
答: