Mojies

DLNA 粗解

简介
Upnp Device Architechture 1.0
1. 前言
2. 简介
  1. What is UPnP™1 Technology?
  2. UPnP™ Forum
  3. In this document
  4. Audience
  5. Required vs. recommended
  6. Acronyms
  7. References and resources
3. 0. Addressing
  1. 0.1 Addressing: Determining whether to use Auto-IP
  2. 0.2 Addressing: Choosing an address
  3. 0.3 Addressing: Testing the address
  4. 0.4 Addressing: Periodic checking for dynamic address availability
  5. 0.5 Addressing: Device naming and DNS interaction
  6. 0.6 Addressing: Name to IP address resolution
  7. 0.7 Addressing references
4. 1. Discovery
  1. 1.1 Discovery: Advertisement
  2. 1.2 Discovery: Search
  3. 1.3 Discovery references
5. 2. Description
  1. 2.1 Description: Device description
  2. 2.2 Description: UPnP Device Template
  3. 2.3 Description: Service description
  4. 2.4 Description: UPnP Service Template
  5. 2.5 Description: Non-standard vendor extensions
  6. 2.6 Description: UPnP Template Language for devices
  7. 2.7 Description: UPnP Template Language for services
  8. 2.8 Description: Retrieving a description
  9. 2.9 Description references>
6. 3. Control
  1. 3.1 Control: Protocols
  2. 3.2 Control: Action
  3. 3.3 Control: Query for variable
  4. 3.4 Control references
7. 4. Eventing
  1. 4.1 Eventing: Subscription
  2. 4.1.1 Eventing: Subscribing: SUBSCRIBE with NT and CALLBACK
  3. 4.2 Eventing: Event messages
  4. 4.3 Eventing: UPnP Template Language for eventing
  5. 4.4 Eventing: Augmenting the UPnP Template Language
  6. 4.5 Eventing references
8. 5. Presentation
  1. 5.1 Presentation references

简介

首先我会将 Upnp Device Architechture 1.0 翻译一遍，然后再结合实践来更新此偏文章。

注意：你可能在文章中会多次发现有如下字眼 "发现消息"， "广播消息" 很多时候他们是名词，而不是一个动作，请结合上下文理解。

Upnp Device Architechture 1.0

前言

本文档合并了几个单独的文档，这些文档构成了UPnP设备体系结构1.0版的整体，包括以前针对AutoIP，SSDP，HTTPU / MU，FXPP和GENA的单独规范，以及《 UPnP Vendor Implementation Guide》中的说明。它不引入任何新的技术要求，而仅构成编辑上的说明。

简介

What is UPnP™1 Technology?

UPnP™技术定义了一种架构，该架构用于构建各种形式的智能设备，无线设备和 PC 设备普遍对v等网络连接。它旨在为家庭，小型企业，公共场所或连接到 Internet 的临时或非托管网络带来易于使用，灵活，基于标准的连接。 UPnP技术提供了一种分布式，开放的网络体系结构，该体系结构利用 TCP/IP 和 Web 技术来实现无缝的邻近网络，以及在联网设备之间进行控制和数据传输。

UPnP Device Architecture（UDA）不仅仅是即插即用外围设备模型的简单扩展。它的设计旨在使能众多厂商支持零配置，“无感” 联网以及服务的自动发现。这意味着设备可以动态加入网络，获取IP地址，申明其功能以及了发现了解其他设备的存在和功能。最终，设备也可以自动顺畅地离开网络，而不会留下任何不必要的状态。

UPnP 体系结构利用了普遍的 Internet 协议技术，例如 IP，TCP，UDP，HTTP 和 XML。像 Internet 合约基于声明性的有线协议一样，UPNP 以 XML 表示并通过 HTTP 协议进行通信。使用互联网协议是 UDA 的一个不错的选择，因为它具有跨不同物理媒体的可靠能力，可以实现现实世界中的多供应商互操作，并且可以与 Internet 以及许多家庭和办公室内部网实现协同作用。 UPnP体系结构已明确设计为适应这些环境。此外，作为一个桥接万物的协议， UDA 还解决了设备因为成本，技术或传统限制设备无法获取 IP 时的场景

为什么 UPnP 技术是 “普遍性” 的？没有设备驱动程序，使用通用协议。 UPnP 网络是独立的（媒体）。 UPnP 设备可以使用任何编程语言在任何操作系统上实现。 UDA 在程序/接口设计上没有设置任何限制。操作系统供应商可以为其客户的需求实现合适的 API。

UPnP™ Forum

UPnP 论坛则是一项行业计划，旨在使来自许多不同的供应商的独立设备和 PC 之间实现轻松而强大的连接。 UPnP 论坛寻求开发一套用于描述设备协议的标准。基于 XML 的设备的标准架构用于在可扩展网络环境中，实现设备到设备互相操作。

The UPnP Implementers Corporation（UIC）由UPnP 论坛中的各个行业成员公司组成，采用统一的设备互连技术标准以对这些设备进行测试和认证。 UIC 开发和管理测试和认证过程，管理 UPnP 徽标的分发，并向 UIC 成员和其他有关 UPnP 设备认证的相关方提供相关信息。 UPnP 设备认证对拥有 UPNP 设备和已支付 UIC 会费的 UPnP 论坛和 UIC 的成员开放。有关更多信息，请参见 http://www.upnp-ic.org。

UPnP论坛已经建立了专门领域知识领域的工作委员会。这些工作委员会负责创建建议的设备标准，构建示例实现以及构建适当的测试套件。本文档指出了UPnP论坛工作委员会职权范围内的特定技术决策。

UPnP 供应商可以建立具有互操作性以及共享知识产权和徽标计划的好处的合规设备。除了徽标程序之外，供应商还可以构建遵循本文定义的 UPnP 设备架构的设备，而无需使用正式的标准程序。如果供应商制造非标准设备，则他们将决定由UPnP论坛工作委员会决定的技术决定（没看懂，原文贴后面了）。If vendors build non-standard devices, they determine technical decisions that would otherwise be determined by a UPnP Forum working committee.

In this document

本文包含的 UDA（以前称为DCP框架）定义了控制器或控制点与设备之间进行通信的协议。为了进行发现，描述，控制，事件和演示，UPnP设备体系结构使用以下协议栈（）：

在最上层，消息在逻辑上仅包含有关其设备的 UPnP 供应商特定信息。在第二层， UPnP 论坛工作委员会定义补充供应商的内容的信息。来自以上各层的消息以特定于 UPnP 的协议托管，例如本文档中定义的简单服务发现协议（SSDP）和通用事件通知体系结构（GENA），以及所引用的其他协议。以上消息是通过 HTTP（通过 UDP 的多播或单播来传输）或通过在 TCP 上的 HTTP 传递的。最终，以上所有消息均通过 IP 网络传递。本文档的其余部分详细描述了每个协议层的内容和格式。作为参考，以上[方括号]中的颜色表示在本文档中哪个协议定义了特定的消息组件。

UDA 定义了两种设备的一般分类：受控设备（或简称为“设备”）和控制点。受控设备充当服务器的角色，响应来自控制点的请求。控制点和受控设备都可以在包括个人计算机和嵌入式系统在内的各种平台上实现。被控设备，控制点两者可以在同一网络终端上同时运行。

UPnP 网络的基础是 IP 寻址（IP addressing）。每个设备必须具有动态主机配置协议（DHCP）客户端，并在设备首次连接到网络时搜索 DHCP 服务器。如果 DHCP 服务器可用，则该设备必须使用分配给它的IP地址。如果没有可用的DHCP服务器，即网络不受管理，则设备必须使用自动 IP ( AutoIP )来获取地址。简而言之，“自动IP” 定义了设备如何从一组保留的地址中智能地选择 IP 地址，以及如何在托管网络和非托管网络之间轻松移动。如果在进行 DHCP 事务处理期间，设备（例如，通过DNS服务器或DNS转发）获得了域名，则设备应在后续的网络操作中使用该名称；否则，设备应使用其IP地址。

给定一个IP地址，UPnP 网络中的步骤 1 是发现（ discovery ）。将设备添加到网络后，UPnP 发现协议允许该设备将其服务通告给网络上的控制点。同样，当将控制点添加到网络时，UPnP 发现协议允许该控制点搜索网络上感兴趣的设备。两种情况下的基本交换是发现消息，该发现消息包含关于设备或其服务之一的一些基本细节，例如，设备的类型，标识符以及指向更详细信息的指针（URL）。下面有关发现的部分说明了设备如何播发，控制点搜索方式以及发现消息格式的详细信息。

UPnP 组网中的第 2 步为描述( description )。控制点发现设备后，控制点对设备的了解仍然很少。为了使控制点了解有关设备及其功能的更多信息，或与设备进行交互，控制点必须从设备在发现消息中提供的 URL 检索设备的描述。设备可能包含其他逻辑设备以及功能单元或服务, 并且包括特定于供应商的制造商信息。例如型号名称和编号，序列号，制造商名称，特定于供应商的网站的 URL 等（设备的 UPnP 描述以 XML 表示）。该描述还包括任何嵌入式列表。设备或服务，以及用于控制，事件和演示的 URL。对于每个服务，描述都包括服务响应的命令或动作的列表，以及每个动作的参数或自变量。服务描述还包括（状态）变量列表；这些变量在运行时对服务状态进行建模，并根据其数据类型，范围和事件特征进行描述。下文“描述”部分说明了如何描述设备以及控制点如何检索这些描述。

UPnP网络中的第三步 3 是控制。在控制点检索到设备的描述之后，控制点可以将操作发送到设备的服务。为此，控制点将适当的控制消息发送到服务的控制 URL（在设备描述中提供）。控制消息还使用简单对象访问协议（SOAP）用 XML 表示。像函数调用一样，响应于控制消息，服务将返回任何特定于操作的值。动作的效果（如果有的话）是通过描述服务运行时状态的变量的变化来建模的。下面有控制的部分的操作说明，状态变量和控制消息格式的描述。

UPnP 网络中的步骤 4 正在事件（eventing）。服务的 UPnP 描述包括服务响应的操作列表和在运行时对服务状态建模的变量列表。这些变量更改时，服务将发布更新，并且控制点可以订阅以接收此信息。该服务通过发送事件消息( eventing msg )来发布更新。事件消息包含多个状态变量的名称以及这些变量的当前值。这些消息也以XML表示。当控制点首次订阅时，会发送一个特殊的初始事件消息。该事件消息包含所有事件变量的名称和值，并允许订户初始化其服务状态模型。为了支持具有多个控制点的方案，事件设计为使所有控制点均等地了解任何操作的效果。因此，并且无论状态变量为何更改，被控点因向所有订户发送所有事件消息。订阅者会受到所有已经变更的消息。下面有事件的部分说明了订阅和事件消息的格式。

UPnP 网络中的第 5 步是展示（presentation）。如果设备具有用于展示的 URL，则控制点可以从该 URL 检索页面，将该页面加载到浏览器中，并根据页面的功能，允许用户控制设备和/或查看设备状态。完成这些操作的程度取决于演示页面和设备的特定功能。下面有 “演示” 的部分说明了检索演示页面的协议。

Audience

本文档的读者包括 UPnP 设备供应商（vendor），UPnP 论坛工作委员会的成员以及需要了解 UPnP 协议技术细节的其他任何人。

本文档假设读者熟悉 HTTP，TCP，UDP，IP 协议家族；本文档未尝试解释它们。本文档还假定大多数读者将不熟悉 XML，尽管它不是 XML 教程，但鉴于 XML 在 UPnP 设备体系结构中的中心地位，将详细解决与 XML 有关的问题。本文档不假定读者对各种编程或脚本语言的理解。

Required vs. recommended

在本文档中，特性被描述成 Required（要求）, Recommended（推荐）, or Optional（可选）三个等级。

Required (or Must or Shall)
必须实现这些基本功能，以符合 UPnP 设备架构（UDA）。短语“不应该（shall not）”和“不得( must not )”表示禁止的行为，如果执行，则表示该实现不符合要求。
Recommended (or Should).
这些功能增加了 UPnP 设备体系结构支持的功能，应予以实现。推荐的功能通常利用 UPnP 设备架构的功能，而不会造成较大的成本增加。请注意，对于合规性测试，如果实施了推荐功能，则它必须满足指定要求才能符合这些准则。某些推荐功能可能会在将来成为要求。短语“不应”表示允许但不建议的行为
Optional (or May).
UPnP 设备体系结构既不需要也不推荐这些功能，但是如果实现了该功能，则必须满足指定的要求才能符合这些准则。这些功能将来不太可能成为必需。

Acronyms

	缩写	解释
ARP	Address Resolution Protocol
CP	Control Point
DCP	Device Control Protocol
DHCP	Dynamic Host Configuration Protocol
DNS	Domain Name System
GENA	General Event Notification Architecture
HTML	HyperText Markup Language
HTTP	Hypertext Transfer Protocol
HTTPMU	HTTP (Multicast over UDP)
HTTPU	HTTP (Unicast over UDP)
SOAP	Simple Object Access Protocol
SSDP	Simple Service Discovery Protocol
UDA	UPnP™ Device Architecture
UPC	Universal Product Code
URI	Uniform Resource Identifier
URL	Uniform Resource Locator
URN	Uniform Resource N me
UUID	Universally Unique Identifier
XML	Extensible Markup Language

References and resources

RFC 2616
HTTP: Hypertext Transfer Protocol 1.1. http://www.ietf.org/rfc/rfc2616.txt
RFC 2279
UTF-8, a transformation format of ISO 10646 (character encoding). http://www.ietf.org/rfc/rfc2279.txt
XML
Extensible Markup Language. W3C recommendation. http://www.w3.org/TR/2000/REC-xml-20001006.

本文档的每个部分都包含有关特定主题资源的其他信息。

0. Addressing

寻址是 UPnP™ 网络的第 0 步。通过寻址，设备可以获得网络地址。寻址成功才能使控制点在步骤 1 （discovery）在找到有感兴趣的设备，步骤 2（description）在控制点了解设备功能，步骤 3（control）在控制点向设备发送命令，步骤4（eventing）控制点监听设备状态变化，步骤5（presentation）控制点显示设备用户界面。

UPnP 网络的基础是 IP 寻址。每个本身不实现 DHCP 服务器的 UPnP 设备都必须具有动态主机配置协议（DHCP）客户端，并在设备首次连接到网络时搜索 DHCP 服务器（如果设备本身实现DHCP服务器，则它可以分配本身就是它所控制的池中的地址）。如果 DHCP 服务器可用，即管理网络，则该设备必须使用分配给它的 IP 地址。如果没有DHCP服务器可用，即网络不受管理；设备必须使用自动 IP 寻址（Auto-IP）来获取地址。

此处定义的自动 IP 是定义设备（a）确定 DHCP 是否不可用，以及（b）从一组本地链路 IP 地址中智能地选择 IP 地址。这种地址分配方法使设备可以轻松地在托管和非托管网络之间移动。

本节定义了自动 IP 的操作。本节中描述的操作在下面列出的参考文档中进行了详细说明。如果本文档和参考文档之间存在冲突，则始终以参考文档为准。

0.1 Addressing: Determining whether to use Auto-IP

支持自动 IP 并的设备被配置为首先通通过 DHCP 发送 DHCPDISCOVER 消息请求 IP 地址开始。此 DHCP 客户端应侦听 DHCPOFFER 的时间量取决于厂商自己的实现。如果在此期间收到 DHCPOFFER，则设备必须进行继续动态地址分配过程。如果没有收到有效的 DHCPOFFER，则设备开始自动配置 IP 地址流程。

0.2 Addressing: Choosing an address

为了使用自动 IP 自动配置 IP 地址，设备需要实现有关的算法来选择 169.254.0.0/16 范围内的地址。此范围中的前 256 个地址和后 256 个地址被保留，不能使用。

经过算法选择的地址必须测试所选的地址在局域网中的唯一性，以确定该地址是否已被使用。如果该地址正被另一个设备使用，则必须选择并测试另一个地址，直到达到厂商自己定义的最大重试次数。当多个设备试图分配地址时，应将地址选择随机化以避免冲突。建议设备使用伪随机算法（分布在从 169.254.1.0 到 169.254.254.255 的整个地址范围内）选择地址，以最大程度地减少同时加入网络的设备选择相同地址的可能性，并在检测到冲突时按相同顺序选择备用地址。可以使用设备的以太网硬件 MAC 地址来作为伪随即算法的种子。

0.3 Addressing: Testing the address

要测试所选的地址，设备必须使用地址解析协议（ARP）探针。 ARP 探针是一个 ARP 请求，其中设备 IP 地址用作发件人的 IP 地址，而发件人的 MAC 地址设置为 0s。 ( hwsrc == 自己 MAC 地址， psrc == 0.0.0.0, pdst == 探测的 IP 地址，也就是自己随机选择出来的 IP 地址 ) 然后，设备将侦听 ARP 探针或针对同一 IP 地址的其他 ARP 探针的响应。如果看有一个使用设备当前选择的 IP 的 ARP 数据包，则设备必须考虑使用其他地址。可以重复进行 ARP 探测，以确保该地址尚未使用。建议每两秒钟发送四次探测。

成功配置链接本地地址后，设备应发送两个自己的 ARP 报文，间隔 2 秒，这次将配置的 IP 填充为了发送方 IP 地址。这些 ARP 的目的是确保网络上的其他主机没有因为以前可能使用相同地址而遗留的陈旧 ARP 缓存。

拥有非易失性存储的设备可以记录其选择的 IP 地址，并在下一次引导时将其用作探测时的第一个候选地址，以提高地址的稳定性并减少解决地址冲突的需要。

当设备正在发送 ARP 探针并侦听答复时，地址冲突检测不应局限于地址测试阶段。地址冲突检测是一个持续不断的过程，只要设备使用链接本地地址，该过程就一直有效。在任何时候，如果设备接收到一个 ARP 数据包，该 ARP 数据包具有自己的 IP 地址作为发送方 IP 地址，但发送方硬件地址与自己的硬件地址不匹配，则该设备应将此视为地址冲突并应做出响应如以下（a）或（b）中所述：

a: 立即配置新的本地链接IP地址，或者
b: 如果设备当前具有活动的 TCP 连接或其他原因希望保留相同的IP地址，并且最近（例如，在过去的十秒钟内）没有看到任何其他冲突的 ARP 数据包，则它可以选择尝试保护其地址一次，方法是记录收到冲突的 ARP 数据包的时间，然后广播一个 gratuitous ARP，并为将自己的 IP 和硬件地址作为 ARP 的源地址。但是，如果在此后的短时间内（例如十秒钟之内）收到另一个冲突的ARP数据包，则设备应立即如上所述配置新的自动IP地址。

设备应按照上述（a）或（b）中的说明响应冲突的 ARP 数据包；它不应忽略冲突的 ARP 数据包。要从一个 IP 地址切换到新的 IP 地址，设备应尽可能取消在前一个地址上发布的所有未完成的广告，并且必须在新地址上发布新的广播。发现部分介绍了广播及其取消。

成功配置自动 IP 地址后，应使用链接级广播而不是链接级单播发送包含自动 IP 源地址的所有后续 ARP 数据包（答复和请求），以便及时发现重复地址。作为替代方案，无法发送广播 ARP 答复的设备应发送单播 ARP 答复，但随后忽略遵循 RFC 826 中有关记录来自已接收ARP请求的发件人信息的指令。这意味着，在未能记录发送方信息的情况下，该设备很可能稍后会发送自己的广播ARP请求，从而使使用相同IP地址的另一设备能够检测到冲突并对其进行响应。

源或目标地址在 169.254.0.0/16 范围内的 IP 数据包不得发送到任何路由器进行转发。具有多播目标地址和自动IP源地址的IP数据报不应从本地链路转发出去。设备和控制点可以假定所有 169.254.0.0/16 目标地址都在链接上并且可以直接访问。 169.254.0.0/16 地址范围一定不能划分子网。

0.4 Addressing: Periodic checking for dynamic address availability

自动配置 IP 地址的设备必须定期检查 DHCP 服务器的存在。这是通过发送 DHCPDISCOVER 消息来完成的。进行此检查的频率取决于实现方式，但是每 5 分钟检查一次将在所需的网络带宽和连接性维护之间保持平衡。如果收到DHCPOFFER，则设备必须继续进行动态地址分配。 DHCP分配的地址到位后，设备可以释放自动配置的地址，但也可以选择在一段时间内（或无限期地）维护该地址以保持连接性。

要从一个 IP 地址切换到新的 IP 地址，设备应尽可能取消在前一个地址上发布的所有未完成的广告，并且必须在该新地址上发布新的广告。发现部分介绍了广告及其取消。

0.5 Addressing: Device naming and DNS interaction

设备具有网络的有效 IP 地址后，就可以通过该地址在该网络上对其进行定位和引用。最终用户可能需要定位和识别设备。在这些情况下，设备的友好名称比 IP 地址更容易被人使用。如果 UPnP 设备选择向 DHCP 服务器提供主机名并向 DNS 服务器注册，则该设备应确保所请求的主机名是唯一的，或者应为用户提供一种更改所请求的主机名的方法。 UPnP设备通常不提供主机名，而是使用文字（数字）IP地址提供URL。

而且，名称比 IP 地址更加静态。当设备的 IP 地址更改时，按名称引用设备的客户端不需要任何修改。设备的 DNS 名称到其 IP 地址的映射可以手动输入，也可以根据 RFC 2136 动态输入到 DNS 数据库中。尽管支持动态 DNS 更新的设备可以直接在 DNS 中注册其 DNS 记录，但也可以配置 DHCP 服务器进行注册 DNS 记录代表这些DHCP客户端。

0.6 Addressing: Name to IP address resolution

如果一台设备需要通过 DNS 联系另外一台设备，那么我们先要从 DNS 的名字中取得设备的 IP 地址。设备根据 RFC1034 和 1035 向预配置的 DNS 服务器提交 DNS 查询，并从 DNS 服务器接收包含目标设备 IP 地址的响应。可以使用 DNS 服务器列表对设备进行静态预配置。或者，可以通过DHCP，或在通过DHCPINFORM消息分配地址之后，为设备配置 DNS 服务器列表。

0.7 Addressing references

RFC1034
Domain Names - Concepts and Facilities. http://www.ietf.org/rfc/rfc1034.txt
RFC1035
Domain Names - Implementation and Specification. http://www.ietf.org/rfc/rfc1035.txt
RFC 2131
Dynamic Host Configuration Protocol. http://www.ietf.org/rfc/rfc2131.txt
RFC 2136
Dynamic Updates in the Domain Name System. http://www.ietf.org/rfc/rfc2136.txt

1. Discovery

发现是 UPnP™ 网络中的第一步。发现是在寻址（第 0 步）之后获得的，其中设备获得了网络地址。通过发现，控制点可以找到有趣的设备。发现可以进行描述（第 2 步），其中控制点了解设备功能，进行控制（第 3 步），控制点向设备发送命令，进行事件（第 4 步），控制点侦听设备的状态变化，和演示（第 5 步），其中控制点显示设备的用户界面。

发现是 UPnP 网络的第一步。将设备添加到网络后，UPnP 发现协议允许该设备将其服务通告给网络上的控制点。同样，当将控制点添加到网络时，UPnP 发现协议允许该控制点搜索网络上感兴趣的设备。两种情况下的基本交换是发现消息，该消息包含有关设备或其服务之一的一些基本细节，例如，设备的类型，设备的唯一的标识符，及指向更详细信息的指针。

将新设备添加到网络后，它会用多播的方式广播一些消息，这些消息会宣传其自身，其嵌入式设备及其服务。任何感兴趣的控制点都可以侦听标准多播地址，以获取有关新功能可用的通知。

同样，将新的控制点添加到网络后，它会用多播的方式广播一条搜索消息，搜索有趣的设备，服务或两者。所有设备必须侦听这些消息的标准多播地址，并且如果它们的任何嵌入式设备或服务符合发现消息中的搜索条件，则必须做出响应。

重申一下，控制点可以获悉感兴趣的设备，因为该设备发送了广告宣传自己的消息，或者因为该设备响应了搜索消息。在任何一种情况下，如果控制点对设备感兴趣并希望了解更多信息，则控制点将使用发现消息中的信息来发送描述查询消息。 “描述”部分详细说明了描述消息。

当设备从网络中删除时，如果可能的话，它应该多播多条发现消息，以撤销其先前的公告，从而有效地声明其嵌入式设备和服务将不再可用。更改设备的IP地址后，它应也应该撤消所有之前的公告，并使用新的IP地址发布广告。

对于具有多个网络接口的设备和控制点，应该在所有启用 UPnP 网络的网络接口上发送 UPnP 通告和搜索。每个广播消息或搜索消息都必须在 LOCATION 标头中指定一个可在该接口上访问的地址

为了避免网络拥塞，每个多播消息的每个 IP 数据包的生存时间（TTL）应该默认为4，并且应该是可配置的。当 TTL 大于 1 时，多播消息可能会遍历多个路由器。因此，使用非 AutoIP 地址的控制点和设备必须发送 IGMP Join 消息，以便路由器将多播消息转发给它们（使用 Auto-IP 地址时，这是不必要的，因为具有 Auto-IP 地址的数据包将不会被路由器转发）。

发现在不同版本的 UPnP 网络的设备和控制点的互操作性中起着重要作用。 UPnP 设备体系结构（在此定义）同时具有主要版本和次要版本，通常写为 major.minor，其中，主要和次要均为整数（例如，版本2.10 比版本2.2更新）。次要版本的提升必须是同一主版本的较早次要版本的兼容超集。主要版本中的进步不一定是早期版本的超集，也不保证其向后兼容。版本信息在发现和描述消息中传达。在前一种情况下，每个发现消息都包括设备支持的 UPnP 网络版本（在 SERVER 标头中）；相关的发现消息中还包含支持的设备和服务类型的版本。作为备份，后者也包含相同的信息。本节将说明发现消息中版本信息的格式以及对发现消息的特定要求，以保持与次要版本的改进的兼容性。

本节的其余部分详细解释 UPnP 发现协议（SSDP），列举设备如何通告和撤消其通告以及控制点搜索和设备如何响应。

1.1 Discovery: Advertisement

将设备添加到网络后，该设备会将其服务通告给控制点。它通过将发现消息多播到标准地址和端口（239.255.255.250:1900）来实现此目的。控制点侦听此端口以检测网络上何时有新功能可用。为了公布其功能的全部范围，设备会多播设备自身的服务相对应的发现消息。每个消息都包含特定于设备（或服务）的信息和有关其封闭设备的信息。消息应应该包含该消息的过期信息；如果设备仍然可用，则应重新发送广告。如果设备不可用，则设备应明确取消其广告，但是如果设备无法执行此操作，则广告将自行失效。

1.1.1 Discovery: Advertisement protocols and standards

为了发送（和接收）广播，设备（和控制点）需要遵从以下提到的 UPNP 的子集。（UPnP 的完整协议栈在文章开头有提及）

在最上层，发现消息包含供应商的信息，例如，用于设备描述和设备标识符的URL。从协议栈向下看，供应商内容将由 UPnP 论坛工作委员会提供的信息（例如设备类型）进行补充。来自以上各层的消息以本文档中定义的 UPnP 的协议承载。同样的，上述消息是通过使用 HTTPMU（ HTTP 多播变体）的头部或者方法进行封装传递。 HTTP 消息是通过 UDP over IP 传递的。作为参考，上方[方括号]中的颜色表示哪种协议定义了下面列出的发现消息中的特定标头和值。

1.1.2 Discovery: Advertisement: Device available -- NOTIFY with ssdp:alive

将设备添加到网络后，它会多播发现消息，以通告其根设备，任何嵌入式设备和所有服务。每个发现消息包含四个主要组件：

在 NT（通知类型）标头中发送的潜在搜索目标（例如设备类型），
在 USN（唯一服务名称）标头中发送该设备综合服务的组合标识符，

在 LOCATION 标头中发送的有关该设备（或在服务中为封闭设备）的更多信息的 URL，

在 CACHE-CONTROL 标头中发送的广播消息的有效期限。

为了公布其功能，设备会广播多次自身服务的多条发现消息。具体来说，根设备必须多播：

更设备（服务）的发现消息。
两条为两个嵌入设备发送的搜索消息。
设备各自的服务。

** 请注意，USN 标头的前缀（在双冒号之前）必须与设备描述中的 UDN 元素的值匹配。 (“描述”部分说明了UDN元素。)

** 请注意，此NT标头的值必须与设备描述中的UDN元素的值匹配。

如果根设备具有 d 个嵌入式设备和 s 个嵌入式服务，但只有 k 种不同的服务类型，那么该设备将可达到 3 + 2d + k 个请求。如果特定设备或嵌入式设备包含特定服务类型的多个实例，则仅需要通告一次该服务类型（而不是每个实例一次）。这会将设备功能的全部范围通告给感兴趣的控制点。这些消息必须按照到期时间粗略的排好先后顺序，然后按照序列顺序发送出去；严格的顺序无关紧要，但是单独的刷新或取消消息是禁止的。（不知道翻译对不对，原文在这里： order is unimportant, but refreshing or canceling individual messages is prohibited）

更新的 UPnP 设备和服务类型需要与该类型的先前版本完全向后兼容。设备必须公布每种受支持类型的最高受支持版本。例如，如果设备支持“音频”服务的版本2，即使它也支持版本 1，它也只会发布版本 2。由此，固定版本的设备或服务的控制点也可以与更高版本进行交互。但由于仅具有向后兼容性要求，因此只能使用较低版本中定义的功能。例如，如果控制点仅支持“音频”服务的版本“ 1”，并且设备宣传其支持“音频”服务的版本“ 2”，则控制点应识别并能够使用该设备。

为广播选择合适的有效时间是在最小化网络流量和最大化设备状态新鲜度之间的平衡。相对较短的有效时间（最短为1800秒）将确保控制点具有当前设备状态，但会增加网络流量；较长的持续时间（例如一天左右）会损害设备状态的新鲜度，但可以大大减少网络流量。通常，设备供应商应该选择一个与预期设备使用率相对应的值：对于短期内预计将成为网络一部分的设备，有效期的时间应该设置比较短；对于预期长期成为网络成员的设备，有效期时间应该设置较长。频繁连接和离开网络的设备（例如移动无线设备）应使用较短的有效期时间，以便控制点可以更准确地了解其可用性。初始的广告集应具有比较合适的有效时间，并且整个组应尽快发送。广播的后续刷新可能会随时间分布，而不是作为一个组发送。

设备应在发送初始广告集之前随机的等待小于 100 毫秒的间隔，以减少网络风暴的可能性；该随机间隔也应在设备获得新 IP 地址或安装新网络接口的情况下应用。

由于 UDP 的不可靠特性，设备应多次发送上述每个发现消息，尽管为避免网络拥塞，发现消息的发送次数不应超过 3 次。另外，设备必须在 CACHE-CONTROL 标头中指定的超市时间到期之前，定期重新发送其广告。建议以小于广播到期时间一半的随机分布间隔进行这种广告刷新，以便为在广告到期之前从为丢失的广播提供恢复的机会，并随着时间的流逝在网络上随机分布多个设备的广告刷新，以避免网络流量激增。但请注意，UDP 数据包的长度也是有界的（在某些实现中可能只有512字节）。每个发现消息必须完全适合单个UDP数据包。而且，不保证上述 3 + 2d + k 个消息将以特定顺序到达。

将设备添加到网络后，它必须使用以下格式广播自己的请求，其中 NTS 头字段的值应该为 ssdp：alive， Method 字段应该为 NOTIFY。其中斜体代表待填充字段。

NOTIFY 方法的请求没有负载（body）部分，但是在头部后了空行一定不能少。（结尾是两个 \r\n）

IP 包的 TTL 默认为 4，但也可以更具具体的情况进行调整。

下面会详细介绍一下上面请求体中各个字段的作用。如非特殊说明，所有的头字段的 Key( field ) 都为大些( UpperCase )。

request line

值域	描述
NOTIFY	发送 notifications 和 events 的方法
*	请求通用而非特定资源必须具备
HTTP/1.1	HTTP 的版本

headers

值域	描述
HOST	必须具备 Internet 号码分配机构（IANA）为 SSDP 保留的多播信道和端口（239.255.255.250:1900）。如果在该字段中省略了 1900 这个端口号，那么接受端应该默认使用 1900 这个端口。
CACHE-CONTROL	必须具备指定广播的有效秒数的 max-age 指令。超过此时间之后，控制点应假定设备（或服务）不再可用。该字段应大于或等于 1800 秒（30分钟）。但可由 UPnP 供应商配置指定。数据类型为整数。
LOCATION	需要包含包含指向根设备的 UPnP 描述的 URL。通常，在非托管网络中，主机部分包含的是 IP 地址字符串，而不是域名。由 UPnP 供应商指定。单一网址。
NT	需要支持指定 Notification 的类型，具体请参考一下 NT 那张表
NTS	需要支持 Notification 的子类型，目前必须是该字段 `ssdp:alive`
SERVER	需要支持。包含操作系统名称，操作系统版本，UPnP / 1.0，产品名称和产品版本的串联。这些信息由 UPnP 供应商自行指定。数据类型：字符串。该头字段必须准确反映设备支持的 UPnP 设备体系结构的版本号。控制点必须准备好接受比控制点本身实现的更高的次要版本号。例如，实现 UDA 版本 1.0 的控制点将能够与实现 UDA 版本 1.1 的设备进行互操作。
USN	需要支持。唯一服务名称。标识设备或服务的唯一实例。必须是以下之一。该字符串的前缀（在双冒号之前）必须与设备描述中的 UDN 元素的值匹配。（“描述”部分将介绍了 UDN 元素。）仅存在单个 URI。

值域	描述
upnp:rootdevice	根设备，此类消息在一个设备中只会出现一条。
uuid:device-UUID	每一个设备只会发送一次，根设备或者嵌入设备 UUID 由 UPNP 供应商（vendor）自己决定。
urn:schemas-upnp-org:device:deviceType:v	每一个设备只会发送一次，根设备或者嵌入式设备。设备类型和版本号由 UPnP 供应商自己确定。指定的版本号为最高支持的版本
urn:schemas-upnp-org:service:serviceType:v	每个服务发送一次。服务类型和版本号有 UPnP Forum 制定，指定的版本号为最高支持的版本
urn:domain-name:device:deviceType:v	每一个设备只会发送一次，根设备或者嵌入式设备。域名的定义由 UPnP 供应商决定，指定的版本号为最高支持的版本域名中的句点字符必须根据 RFC 2141 替换为连字符。
urn:domain-name:service:serviceType:v	每一个服务都会发送一次。域名，服务类型和版本号都由 UPnP 供应商自己定义，这里指定的版本号为最高支持的版本域名中的句点字符必须根据 RFC 2141 替换为连字符。

USN 支持的可选项

值域	描述
uuid:device-UUID::upnp:rootdevice	根设备发送一次设备 UUID 由供应商决定
uuid:device-UUID	每一个设备都会发送一次, 根设备或者嵌入设备设备 UUID 由供应商决定
uuid:device-UUID::urn:schemas-upnp-org:device:deviceType:v	每一个设备都会发送一次, 根设备或者嵌入设备设备 UUID 由供应商决定设备的类型和版本号有 UPnP 委员会确定这里指定的版本号为最高支持的版本
uuid:device-UUID::urn:schemas-upnp-org:service:serviceType:v	每一个服务都会发送一次设备 UUID 由供应商决定设备的类型和版本号有 UPnP 委员会确定这里指定的版本号为最高支持的版本
uuid:device-UUID::urn:domain-name:device:deviceType:v	每一个设备都会发送一次, 根设备或者嵌入设备设备 UUID，域名，设备类型，版本由供应商决定这里指定的版本号为最高支持的版本域名中的句点字符必须根据 RFC 2141 替换为连字符。
uuid:device-UUID::urn:domain-name:service:serviceType:v	每一个服务都会发送一次设备 UUID，域名，服务类型，版本由供应商决定这里指定的版本号为最高支持的版本域名中的句点字符必须根据 RFC 2141 替换为连字符。

NOTIFY 的请求不需要响应。

1.1.3 Discovery: Advertisement: Device unavailable -- NOTIFY with ssdp:byebye

当要将某个设备及其服务从网络中删除时，该设备应多播一个 ssdp：byebye 消息，该消息对应于其多播的尚未到期的每个 ssdp：alive 消息。如果设备突然从网络中删除，则可能无法组播消息。作为后备，发现消息必须在 CACHE-CONTROL 标头中包含一个到期值（如上所述）。如果不重新发布，发现消息最终将会自行失效，并且必须从任何控制点缓存中删除。

（注意：当一个控制点从网络中推出时，不需要 discovery 相关的请求发出。）

当设备将要从网络中删除时，应通过为发送的每个 ssdp：alive 消息发送一个多播请求，显式撤消其发现消息。每个多播请求在 NTS 标头中必须具有以下格式的 NOTIFY 和 ssdp：byebye 方法。斜体值是实际值的占位符

(该请求无 Body 字段，但是后面的空行不能省略，即 IP 负载字段应该以 \r\n\r\n 结尾)

IP 包的 TTL 应该设置成 4, 但是该字段 UPnP 可以根据实际情况修改。

下面将会根据上叙协议中各个字段的详细解释。除非特殊说明，上叙头中的字段都是大小写敏感的。

Request line

值域	描述
NOTIFY	发送 notifications 和 events 的方法
*	请求通用而非特定资源必须具备
HTTP/1.1	HTTP 的版本

headers

值域	描述
HOST	必须具备 Internet 号码分配机构（IANA）为 SSDP 保留的多播信道和端口（239.255.255.250:1900）。如果在该字段中省略了 1900 这个端口号，那么接受端应该默认使用 1900 这个端口。
NT	需要支持（请参考 ssdp:alive 中的说明）这里只包含单个 URI
NTS	需要支持 Notificatioin 的子类型该字段必须为 ssdp:byebye 这里只包含单个 URI
USN	需要支持唯一的服务名字（请参考 ssdp:alive 中的说明）这里只包含单个 URI

（该 NOTIFY 信息不要服务端响应）

由于 UDP 的不可靠特性，设备应多次发送上述每个消息。作为后备，如果控制点无法接收到有关设备或服务不可用的通知，原始发现消息最终将失效，从而产生相同的效果。

1.2 Discovery: Search

将控制点添加到网络后，UPnP 发现协议允许该控制点搜索网络上感兴趣的设备。它通过在保留的地址和端口（239.255.255.250:1900）上多播搜索消息，该搜索消息的特征码或目标等于设备或服务的类型或标识符。来自设备的响应与新设备进入网络时广播的消息基本相同，区别是，前者是单播的，后者是组播的。

1.2.1 Discovery: Search protocols and standards

当要搜索设备（并由控制点发现），控制点（和设备）使用如下的 UPnP 协议栈的子集。（本文档开头列出了整个 UPnP 协议栈。）

在协议顶层，搜索消息包含特定于供应商的信息，例如控制点，设备和服务标识符。协议栈向下一层，供应商内容将由 UPnP 论坛工作委员会提供的信息进行补充，例如设备或服务类型。来自以上各层的消息都将托管在本文档中定义的 UPnP 协议中。相应的，搜索请求是通过 HTTP 的多播变体传递的，该变体已使用其他方法和标头进行了扩展。而搜索响应是通过 HTTP 的单播变体（已扩展）传递的。两种 HTTP 消息都是通过 UDP over IP 传递的。作为参考，上方[方括号]中的颜色表示哪种协议定义了下面列出的发现消息中的特定标头和值。

1.2.2 Discovery: Search: Request with M-SEARCH

当一个控制点加入网络之后，它应该发送一个 M-SEARCH 类型的多播请求。该请求服从下面的格式。Values in italics are placeholders for actual values.

( M-SEARCH 请求没有负载（body 字段），但是结尾的空行必须存在，即数据包应该以 \r\n\r\n 结束。 )

IP 包的 TTL 应该设置成 4, 但是该字段 UPnP 可以根据实际情况修改。

下面将会根据上叙协议中各个字段的详细解释。除非特殊说明，上叙头中的字段都是大小写敏感的。

Request line

值域	描述
NOTIFY	发送 notifications 和 events 的方法
*	请求通用而非特定资源必须具备
HTTP/1.1	HTTP 的版本

headers

值域	描述
HOST	必须具备 Internet 号码分配机构（IANA）为 SSDP 保留的多播信道和端口（239.255.255.250:1900）。如果在该字段中省略了 1900 这个端口号，那么接受端应该默认使用 1900 这个端口。
MAN	该字段服从 HTTP 扩展框架要求。与 NTS 和 ST 标头不同， MAN 标头的值用双引号引起来；它定义扩展的范围（名称空间）。字段值必须为 “ssdp：discover”。
MX	需要支持，该字段指定最大的等待时长，单位为 s, 推荐值在 1 - 120 s 之间。设备的响应该在经过 0 - MAX 之间随机的一段时间后发出，而且不应该为迁就网络状况而去增大该值，（下面会说明原因）这个字段由 UPnP 供应商指定，数据类型为整数
ST	需要支持，指定搜索的目标。必须从以下几个中选择一个（见接下来的 ST 表）仅仅包含一个指向资源的 URI

ST 中包含的可选项

值域	描述
ssdp:all	搜索所有的服务
upnp:rootdevice	仅搜索根设备
uuid:device-UUID	搜索 UUID 指定的设备，UUID 由供应商决定
urn:schemas-upnp-org:device:deviceType:v	搜索任何 deviceType 类型的设备， DeviceType 由 UPnP 委员会定义
urn:schemas-upnp-org:service:serviceType:v	搜索任何 serviceType 类型的设备， serviceType 由 UPnP 委员会定义
urn:domain-name:device:deviceType:v	搜索任何服从该域名，设备类型的设备，这里的域名和设备类型有 UPNP 供应商定义域名中的句点字符必须根据 RFC 2141 替换为连字符。
urn:domain-name:service:serviceType:v	搜索任何服从该域名，服务类型的服务，这里的域名和服务类型有 UPNP 供应商定义域名中的句点字符必须根据 RFC 2141 替换为连字符。

由于 UDP 的不可靠特性，控制点应多次发送各个 M-SEARCH 消息。作为备用，为防止设备收不到控制点发送的 M-SEARCH 消息的可能性，设备应定期重新发送其广告（请参见上面 NOTIFY 中带有 ssdp：alive 的 CACHE-CONTROL 标头）。

控制点应该在 MX s 内一直等待设备发出响应。 MX 间隔上响应的随机分布意味着响应者可能在收到 M-SEARCH 请求后的 MX 秒发送响应。因此供应商应该基于观察到的响应者的数量，然后根据经验调一个合适的 MX 值。也因为上叙原因，因此无法通过增加 MX 值来解决影响流量传播的网络特征。请求者可以根据观察到的网络行为，通过启发式方法适应网络特征（确切的启发式方法不在本文范围内）。算法最终应该会导致请求者等待 M-SEArCH 的时间会略微超过 MX 的时间，从而适应网络的传输特性。以最小化丢失设备的响应。

需要设备和服务类型的更新版本与以前的版本完全向后兼容。设备必须响应任何受支持版本的 M-SEARCH 请求。例如，如果设备实现“ urn：schemas-upnporg：service：Audio：2”，则该设备也应该响应类型为 “ urn：schemas-upnp-org：service：Audio：1” 的搜索请求。响应中应指定与搜索请求中包含的版本相同的版本。如果控制点搜索特定版本的设备或服务并且未收到任何响应（大概是因为网络上没有设备支持指定的版本），但愿意使用较低的版本进行操作，则它可能会重复搜索指定较低的版本。

1.2.3 Discovery: Search: Response

为了找到这些设备，设备必须为每一个从该多播地址收到的请求返回一个响应。如果发起 MSEARCH 设备的 ST 头为 “ssdp:all” 或者 "upnp:rootdevices" 或者 "uuid:device-UUID"（device-UUID 和本设备一致）, 设备则必须响应这些消息，

设备在收到 DMC 发出的请求之后应该随机的响应 0 - MX 指定的时间然后才响应设备的请求。这么做是为了防止环境中的设备集中的响应 DMC 的请求，造成短暂的网络拥塞，如果一个搜索请求有多个响应，那么这些响应也应该随机的分布在 0 - MX 时间段内。如果搜索请求不包含 MX 标头，则设备必须静默丢弃并忽略搜索请求。如果 MX 标头指定的值大于120，则设备应假定其包含的值等于或小于 120。设备在发送响应之前等待随机延迟的同时，不应停止响应其他请求。

在 M-SEARCH 的响应消息中，LOCATION 字段指定的 URL 必须是可以访问的。

设备对 M-SEARCH 的响应是有意相似于 ssdp:alive 的广播消息的，比如说响应的头几乎与 ‘ssdp:alive’ 消息的头一致（除了 NT 头换成了 ST 头）。响应必须以以下格式发送。斜体值是实际值的占位符

( M-SEARCH 请求没有负载（body 字段），但是结尾的空行必须存在，即数据包应该以 \r\n\r\n 结束。 )

IP 包的 TTL 应该设置成 4, 但是该字段 UPnP 可以根据实际情况修改。

下面将会根据上叙协议中各个字段的详细解释。除非特殊说明，上叙头中的字段都是大小写敏感的。

request line

值域	描述
HTTP/1.1	HTTP 的版本
200	HTTP 状态码，200 代表成功响应
OK	响应成功的描述字段

headers

值域	描述
CACHE-CONTROL	必须具备指定广播的有效秒数的 max-age 指令。超过此时间之后，控制点应假定设备（或服务）不再可用。该字段应大于或等于 1800 秒（30分钟）。但可由 UPnP 供应商配置指定。数据类型为整数。
DATE	建议携带此字段响应的时候生成，格式 follow “rfc1123-date”，在 RFC 2616 中有定义。
EXT	该字段由（ HTTP Extension Framework）引入主要用于确定理解请求中 “MAN” 头该头不需要携带任何值
LOCATION	需要包含包含指向根设备的 UPnP 描述的 URL。通常，在非托管网络中，主机部分包含的是 IP 地址字符串，而不是域名。由 UPnP 供应商指定。单一网址。
SERVER	需要支持。包含操作系统名称，操作系统版本，UPnP / 1.0，产品名称和产品版本的串联。这些信息由 UPnP 供应商自行指定。数据类型：字符串。该头字段必须准确反映设备支持的 UPnP 设备体系结构的版本号。控制点必须准备好接受比控制点本身实现的更高的次要版本号。例如，实现 UDA 版本 1.0 的控制点将能够与实现 UDA 版本 1.1 的设备进行互操作。
ST	如果请求中指定搜索此头，那么在这里就要包含此头。具体请参考请求部分的说明
USN	需要支持。这里指定唯一服务名称。具体请参考 "ssdp:alive" NOTIFY 部分的说明

如果搜索请求出现错误（例如 MAN 标头中的值无效，MX 标头丢失或其他格式错误的内容），则设备应静默丢弃并忽略搜索请求。不建议发送错误响应，因为如果许多设备向同一请求发送错误响应，则可能会出现数据包风暴。

1.3 Discovery references

RFC 2141
URN Syntax. http://www.ietf.org/rfc/rfc2141.txt
RFC 2616
HTTP: Hypertext Transfer Protocol 1.1. http://www.ietf.org/rfc/rfc2616.txt.
RFC 2774
HTTP Extension Framework. http://www.ietf.org/rfc/rfc2774.txt.

2. Description

Description 是 UPnP™ 网络中的步骤 2，在寻址（步骤0）和设备发现（步骤1）之后。

在控制点发现设备之后，控制点仍然对设备知之甚少 - 仅仅能获取发现消息中涉及到的信息，即设备（或服务）的 UPnP 类型，设备的通用标识符以及设备 UPnP 描述的 URL。为了控制点了解有关设备及其功能的更多信息，或与设备交互，控制点必须从发现消息中由设备提供的 URL 检索设备及其功能的详细描述。

设备的 UPnP 描述分为两个逻辑部分：一个设备描述（名词）描述（动词）物理和逻辑容器，以及描述设备公开的功能的服务描述。 UPnP 设备描述包括特定于供应商的制造商信息，例如型号名称和编号，序列号，制造商名称，特定的供应商的网站的 URL 等（以下详细信息）。对于设备中包含的每个服务，设备描述都列出了服务类型，名称，服务描述的 URL，控制的 URL 和事件的 URL。设备描述还包括所有嵌入式设备的描述以及用于展示设备状态信息或者控制接口的 URL。本节说明 UPnP 设备说明，而“控制”，“事件”和“演示”部分分别说明如何使用用于控制，事件和演示的 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 设备描述很简单：控制点使用 HTTP GET 请求去访问设备描述的 URL(在 Discovery 阶段获取)，然后设备即会返回设备对应的描述。检索 UPnP 服务描述的过程与在设备描述中使用 URL 的过程一样。响应和请求的协议栈，方法，标头和主体在下面详细说明。

只要来自设备的发现广播还没有过期，控制点就可以假定该设备及其服务可用。由于设备和服务描述是静态的，因此只要设备及其服务可用，就可以在任何时候检索设备和服务描述。如果设备取消其广播或广播到期，则控制点应假定该设备及其服务不再可用。如果设备需要更改这些描述之一，则必须取消其未完成的广播并重新进行广播。因此，如果设备重新出现在网络上，则控制点不应假定设备和服务描述不变。

像发现一样，描述在使用不同版本的 UPnP 网络的设备和控制点的互操作性中也起着重要作用。如发现部分所述，UPnP 设备体系结构既有主要版本也有次要版本。主版本和次版本是单独的整数；即使它们可能出现在打印中，也不应将其解释为一个带小数点的数值。次要版本的提升必须是同一主版本的较早次要版本的兼容超集。主要版本中的进步不一定是早期版本的超集，也不保证其向后兼容。版本信息在描述消息中传递，作为后备，此信息也存在在设备的发现消息中。本节将会说明描述消息中版本信息的格式。

设备和服务的标准由 UPnP 论坛工作委员会标准化或由供应商创建。设备或服务的每个更高版本都必须是先前版本的完全向后兼容的超集，即，与该设备的早期版本相比，当前版本必须包括前一版本的所有嵌入式设备和服务。在设备的所有版本中，UPnP 设备或服务类型均相同，而对于更高版本，设备或服务版本必须更大。在工作委员会的开发过程中，设备和服务模板的版本可能具有非整数版本（例如“ 0.9”），但是标准化后必须成为整数。设备和服务的版本号可能大于其设计所针对的体系结构的主要版本号（例如，“ Power：2”可能被设计为在 UDA 版本1.0上工作）；设备或服务模板的版本与设计用来工作的体系结构的版本之间没有直接关联。如果定义了设备或服务的非向后兼容版本，则该设备或服务必须具有不同的设备或服务名称，以指示其不向后兼容（新类型的版本号应从1重新开始）。

UPnP 设备和服务类型可以以各种组合形式组装成 “building blocks”。标准设备类型和供应商定义的设备类型都可以嵌入标准设备类型中。标准和供应商定义的设备类型都可以嵌入在供应商定义的设备类型中。同样，标准和供应商定义的服务类型都可以嵌入在标准和供应商定义的设备类型中。能够与特定设备或服务类型一起工作的控制点，即使将其嵌入在无法识别的另一种设备类型（标准或供应商定义）中，也应识别该设备或服务类型。例如，如果定义了标准服务类型“ Print：1”，并且定义了包含“ Print：1”服务的标准设备类型“ Printer：1”，控制点希望找到并使用“ Print：1” 服务应，无论服务是嵌入在 “urn：schemas-upnp-org：device：Printer：1” 设备中, 还是嵌入在供应商定义的 “urn：acme-com：device：Printer：1” 中, 或者 “urn：acme-com：device：AcmeMultifunctionPrinter：1”。

本节的其余部分首先说明如何描述设备，并详细说明特定于供应商的信息，嵌入式设备以及用于控制，事件和显示的URL。其次，它说明了 UPnP 设备模板。第三，它解释了如何描述服务，解释了动作，参数，状态变量以及这些变量的属性的详细信息。然后说明 UPnP 服务模板和 UPnP 模板语言。最后，本节详细说明控制点如何从设备检索设备和服务描述。

2.1 Description: Device description

设备的 UPnP 描述包含几条特定于供应商的信息，所有嵌入式设备的定义，用于设备显示的 URL，所有服务的列表以及用于控制和事件的URL。除了定义非标准设备（供应商定义的设备和标准嵌入式设备和服务）之外， UPnP供应商还可以提供这些信息，以下是实际元素和值的占位符列表（斜体）。其中一些占位符将由 UPnP 论坛工作委员会（红色）或 UPnP 供应商（紫色）指定。对于非标准设备，所有这些占位符将由 UPnP 供应商指定。（由UPnP设备体系结构定义的元素显示为绿色，以备后用。）紧随清单之后的是元素，属性和值的详细说明。

下面列出的是上面列表中出现的每个元素，属性和值的详细信息。所有元素和属性都区分大小写； HTTP 指定 URL 也区分大小写；除非另有说明，否则其他值不区分大小写。元素的顺序无关紧要。除非另有说明：必需元素必须只出现一次（没有重复），推荐或可选元素最多也只能出现一次。请注意，某些实现可能会严格执行以下各个元素的长度限制，因此建议工作委员会注意所有指定的限制。

xml Required | 此字段区分大小写。
root Required | 此元素必须设置 xmlns 属性，而且值必须是 urn:schemas-upnp-org:device-1-0，这引用了 UPnP 模板语言（如下所述）。该元素下的子元素一起描述了根设备，区分大小写。其子设备类型如下：
- specVersion Required | 包含下列元素
  - major Required | UDA 的主版本号，必须为 1
  - minor Required | UDA 的子版本号. 对于实现 UDA 1.0 版本的设备此元素的值必须为 0
  这两个子元素必须准确的反应所实现的 UDA 的版本。而对于控制端，则必须准备接受设备端的版本高于自身的情况。
- URLBase Optional | 定义 Base URL。用于构造标准 URL。根据 RFC 2396 中的规则，描述中其他位置出现的 URL 将是 Base URL 的相对路径, 在使用其他 URL 的时候需要先与 Base URL 拼接成一个完整的 URL。如果 URLBase 为空或未给出，则可以直接访问其他位置出现的 URL（这是现在的首选实现，不再建议使用 URLBase）。由UPnP供应商指定。| Single URI。
- device Required. 包含下面的元素:
  - deviceType REQUIRED | UPnP 设备类型. Single URI.
    - 对于由 UPnP 论坛工作委员会定义的标准设备，必须以 "urn:schemasupnp-org：device""开头，然后是标准化设备类型后缀，冒号和整数设备版本，即 urn: schemas-upnp-org:divice deviceType:ver。必须指定设备类型的最高支持版本。
    - 对于UPnP供应商指定的非标准设备，必须以 "urn:" + 供应商域名 + ”：device：” + ”deviceType“ + 冒号 + 整数版本，即“ urn：域名：device：deviceType：ver”。供应商域名中的句点字符必须根据 RFC 2141 替换为连字符。必须指定设备类型的最高支持版本。
    设备类型的后缀由 UPNP 委员会定义，或者由设备供应商定义，长度必须小于 64 字节（版本号和冒号不在计数范围）。
  - friendlyName Required | 一个对终端用户友好的简短描述，应支持本地化语言(参见. ACCEPT-LANGUAGE 和 CONTENTLANGUAGE 头). 由设备供应商指定。该元素值必须小雨 64 字节 | String 类型。
  - manufacturer Required | 制造商名字. 应该支持本地化 (参见. ACCEPT-LANGUAGE 和 CONTENTLANGUAGE 头). 由设备供应商指定。该元素值必须小雨 64 字节 | String 类型。
  - manufacturerURL Optional | 制造商的主页，应该支持本地化 (参见. ACCEPT-LANGUAGE 和 CONTENTLANGUAGE 头). 由设备供应商指定。该元素值必须小雨 64 字节 | String 类型。
  - modelDescription Recommended | 关于设备模块的详细描述，应该支持本地化 (参见. ACCEPT-LANGUAGE 和 CONTENTLANGUAGE 头). 由设备供应商指定。该元素值必须小雨 128 字节 | String 类型。
  - modelName Required | 设备模块名字，应该支持本地化 (参见. ACCEPT-LANGUAGE 和 CONTENTLANGUAGE 头). 由设备供应商指定。该元素值必须小雨 32 字节 | String 类型。
  - modelNumber Recommended | 设备模块数量，应该支持本地化 (参见. ACCEPT-LANGUAGE 和 CONTENTLANGUAGE 头). 由设备供应商指定。该元素值必须小雨 32 字节 | String 类型。
  - modelURL Optional | 模块的介绍网址，应该支持本地化 (参见. ACCEPT-LANGUAGE 和 CONTENTLANGUAGE 头). 由设备供应商指定。该字段有可能是资源相对与 BaseURL 的相对位置 | String 类型。
  - serialNumber Recommended | 设备序列号，应该支持本地化 (参见. ACCEPT-LANGUAGE 和 CONTENTLANGUAGE 头). 由设备供应商指定。该元素值必须小雨 64 字节 | String 类型。
  - UDN Required | 唯一的设备名称，设备的通用唯一标识符（与根标识符还有嵌入式标识符也保持唯一性）。在设备的生命周期内，该元素的值应该保持不变（即重启后任然有效，恢复出厂设置之后可以变更），必须与设备发现消息中 NT 标头的值匹配。在所有发现消息中，必须与 USN 标头的前缀匹配。（关于发现的部分说明了 NT 和 USN 标头）。必须为以下格式（ ”uuid：“ + PnP 供应商指定的UUID后缀） | 单个URI。
  - UPC Optional | 通用产品代码（Universal Product Code），由 12 个数字组成，标识消费者包装的代码。由统一代码委员会管理（the Uniform Code Council）。由 UPnP 供应商指定 | Single UPC。
  - iconList 如果产品有自己的 ICON, 那么此字段就需要存在。有供应商自己指定，包含以下元素。
    - icon Recommended | 用于在控制点 UI 中描绘设备的图标。应该支持本地化 (参见. ACCEPT-LANGUAGE 和 CONTENTLANGUAGE 头). ICON 的大小是取决于供应商设计。包含以下子元素：
      - mimetype Required | Icon 的 MIME type， (参考 RFC 2045, 2046, and 2387) | Single MIME image type | 至少应该包含 image/png (Portable Network Graphics, see IETF RFC 2083) 类型
      - width Required | icon 的水品大小（宽） | 单位为像素 | Integer
      - height Required | icon 的垂直大小（高） | 单位为像素 | Integer
      - depth Required | icon 每个像素的（色彩深度） | Integer
      - url Required | img 的 URL( XML 不支持直接嵌入图片在描述文档中. 参看下面的注释) | 该字段有可能是资源相对与 BaseURL 的相对位置 | 由 UPNP 供应商指定 | Single URL.
  - serviceList Optional | 包含以下元素:
    - service Optional | 对于 UPNP 委员会定义的每个服务都要有描述，对于供应商额外自定义的用来区分设备的服务也需要在这里有描述。该服务元素有一下属性。
      - serviceType Required | 服务类型 | 必须包含一个 23 位 UTF-8 编码的散列值 | Single URI.
        
        对于由 UPnP 委员会定义的标准服务类型，必须遵守以下格式( “urn：schemas-upnp-org：service" + 标准服务类型后缀 + ： + 整数服务版本)，即 urn: schemas-upnp-org:device：：serviceType：ver 。必须指定服务的最高支持版本。
        
        对于非标服务，则必须遵守以下格式 ( "urn:" + 供应商的域名 + ”:service:“ + 服务类型后缀 + 服务版本号-整数 )，供应商域名中的句点字符必须根据RFC 2141替换为连字符。必须指定服务类型的最高支持版本。
        
        这些服务的类型有 UPnP 委员会或者供应商定义，长度必须小于 64 字节 ( 类型后缀和冒号分隔符不包括在内 )。
      - serviceId REQUIRED | 服务的唯一标识 | 在整个设备描述中必须是唯一的 | Single URI.
        
        对于 UPNP 委员会定义的标准服务，这里必须是服从以下格式 ( urn:upnp-org:serviceId: + 服务的 ID 后缀 )（如 urn:upnporg:serviceId:serviceID ）。如果这个实例在上面指定的服务类型（如：）属于上面指定的设备类型（如：）之一，则服务 ID 后缀的值必须为设备 ID 为该服务实例定义的服务 ID。否则，服务 ID 后缀的值是供应商定义的。（请注意，在这种情况下，使用 upnp-org 代替了 schemas-upnp-org，因为没有为每个服务ID定义XML模式。）
        
        对于非标设备，必须服从以下格式（”urn：“ + 供应商域名 + ":serverId:" + 服务 ID 后缀），例如： “urn:domain-name:serviceId:serviceID”。如果这个实例在上面指定的服务类型（如：）属于上面指定的设备类型（如：）之一，则服务 ID 后缀的值必须为设备 ID 为该服务实例定义的服务 ID。否则，服务 ID 后缀的值是供应商定义的。（请注意，在这种情况下，使用 upnp-org 代替了 schemas-upnp-org，因为没有为每个服务ID定义XML模式。）域名中的句点字符必须根据 RFC 2141 替换为连字符。
        
        这里的设备 ID 后缀由 UPNP 委员会或者供应商定义，必须小于 64 字节。
      - SCPDURL Required | 详细描述此服务的 URL， (nee 服务控制协议定义 URL). (参考以下服务描述章节的说明）又 UPNP 供应商指定 | Single URL.
      - controlURL Required | 用于控制的 URL (参考以下控制章节的说明). 此字段有可能是 BaseURL 的相对路径 | 有供应商指定 | Single URL.
      - eventSubURL Required | 事件的 URL（请参阅事件部分）。可能是 BaseURL 的相对路径。设备内必须唯一；没有两个服务可以具有用于事件的相同 URL。如果服务没有事件变量，则不应包含事件（请参见事件部分）；如果服务没有事件，则此元素必须存在但应为空，即。 | 由UPnP供应商指定 | Single URL.
  - deviceList 当此根设备拥有嵌入设备的时候，此元素存在。该元素拥有以下子元素：
    - device Required | 有供应商决定 | 没有嵌入设备都必须拥有一个描述，如果供应商这里的子元素的定义和上面根设备包含的子元素一致。
  - presentationURL Recommended | 展示设备状态和控制界面的 URL (参考展示章节). 此字段有可能是 BaseURL 的相对路径 | 有供应商指定 | Single URL.

控制点在识别和与设备交互时使用的 serviceID 应该要与设备定义的值不同。如果存在一个服务有多个实例，则控制点应默认（除非用户操作另有指示）应使用与设备类型定义的 serviceId 值关联的服务实例。如果服务的所有实例都不具有由设备类型定义的 serviceId 值，则控制点可以使用任何服务实例。当仅存在一个服务实例时，即使 serviceId 值与设备类型定义的值不匹配，控制点也应使用该实例。

为看可扩展性，当像上面的清单那样处理 XML 时，设备和控制点必须忽略：（a）任何未知元素及其子元素或内容以及（b）任何未知属性及其值。

控制点和设备应忽略它们不理解的 UPnP 设备和服务描述中嵌入的任何 XML 注释或 XML 处理指令。

UPnP设备描述应使用UTF-8编码。

当任何文本元素或属性的值包含一个或多个保留标记的字符时（例如 ampersand（＆）或 less than（“ <”）），必须按照XML规范第2.4节的规定对文本进行转义，并将每个此类字符替换为等效的数字表示形式或字符串（例如“&”或“<”）。出现在 URL 中的此类字符也可以根据 RFC 2396 第 2.4 节中指定的 URL 转义规则进行转义。

XML 不支持直接将二进制数据（例如，图标）嵌入 UPnP 设备描述中。如果一定要嵌入，可以使用 bin.base64（二进制数据的 MIME-style 的 base 64 编码）或 bin.hex（十六进制数字代表八位字节）的 XML 数据类型将二进制数据转换为文本。或者，可以通过在 XML 中嵌入 URL 并响应单独的 HTTP 请求来传输数据来间接传递数据。 UPnP 设备描述中的图标以后一种方式传输。

如果有包括任何图标，则至少应该采用 RFC 2083 中定义的可移植网络图形（PNG）格式，由 MIME 类型“ image/png” 指示，而且不应该采用 progressive encoding 编码方式。由于各种控制点偏爱的种类繁多，因此不建议使用特定的图标大小。鼓励控制点供应商发布实施指南。

请注意，在 UPnP 设备体系结构的 1.0 版中， serviceList 元素是必需的，并且它至少包含一个服务元素。但随后的版本取消了这些要求，以适应网关和基本设备类型。如果设备没有服务，则 serviceList 元素可以完全省略，也可以存在但不包含服务元素。

2.2 Description: UPnP Device Template

上面的清单说明了 UPnP 设备描述和 UPnP 设备模板之间的关系。如上所述，UPnP 设备描述是由 UPnP 供应商按照 UPnP 设备模板以 XML 编写的。 UPnP 委员会制作了 UPnP 设备模板，作为标准化设备的一种方法。

通过选择适当的占位符，上面列出的内容可以是 UPnP 设备模板或 UPnP 设备描述。其中，某些占位符由 UPnP 论坛工作委员会（红色）定义（如：UPnP 设备类型标识符 / UPnP 服务 / UPnP 嵌入式设备（如果有的话））。如果这些被编写到代码中，则生成的 XML 文档即是 UPNP 设备模板。 UPnP 设备模板是 UPnP 论坛工作委员会的主要成果之一。

更进一步，由 UPnP 供应商（紫色）指定上面列表中的其余占位符，即特定于供应商的信息。如果在代码中指定了这些占位符（以及其他占位符），则列表将是 UPnP 设备描述，适合传递给控制点以用来后续的控制 / 事件 / 演示。

换句话说，UPnP 设备模板定义了设备的整体类型，每个 UPnP 设备描述都使用供应商特定的信息实例化该模板。前者 UPnP 论坛工作委员会定义，而后者由 UPnP 供应商定义。

2.3 Description: Service description

PnP 描述定义了服务的可执行动作, 参数，状态变量及其数据类型，范围和事件特征。

每个服务可能有零个或多个动作。每个动作可以具有零个或多个参数。这些参数可以是输入参数或也可以是输出参数。如果一个动作具有一个或多个输出自变量，则这些自变量中的一个可被标记为返回值。每个参数应对应一个状态变量。这给直接操纵的编程模型增强了简单性。

每一个服务必须有一个或者多个状态变量。

为了定义非标服务，UPnP 供应商可能会增加自己定义的 action 或者 service 给标准设备，而且也可能嵌入非标准设备到标准设备。

为了说明这些观点，下面列出了包含实际元素的占位符（以斜体显示）和值。对于标准的 UPnP 服务，其中一些占位符将由 UPnP 论坛工作委员会定义（红色）或由UPnP供应商指定（紫色）。对于非标准服务，所有这些占位符将由 UPnP 供应商指定。（由UPnP设备体系结构定义的元素显示为绿色，以备后用。）紧随清单之后的是元素，属性和值的详细说明。

下面列出的是上面列表中出现的每个元素，属性和值的详细信息。所有元素和属性（包括动作，参数和状态变量名称）均区分大小写, 顺序也无关紧要，必需元素必须仅出现一次（没有重复），推荐或可选元素最多只能出现一次，除非另有说明。

xml所有的 XML 文档都大小写敏感
scpd Required | Must | 属性 xmlns 的值必须是 urn:schemas-upnp-org:service-1-0; 这引用了UPnP模板语言（如下所述）。下面详细介绍该元素的子元素：
- specVersion Required | 包含以下元素:
  - major Required | UDA 的主版本号，必须为 1
  - minor Required | UDA 的子版本号. 对于实现 UDA 1.0 版本的设备此元素的值必须为 0
  这两个子元素必须准确的反应所实现的 UDA 的版本。而对于控制端，则必须准备接受设备端的版本高于自身的情况。
- actionList Required （如果服务拥有 action ） (每一个服务必须包含 >= 0 个 action), action 的子元素有如下几种：
  - action Required | 对 UPnP 委员会定义的每个操作都要实现一次。如果 UPnP 供应商需要通过添加其他 action 来区分服务，则也要为添加的 action 实现在此处。一个 action 包含以下子元素：
    - name Required | action 的名字，不得包含连字符（-，UTF-8 中为 0x2D ）或哈希字符（＃，UTF-8 中为 0x23）。 | 区分大小写 | 第一个字符必须是 USASCII 字母（A-Z，a-z）/ USASCII 数字（0-9） / 下划线（“ _”）/ 大于 U+007F 的非实验性 Unicode 字母或数字。
      支持的字符必须在以下范围 USASCII 字母（A-Z，a-z） / USASCII 数字（0-9） / 下划线（“ _”） / 句点（“.”） / Unicode组合字符 / 扩展程序或非实验性 Unicode 大于 U+007F 的字母或数字。在任何情况下，前三个字母不得为“ XML”。
      - 对于标准的 action 必须以 X_ 或者 A_ 开头。
      - 对于非标 action，但是是添加到标准设备中的 action，则必须以 X_ 开头。
      String | 必须小于 32 个字符。
    - argumentList Required （当且仅当 action 定义了要操作的参数时）( 每一个 action 可能会有 >= 0 个参数)，参数有以下的子元素
      - argument Required | 每一个参数都拥有这样的一个元素，该元素又如下子元素：
        
        name Required | 参数的名字 | 不得包含连字符（UTF-8中为 '-'，0x2D）。第一个字符必须是 USASCII 字母（A-Z，a-z）， USASCII 数字（0-9），下划线（“ _”）或大于 U+007F 的非实验性 Unicode 字母或数字。中间包含的字符必须在以下范围内： USASCII 字母（A-Z，az） / USASCII数字（0-9） / 下划线（“ _”），句点（“.”），Unicode 组合字符，扩展程序或非实验 Unicode 大于 U+007F的字母或数字。任何组合中，前三个字母不得为“ XML”。应小于32个字符。
        
        direction Required | 参数是输入参数还是输出参数。值必须是 in or out。
        
        retval Optional | 最多将一个 out 参数指定为返回值。如果在一个 action 中指定了一个返回值，则该参数在文档顺序中一定要是在 out 类型的参数列表中排第一。
        
        relatedStateVariable Required | 该参数关联的状态变量名称，
- serviceStateTable Required | 每一个服务包含大于 0 个状态变量，该状态变量的元素对象包含如下元素：
  - stateVariable Required | 对 UPnP 委员会定义的每个状态变量都要在此实现。如果 UPnP 供应商有通过添加其他状态变量来区分服务，则每个其他变量也需要在此实现。 sendEvents 属性定义当此状态变量的值更改时是否生成事件消息；非事件状态变量具有 sendEvents = “no”; 默认值为 sendEvents = yes。该状态变量的元素对象包含如下元素：
    - name Required | 状态变量的名字，不得包含连字符（-，UTF-8 中为 0x2D ）或哈希字符（＃，UTF-8 中为 0x23）。 | 区分大小写 | 第一个字符必须是 USASCII 字母（A-Z，a-z）/ USASCII 数字（0-9） / 下划线（“ _”）/ 大于 U+007F 的非实验性 Unicode 字母或数字。
      支持的字符必须在以下范围 USASCII 字母（A-Z，a-z） / USASCII 数字（0-9） / 下划线（“ _”） / 句点（“.”） / Unicode组合字符 / 扩展程序或非实验性 Unicode 大于 U+007F 的字母或数字。在任何情况下，前三个字母不得为“ XML”。
    - dataType Required | 与 XML Schema 第 2 部分《数据类型定义》的数据类型相同。由 UPnP 委员会为标准状态变量定义，或者由UPnP供应商指定用于扩展。必须为以下值之一：
      - ui1 1 Byte 无符号整形。数值范围 [0, 255] 。
      - ui2 2 Byte 无符号整形。数值范围 [0, 65535]。
      - ui4 4 Byte 无符号整形。数值范围 [0, 4294967295] 。
      - i1 1 Byte 有符号整形。数值范围 [-128 , 127 ]。
      - i2 2 Byte 有符号整形。数值范围 [-32768 ,32767 ]。
      - i4 4 Byte 有符号整形。数值范围 [-2147483648, 2147483647] 。
      - int Fixed point, integer number. May have leading sign. May have leading zeros. (No currency symbol.) (No grouping of digits to the left of the decimal, e.g., no commas.)
      - r4 4 字节浮点型，格式和 float 一样，数值范围在 [ 3.40282347E+38 , 1.17549435E-38 ] 之间。
      - r8 8 字节浮点型，格式和 float 一样，复数数值范围在 [ -1.79769313486232E308， -4.94065645841247E-324 ] 之间。正数在 [4.94065645841247E-324 ， 1.79769313486232E308 ] 之间。
      - number Same as r8.
      - fixed.14.4 Same as r8，但是不会超过 14 个数字在小数点左边，不会超过 4 个数字在小数点右边。
      - float Floating point number. Mantissa (left of the decimal) and/or exponent may have a leading sign. Mantissa and/or exponent may have leading zeros. Decimal character in mantissa is a period, i.e., whole digits in mantissa separated from fractional digits by period. Mantissa separated from exponent by E. (No currency symbol.) (No grouping of digits in the mantissa, e.g., no commas.)
      - char Unicode string. 一个字节。
      - string Unicode string.不限长度。
      - date 格式遵从 ISO 8601 标准，但不包括 time data 类型.
      - dateTime 格式遵从 ISO 8601 标准，但不包括 timezone.
      - dateTime.tz 格式遵从 ISO 8601 标准，time 和 timezone 都是可选的。
      - boolean 值包含两个值 0 / 1, 0 代表假，1 代表真，”true“ / ”false“, ”yes“ / ”no“ 也可以使用，但是不推荐。
      - bin.base64 MIME 样式的 Base64 编码的二进制 BLOB。每 3 个字节分成 4 个 par，每一 Par 占 6 个 bit。然后将 6 个 bit 映射到 8 个 bit 中。大小不受限制。
      - bin.hex 将一个字节拆分成两个十六进制字符表示，每 4 个 bit 对应一个字符。大小不受限制。
      - bin.uri uri
      - bin.uuid UUID( niversally Unique ID )。代表八位位组的十六进制数字。可选的嵌入式连字符将被忽略。
    - defaultValue Recommended | 初始值，由 UPnP 委员会定义或者 UPnP 供应商定义. 必须符合以上的数值类型，必须在以下提到的 allowedValueList 或者 allowedValueRange 内。
    - allowedValueList Recommended | 枚举合法的字符串值。禁止使用非字符串数据类型。该字段与allowedValueRange 互斥。子元素是有序的（参见NEXT_STRING_BOUNDED）。包含以下子元素：
      - allowedValue Required | 一个合法的字符串值，对于标准的状态变量，这里的值由 UPnP 委员会定义，对于 UPnP 扩展的则又供应商自己决定。该字段的值必须小于 32 个字符。
    - allowedValueRange Recommended. 定义一个合法的数值范围，该字段与 allowedValueList 互斥。包含以下子元素：
      - minimum Required | 可选范围的下边界，由 UPnP 委员会定义，对于 UPnP 扩展的则又供应商自己决定。此处为单个数值。
      - maxiumum Required | 可选范围的上边界，由 UPnP 委员会定义，对于 UPnP 扩展的则又供应商自己决定。此处为单个数值。
      - step Recommended | 每一次 increment 或者 decrement 是的步进。例如在操作 v = v + s 中 s 的值。由UPnP论坛工作委员会定义或委托给UPnP供应商。单个数值。

元素 relatedStateVariable 的值必须是定义在同一服务里状态变量的名称。 relatedStateVariable 定义了参数的类型； argument 和 relatedStateVariable 之间不一定存在任何语义关系。 relatedStateVariable 必须在 serviceStateTable 中指定 stateVariable 的名称，该名称具有的 dataType， allowedValueList 和 allowedValueRange。如果不存在带有适当定义的 stateVariable，则工作委员会（或供应商）必须为此目的定义其他状态变量；用于描述参数类型而定义的状态变量的名称的前缀应该是 “ A_ARG_TYPE_”。

allowedValueList 和 allowedValueRange 元素可用于指示设备可选的功能。 UPnP 委员会可能要求列表或范围中的所有值都应由所有供应商支持（无选项），或带有最小可选值的最小子集，或允许供应商完全决定。如果委员会允许，供应商可以将供应商定义的 allowedValues 添加到标准 allowedValueList 中（名称前缀必须为 'X_'）。但是，应注意，定制的可选功能应该尽可能的减少了控制点可能依赖的值的数量，从而防止影响到交互操作时的兼容性。如果设备功能会在设备运行期间发生变化，则委员会应定义单独的 action 来检测设备功能，而不是将区分功能的信息嵌入到服务描述中。而每次服务描述文档更改时，设备都应该取消之前的广播并重新发布新的功能的广播。如果服务描述用于传达功能信息，则设备必须从服务描述中省略未实现的可选元素（动作，allowedValues等）。

为了将来的可扩展性，当像上面的清单那样处理 XML 时，设备和控制点必须忽略：（a）任何未知元素及其子元素或内容，以及（b）任何未知属性及其值。

控制点和设备应忽略嵌入在 XML 描述文档中的注释，和控制点本身不支持或者不懂的那些描述。

UPnP 服务描述应使用 UTF-8 编码。

任何属性或者元素的值都包含一个或者多个保留字（即 '&' 符号或者是 '<'）, 如一定要使用此类字符则必须按照 XML 规范的 2.4 节的规定对文本进行转义，并用等效的数字表示形式或字符串替换每个此类字符（例如 '& amp;” 或 “& lt;”）。出现在 URL 中的此类字符也可以根据 RFC 2396 第 2.4 节中指定的 URL 转义规则进行转义。注意，服务在逻辑上可能没有任何动作，但具有状态变量和事件；尽管这种服务不太可能，但是它将成为自治信息源。但是注意，禁止使用没有状态变量的服务。

与设备描述不同，服务描述和关联的值不应使用 locale-specific（本地化）的值。应用程序应将信息从标准格式转换（格式化）为语言环境的正确语言（或格式）。例如，日期以与语言环境无关的格式（ISO 8601）表示，而整数则以没有语言环境特定的格式表示（例如，没有货币符号，没有数字分组）。字符串值应以标准的 “语言环境” 或与语言环境无关的方式表示。具有 allowedValueList 的变量应使用 UPnP 标准语言的标记值。

但是，在某些情况下，动作的行为取决于语言环境。在这种情况下，应该定义一个参数来指示语言环境，比如可以使用 ACCEPT-LANGUAGE 和 CONTENT-LANGUAGE 标头（RFC 1766）。如果存在多个依赖于语言环境的 action，则该服务可以包括一个操作，该操作用于设置状态变量以指示语言环境，以消除了将语言环境标识符分别传递给每个操作的需要。

UPnP 委员会标准化的服务具有整数版本。服务的每个更高版本都必须是先前版本的超集，即，它必须完全包含服务的早期版本所定义的所有操作和状态变量。 UPnP 服务类型在服务的所有版本中都相同，而对于更高版本，该服务版本必须更大。在工作委员会的开发过程中，设备和服务模板的版本可能具有非整数版本（例如“ 0.9”），但是标准化后必须成为整数。设备和服务的版本号可能大于其设计所针对体系结构的主要版本号，但是设备服务也要应该响应低版本控制端的指令（例如，“ Power：2” 可能被设计为在 UDA 版本 1.0 上工作）。

2.4 Description: UPnP Service Template

上面的清单还说明了 UPnP 服务描述和 UPnP 服务模板之间的关系。如上所述，服务的 UPnP 描述是由 UPnP 供应商按照 UPnP 服务模板以 XML 编写的。 UPnP 委员会制作了 UPnP 服务模板，作为标准化设备的一种方法。

通过适当的占位符规范，上面的清单可以是 UPnP 服务模板也可以是 UPnP 服务描述。回想一下，某些占位符将由 UPnP 论坛工作委员会（红色）定义，即 action 及其 arguments，status 及其 dataType， range 和 event characteristics 。如果将上面指定的这些实例化为代码，那么这就是一份 UPnP 服务模板， UPnP 服务模板是 UPnP 论坛工作委员会的主要交付成果之一。

更进一步，如果 UPnP 供应商（紫色）指定了上面列表中的其余占位符，即由供应商指定的其他 action 和 status variables。如果指定了这些占位符（以及其他占位符），则列表将是 UPnP 服务描述，适用于对设备内服务的有效控制。

换句话说，UPnP 服务模板定义了服务的整体类型，而 UPnP 服务描述则在模板的基础上包含了供应商的添加特定的特性。第一个由 UPnP 委员会创建；后者由 UPnP 供应商提供。

2.5 Description: Non-standard vendor extensions

如上所述，UPnP 供应商可以通过添加其他服务和嵌入式设备来区分其设备并扩展标准设备。同样，UPnP 供应商可以通过添加其他操作或状态变量来扩展标准服务。下表中列出了每种方法的命名约定，并在上面进行了详细说明。

如上表的最后两行所示， UPnP 供应商还可以将非标准 XML 添加到设备或服务描述中。每个添加项都必须由供应商的 XML namespace 限制。供应商添加的 XML 元素必须包含在以 X_ 开头的元素中，并且该元素必须是标准元素的子元素。可以将非标准属性添加到标准元素中，前提是这些属性的元素名称是 X_ 开头的。

为了说明这一点，下面列举了实际元素和值的占位符（斜体）。以及一些 UPnP 供应商指定（紫色）字段替换后的样例。和一些则由 UPnP 设备体系结构定义的样例（绿色）。

RootStandardElement Required | 一个标准的根元素. xmlns 属性定义了 namespaces。在这个案例中,描述了一个标准 UPnP namespace 和一个以 'n' 为前缀的非标 namespace。
- 注意对于设备的描述，这个描述必须存在 root 元素中。
- 注意对于设备的描述，这个描述必须存在 scpd 元素中。
AnyStandardElement
Required | 任何标准元素，无论是根元素还是其他元素，文本的内容或者元素的内容。必须作为标准设备或标准服务服务的一部分。 X_VendorAttribute 必须以 X_ 开头，后可以接任意字符串。（前缀 A_ 是保留的。）

EltOnlyStandardElement Required | Element with content of element only. Must already be included as part of the standard device or service description. 仅包含元素内容的元素。这些元素必须包含在标准设备或标准服务描述中。
- 对于设备的描述，必须是其中之一： root, specVersion, device, iconList, icon, serviceList, service, and/or deviceList.
- 对于服务的描述，必须是其中之一： scpd, actionList, action, argumentList, argument, serviceStateTable, stateVariable, allowedValueList, and/or allowedValueRange.
X_VendorElement
Required | 必须是以 'X_' 开头( 前缀 ‘A_’ 为保留字)。必须有 xmlns 属性. 可能还包括其他任意的 XML 内容。

如果控制点不理解自定义的一些标签，那么控制点应该忽略之。

2.6 Description: UPnP Template Language for devices

上面的段落解释了 UPnP 设备描述，并说明了如何从 UPnP 设备模板中实例化该描述。如前所述，UPnP 设备模板是由 UPnP 论坛工作委员会制作的，这些模板是从 UPnP 模板语言衍生而来的。该模板语言定义了设备和服务的有效模板。以下是与设备有关的该语言的清单和说明。

UPnP 模板语言是用 XML 语法编写的，并且派生自 XML Schema（第1部分：结构，第2部分：数据类型）。 XML 模式提供了一组 XML 的结构，这些结构表达（展示/阐述）了描述语言概念，例如必需元素与可选元素，元素嵌套和值的数据类型（以及此处不感兴趣的其他属性）。 UPnP 模板语言使用这些 XML 架构构造来定义元素，例如以上详细列出的 specVersion，URLBase，deviceType 等。因为 UPnP 模板语言是使用另一种精确的语言构造的，所以它是明确的。并且由于 UPnP 模板语言，UPnP 设备模板和 UPnP 设备描述都是机器可读的，因此自动化工具可以自动检查以确保后两个具有所有必需的元素，正确地嵌套并且具有正确的数据类型的值。

下面是由 UDA 定义的设备的 UPnP 模板。这些元素在 UPnP 设备模板中有介绍（这里和上面的解释都用绿色表示）; Below is where these elements are defined; above is where they are used.

紧随其后的是对使用的 XML Schema 元素，属性和值的简要说明。本节末尾的 XML Schema 参考有更多详细信息。

UPnP Template Language for devices

ElementType 用新的派生语言定义元素。 name 属性定义元素名称。 dt:type 属性使用新的派生语言为 element 的值定义数据类型。
element 使用嵌套的方式来引用元素。 minOccurs 属性定义元素必须出现的最小次数。默认值为 minOccurs = 1; 可选元素的 minOccurs =0。maxOccurs属性定义元素必须出现的最大次数。默认值为maxOccurs = 1; 可以出现一次或多次的元素具有 maxOccurs = *。 Content =“textOnly” 表示元素不包含子元素； content =“eltOnly”表示元素包含子元素。

2.7 Description: UPnP Template Language for services

本章节介绍服务描述是如何从 UPnP 服务模板中实例化到的。像设备模板一样，UPnP 的服务模板也是有 UPnP 委员会定义的每个操作都要实现一次。服务模板和设备模板也都是由 UPnP 模板语言衍生而来，像上面介绍的一样，UPnP 模板文档服从 XML 的语法格式（由 XML Schema 衍生而来），（这里主要产靠 Part1: struct 和 Part 2: DataTypes）。下面是一个 service 描述模板的例子，这里绿色代表涉及的内容对应上面提到的内容。下面定义的元素也揭示了他们的用法。

紧随其后的是对使用的 XML Schema 元素，属性和值的简要说明。本节末尾的 XML Schema 参考有更多详细信息。

UPnP Template Language for services

attribute 引用属性以声明该可能出现在哪些元素中。像任何 XML 元素一样，AttributeType 元素可以具有自己的属性。在此元素内使用 required 属性指示该属性是否必须存在；可选属性 required=no。
AttributeType 定义一个新的 AttributeType，像任何XML元素一样，AttributeType元素可以具有自己的属性。在此元素中使用 name 属性定义属性名称，因为它将在派生语言中使用。
element 使用嵌套的方式来引用元素。 minOccurs 属性定义元素必须出现的最小次数。默认值为 minOccurs = 1; 可选元素的 minOccurs =0。maxOccurs属性定义元素必须出现的最大次数。默认值为maxOccurs = 1; 可以出现一次或多次的元素具有 maxOccurs = *。 Content =“textOnly” 表示元素不包含子元素； content =“eltOnly”表示元素包含子元素。
ElementType 定义一个新的 element。 name 属性定义元素名称。dt：type 属性使用新的 element 的值定义数据类型。 model 定义此处是否有一个新的 elements, 属性指示新的派生语言中的元素是否可以包含此处未明确指定的元素；如果仅可以使用以前的特定元素，则 model=closed。 content 属性指示可能包含的内容；仅包含其他元素的元素具有 content = eltOnly; 仅包含字符串的元素的content = textOnly。
- group 将内容组织为一组以指定序列。 minOccurs 属性定义组必须出现的最小次数。 maxOccurs 属性定义组必须出现的最大次数。顺序属性限制元素的顺序；当最多允许一个元素时，order = one。

2.8 Description: Retrieving a description

如上所述，控制点发现设备后，仍然对设备知之甚少。要了解有关设备及其功能的更多信息，控制点必须使用设备在发现消息中提供的 URL 检索设备的 UPnP description(描述)。然后，控制点必须使用设备描述中提供的 URL 检索一个或多个服务描述。这是一个简单的基于 HTTP 的过程，并使用了整个 UPnP 协议堆栈的以下子集。（本文档开头列出了整个UPnP协议栈。）

在协议的最上层，描述消息包含特定于厂商的信息，例如，设备类型，服务类型和所需的服务。从协议栈向下移动，供应商内容将由 UPnP 论坛工作委员会提供的信息进行补充，例如型号名称，型号编号和特定的 URL。来自以上各层的消息以本文档中定义的特定于 UPnP 的协议托管。反过来，上述消息通过基于 IP/TCP 上的 HTTP 传递。作为参考，上面[方括号]中的颜色表示在下面列出的描述消息中哪个协议定义了特定的标头和主体元素。

使用此协议栈，检索UPnP设备描述非常简单：控制点向发现消息中的 URL 发出 HTTP GET 请求，并且设备在 HTTP 响应的正文中返回其描述。类似地，为了检索 UPnP 服务描述，控制点向设备描述中的 URL 发出 HTTP GET 请求，然后设备在 HTTP 响应的正文中返回该描述。响应和请求的标头和正文将在下面详细说明。

首先，控制点必须使用以下格式的GET方法发送请求。斜体部分需要填上实际的值

获取 description 的请求没有负载字段，但在请求头之后一定要有空行（即以 \r\n\r\n 结束）。

下面列出的是请求行的详细信息以及出现在上面列表中的标题。除非另有说明，否则所有标头值均区分大小写。

Request line
- GET HTTP GET Method
- path to description 获取 device 或者 service 的 description 的资源路径。device description 的 URL 在 discovery 响应的 LOCATION 字段中。 service description 的 URL 在 device description 的 SCPDURL 字段中。
- HTTP/1.1 HTTP 版本
headers
- HOST Required | 服务的域名或者 IP 地址（端口号可省略）， device description 的 URL 在 discovery 响应的 LOCATION 字段中。 service description 的 URL 在 device description 的 SCPDURL 字段中。如果端口号没有给出，则默认为 80 端口。
- ACCEPT-LANGUAGE 在获取设备描述的时候推荐添加此字段，该字段表示有限选择的语言，如果这个字段没有指定可用的语言，则返回的描述采用用默认语言。请参考（ RFC 1766 ）。

在 Control Point 发出获取描述的请求之后，设备需要马上响应 ControlPoint 请求，将 description 文档发给 ControlPoint。设备必须在合适的时间（一定要小于 30s）响应该请求。如果在这个时间内响应失败了，那么 ControlPoint 必须马上重新发送一个请求。设备必须以以下的格式返回响应信息。（斜线部分应该替换成具体的值）

这个响应的负载部即是设备或者服务的描述部分。在上面的几个小节中阐述了。

下面将会介绍请求头字段部分，所有的值都是大小写敏感的。

headers
- CONTENT-LANGUAGE 如果请求的头字段中有 ACCEPT-LANGUAGE 字段则必须存在该字段。否则应该遵从 RFC 1766 中对语言格式的要求。
- CONTENT-LENGTH Required | 负载的总长度 | 整形
- CONTENT-TYPE Required | 该处的值必须为 text/xml
- DATE Recommended | 该处记录响应生成是的时间，格式遵从 RFC 2616 中定义的 “rfc1123-date” 格式
- SERVER 关于请求 description 的响应，不需要此头字段。（我不知道为什么要存在此说明，莫名其妙）

请注意，由于HTTP 1.1允许使用分块编码，因此，如果GET请求指定HTTP 1.1，则某些设备可能会使用分块编码发送描述。因此，建议所有在GET请求中包含HTTP 1.1的实现都支持接收分块编码。 Note that because HTTP 1.1 allows use of chunked encoding, some devices may send the description using chunked encoding if the GET request specifies HTTP 1.1. It is therefore recommended that all implementations that include HTTP 1.1 in the GET request support receiving chunked encoding.

2.9 Description references>

ISO 8601 ISO (International Organization for Standardization). Representations of dates and times, 1988-06-15. 传送门
RFC 822 Standard for the format of ARPA Internet text messages. 传送门
RFC 1123 Includes format for dates, for, e.g., HTTP DATE header 传送门
RFC 1766 Format for language tag for, e.g., HTTP ACCEPT-LANGUAGE header. 传送门 See also for language codes 传送门.
RFC 2045 Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies. 传送门
RFC 2046 Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types. 传送门
RFC 2083 PNG (Portable Network Graphics) Specification Version 1.0 传送门和传送门
RFC 2387 Format for representing content type, e.g., mimetype element for an icon. 传送门
RFC 2396 Uniform Resource Identifiers: Generic Syntax. 传送门
RFC 2616 HTTP: Hypertext Transfer Protocol 1.1. 传送门
UPC Universal Product Code. 12-digit, all-numeric code that identifies the consumer package. Managed by the Uniform Code Council. 传送门
XML Extensible Markup Language. 传送门
XML Schema (Part 1: Structures, Part 2: Datatypes) Grammar defining UPnP Template Language. 传送门

3. Control

UPnP™ networking 的第三步就是 Control。该步骤在 addressing, discovery, description 之后，但是该步骤与第四步（eventing）是独立的。通过控制，控制点通过调用设备描述中的 action 并附带参数来控制。 Control 和 Eventing 是 presentation 的延伸。

给定一个设备和该设备服务的信息，控制点可以向该设备发起请求调用服务的 action，并接受服务执行动作的响应。调用的方式是通过 RPC 的方式实现的，控制点向服务点发送请求控制数据，服务点接收控制命令，并且返回成功或者失败的结果给控制点

如何控制设备？在设备的 description 中有个 controlURL 元素，该元素的值即为服务器地址，控制点向这个地址发送合适的请求，即可实现对设备的控制。控制点的动作会最终影响设备的运行时状态。当这些状态改变，设备应该将这些状态发送给感兴趣（之前订阅过）的控制点。这个章节将会介绍发起控制的消息格式，响应格式。 Eventing 章节将会介绍 event 相关的信息。

委员会和供应商会定义一些 actions 的状态, 以允许控制点确定设备的当前值的动作。与 action 的调用类似，控制点需要发送一个定义好的请求。服务收到该请求之后，服务需要将请求的状态变量，以及变量的值返回给控制点。每个服务需要负责保持其状态表的一致性，以便控制点在轮询时查到的值是有意义的。事件部分介绍了变量值的自动通知。

只要设备 discovery 时广播的消息没有过期，那么控制点即可认为广播的服务是可用的。如果设备取消了广播，控制点必须认定之前广播的设备和服务不可用了。

UPnP 的控制消息和响应的负载应该是 UTF-8 编码的。

尽管 UDA 确实定义了一套方法来调用动作并轮询值，但 UDA 并未指定或约束针对在控制点上运行的应用程序的 API 设计；操作系统供应商可以创建适合其客户需求的API。

如果有很大的一部分数据需要随 action 一起传输（特别是事先不知道数据的大小），则不建议将数据作为 SOAP 参数的一部分或者作为 MIME 附件发送，相反的应该采用 out-of-band 的方式传输。例如，你可以在 argument 中包含一个 URL。控制点可以通过该 URL 去GET / PUT /POST 获取目标数据。如果事先不知道数据量，则可以使用 HTTP chunked encoding。

在接下来的章节将对 Control Msg 的格式进行详细解释。

3.1 Control: Protocols

为了执行动作或者获取状态，控制点需要用到下面的这个 UPNP 协议栈。（ UPnP 的完整协议栈在本文档开头有说明）

在协议栈最上层，控制信息包含了供应商（vendor）的一些信息（比如：参数值）。接下来供应商的 Content 由 UPnP 委员会补充（如：action 的名字，argument 的名字，variable 的名字）。以上各层的消息都由 UPnP-specific protocols 承载，协议定义在本文档中。因此，上述消息使用简单对象访问协议（SOAP）标头和主体元素进行格式化，并且这些消息是通过基于 IP/TCP 上的 HTTP 传递。作为参考，上面[方括号]中的颜色表示在下面列出的订阅消息中哪个协议定义了特定的标头元素。

3.2 Control: Action

控制点调用服务 action, 服务返回操作结果或者错误，都采用 SOAP 封包的形式进行通信（传输协议是 HTTP ）。

3.2.1 Control: Action: Invoke

简单对象访问协议（SOAP）定义了利用 XML 和 HTTP 实现远程过程调用的一组规范。 UDA 使用 SOAP 将控制消息传递到设备，并将结果或错误返回给控制点。

SOAP 定义了其他 HTTP 标头，并且为了确保它们不会与其他 HTTP 扩展名混淆， SOAP 遵循 HTTP 扩展框架（RFC 2774），并在 MAN 标头中指定 SOAP 唯一 URI，并以 M- 作为 HTTP 方法的前缀。在这里，方法为 M-POST。使用 M-POST 要求 HTTP 服务器查找和理解 SOAP 唯一 URI 和特定于 SOAP 的标头。

为了向防火墙和代理提供更大的管理灵活性，SOAP 指定必须首先尝试不使用 MAN 头或 M- 前缀的请求。如果请求的响应为 “405不允许的方法” 而被拒绝，则必须使用 MAN 头和 M 前缀发送第二个请求。如果该请求以 “未实现501” 或 “未扩展510” 的响应被拒绝，则该请求将失败。（其他HTTP响应应根据HTTP规范进行处理。）

下面是使用 POST 方法发送的控制消息的列表（不带 MAN 头），后面是头和主体的说明。紧随其后的是使用 M-POST 方法和 MAN 标头发送的控制消息列表。

要调用设备服务上的操作，控制点必须使用以下格式的POST方法发送请求。斜体值是实际值的占位符。

下面列出的是上面列表中出现的请求行，标题和正文元素的详细说明。所有标头值和元素名称均区分大小写，值不区分大小写，除非另有说明。元素的顺序无关紧要，除非另有说明。必需元素必须仅出现一次（没有重复），推荐或可选元素最多只能出现一次，除非另有说明。

Request line
- POST HTTP method.
- path control url 组件 URL 路径，用于控制此服务（设备描述的 service 元素的 controlURL 子元素）。| single URL
- HTTP/1.1 HTTP/1.1 版本。
headers
- HOST Required | URL 的域名或 IP 地址以及用于控制此服务的 URL 的可选端口组件（设备描述的 service 元素的 controlURL 子元素）。如果端口为空或未指定，则假定端口为 80。
- ACCEPT-LANGUAGE (该控制消息无 ACCEPT-LANGUAGE 头)
- CONTENT-LENGTH Required | Body 的大小，单位字节 | Integer
- CONTENT-TYPE Required | 必须为 text/xml，之名 Body 采用的字符编码，这里必须为 “uft-8”。
- MAN （POST 请求方法无 MAN 头）
- SOAPACTION Required header defined by SOAP. Must be the service type, hash mark, and name of action to be invoked, all enclosed in double quotes. If used in a request with method M-POST, header name must be qualified with HTTP name space defined in MAN header. Single URI. The specified service version MUST indicate the version of the service that the control point wants to use while invoking the action. Its value may be any version of the service type in which the specified action was defined.
body
- Envelope Required element defined by SOAP. xmlns namespace attribute must be "http://schemas.xmlsoap.org/soap/envelope/". Must include encodingStyle attribute with value "http://schemas.xmlsoap.org/soap/encoding/". Contains the following sub elements:
  - Body Required element defined by SOAP. Should be qualified with SOAP namespace. Contains the following sub element:
    - actionName Required. Name of element is name of action to invoke. xmlns namespace attribute must be the service type enclosed in double quotes; the version specified must be the same version specified in the SOAPACTION header. Case sensitive. Must be the first sub element of Body. Contains the following, ordered sub element(s):
      - argumentName Required if and only if action has in arguments. Value to be passed to action. Repeat once for each in argument. (Element name not qualified by a namespace; element nesting context is sufficient.) Case sensitive. Single data type as defined by UPnP service description. Every “in” argument in the definition of the action in the service description must be included, in the same order as specified in the service description (SCPD) that was downloaded from the device.

If the CONTENT-TYPE header specifies an unsupported value (other then “text/xml”) the device must return an HTTP status code “415 Unsupported Media Type”.

Devices and control points shall ignore any XML comments or XML processing instructions they may receive that they do not understand.

XML namespace prefixes do not have to be the specific examples given above (e.g., “s” or “u”); they can be any value that obeys the rules of the general XML namespace mechanism; devices must accept requests that use other legal XML namespace prefixes.

If an action has no “in” arguments, it is valid to combine the opening and closing XML tags (e.g., “” instead of “”).

When the value of any argument contains one or more characters reserved as markup (such as ampersand (“&”) or less than (“<”)), the text must be escaped in accordance with the provisions of section 2.4 of the XML specification and each such character replaced with the equivalent numeric representation or string (such as “&” or “<”). Such characters appearing in URLs may also be escaped in accordance with the URL escaping rules specified in Section 2.4 of RFC 2396.

Note that because HTTP 1.1 allows use of chunked encoding, some control points may send the action request using chunked encoding if the POST method header specifies HTTP 1.1. Device implementations that do not support receiving action requests using chunked encoding should return a 505 HTTP Version Not Supported error.

If a request with POST is rejected with a response of "405 Method Not Allowed", then a control point must send a second request with method M-POST and MAN in the following format. Values in italics are placeholders for actual values.

(Message body for request with method M-POST is the same as body for request with method POST. See above.)

Request Line
- M-POST Method defined by HTTP Extension Framework (RFC 2774)
- pasth or control URL Path component of URL for control for this service (controlURL sub element of service element of device description). Single, relative URL.
- HTTP/1.1 HTTP version
Headers
- HOST Required. Domain name or IP address and optional port components of URL for control for this service (controlURL sub element of service element of device description). If the port is empty or not given, port 80 is assumed
- ACCEPT-LANGUAGE (No ACCEPT-LANGUAGE header is used in control messages.)
- CONTENT-LENGTH Required. Length of body in bytes. Integer.
- CONTENT-TYPE Required. Must be text/xml. Should include character coding used, which must be “utf-8”.
- MAN Required. Must be "http://schemas.xmlsoap.org/soap/envelope/". ns directive defines namespace (e.g., 01) for other SOAP headers (e.g., SOAPACTION).
- SOAPACTION Required header defined by SOAP. Must be the service type, hash mark, and name of action to be invoked, all enclosed in double quotes. The specified service version MUST indicate the version of the service that the control point wants to use while invoking the action. Its value may be any version of the service type in which the specified action was defined. If used in a request with method M-POST, header name must be qualified with HTTP name space defined in MAN header. Single URI.

3.2.2 Control: Action: Response

The service must complete invoking the action and respond within 30 seconds, including expected transmission time (measured from the time the action message is transmitted until the time the associated response is received). Actions that take longer than this should be defined to return early and send an event when complete. If the service fails to respond within this time, what the control point should do is application-specific. The service must send a response in the following format. Values in italics are placeholders for actual values.

Listed below are details for the response line, headers, and body elements appearing in the listing above. All header values and element names are case sensitive; values are not case sensitive except where noted. Except where noted, the order of elements is insignificant. Except where noted, required elements must occur exactly once (no duplicates), and recommended or optional elements may occur at most once

Response line
- HTTP/1.1 HTTP version
- 200 OK HTTP success code
Headers
- CONTENT-LANGUAGE (No CONTENT-LANGUAGE header is used in control messages.)
- CONTENT-LENGTH Required. Length of body in bytes. Integer.
- CONTENT-TYPE Required. Must be text/xml. Should include character coding used, which must be “utf-8”.
- DATE Recommended. When response was generated. “rfc1123-date” as defined in RFC 2616.
- EXT Required. Confirms that the MAN header was understood. (Header only; no value.)
- SERVER Required. Concatenation of OS name, OS version, UPnP/1.0, product name, and product version. String. Must accurately reflect the version number of the UPnP Device Architecture supported by the device. Control points must be prepared to accept a higher minor version number (but the same major version number) than the control point itself implements. For example, control points implementing UDA version 1.0 will be able to interoperate with devices implementing UDA version 1.1.
Body
- Envelop Required element defined by SOAP. xmlns namespace attribute must be "http://schemas.xmlsoap.org/soap/envelope/". Must include encodingStyle attribute with value "http://schemas.xmlsoap.org/soap/encoding/". Contains the following sub elements:
  - Body Required element defined by SOAP. Should be qualified with SOAP namespace. Contains the following sub element:
    - actionNameResponse Required. Name of element is action name prepended to Response. xmlns namespace attribute must be service type enclosed in double quotes; the version specified must be the same version specified in the SOAPACTION header in the original invocation request. Case sensitive. Must be the first sub element of Body. Contains the following sub element:
      - argumentName Required if and only if action has out arguments. Value returned from action. Repeat once for each out argument. If action has an argument marked as retval, this argument must be the first element. (Element name not qualified by a namespace; element nesting context is sufficient.) Case sensitive. Single data type as defined by UPnP service description. Every “out” argument in the definition of the action in the service description must be included, in the same order as specified in the service description (SCPD) available from the device.

Control points and devices shall ignore any XML comments or XML processing instructions they may receive that they do not understand.

XML namespace prefixes do not have to be the specific examples given above (e.g., “s” or “u”); they can be any value that obeys the rules of the general XML namespace mechanism; control points must accept responses that use other legal XML namespace prefixes.

If an action has no “out” arguments, it is valid to combine the opening and closing XML tags (e.g., “” instead of “”)

If a control point uses an HTTP/1.0 binding on a SOAP request without setting the KeepAlive token, the Device MUST close the socket after responding. If a control point uses an HTTP/1.1 binding on a SOAP request, and sets the Connection: CLOSE token, the Device MUST close the socket after responding.

Note that because HTTP 1.1 allows use of chunked encoding, some devices may send the action response using chunked encoding if the POST request specifies HTTP 1.1. It is therefore recommended that all implementations that include HTTP 1.1 in the POST request support receiving chunked encoding.

If the service encounters an error while invoking the action sent by a control point, the service must send a response within 30 seconds, including expected transmission time. Out arguments must not be used to convey error information; out arguments must only be used to return data; error responses must be sent in the following format. Values in italics are placeholders for actual values.

Response line
- HTTP/1.1 HTTP version
- 500 Internal Server Error HTTP error code
Headers
- CONTENT-LANGUAGE (No CONTENT-LANGUAGE header is used in control messages.)
- CONTENT-LENGTH Required. Length of body in bytes. Integer.
- CONTENT-TYPE Required. Must be text/xml. Should include character coding used, which must be “utf-8”.
- DATE Recommended. When response was generated. “rfc1123-date” as defined in RFC 2616.
- EXT Required. Confirms that the MAN header was understood. (Header only; no value.)
- SERVER Required. Concatenation of OS name, OS version, UPnP/1.0, product name, and product version. String. Must accurately reflect the version number of the UPnP Device Architecture supported by the device. Control points must be prepared to accept a higher version number than the control point itself implements. For example, control points implementing UDA version 1.0 will be able to interoperate with devices implementing UDA version 1.1.
Body
- Envelope Required element defined by SOAP. xmlns namespace attribute must be "http://schemas.xmlsoap.org/soap/envelope/". Must include encodingStyle attribute with value "http://schemas.xmlsoap.org/soap/encoding/". Contains the following sub elements:
  - Strong Required element defined by SOAP. Should be qualified with SOAP namespace. Contains the following sub element:
  - Fault Required element defined by SOAP. Error encountered while invoking action. Should be qualified with SOAP namespace. Contains the following sub elements:
    - faultCode Required element defined by SOAP. Value must be qualified with the SOAP namespace. Must be Client.
    - faultstring Required element defined by SOAP. Must be UPnPError.
    - detail Required element defined by SOAP. Contains the following subelement:
      - UPnPError Required element defined by UDA. Contains the following subelements:
        
        errorCode Required element defined by UDA. Code identifying what error was encountered. See table immediately below for values. Integer.
        
        errorDescription Recommended element defined by UDA. Short description. See table immediately below for recommended values; other values may be used by vendors. Human-readable string. Recommend < 256 characters.

The following table summarizes defined error types and the corresponding value for the errorCode and errorDescription elements.

3.3 Control: Query for variable

The QueryStateVariable action has been deprecated by the UPnP Forum and should not be used by control points except in limited testing scenarios due to inconsistent results. Working committees and vendors should explicitly define actions for querying of state variables for which this capability is desired. Such explicit query actions may include multiple state variables, if desired. The following definition of QueryStateVariable is retained in the UPnP Device architecture for reference and for backward compatibility with early implementations.

In addition to invoking actions on a device's service, control points may also poll the service for the value of a state variable by sending a query message. A query message may query only one state variable; multiple query messages must be sent to query multiple state variables.

This query message is decoupled from the service's eventing (if any). If a variable is moderated, then querying for the value of the variable will generally yield more up-to-date values than those received via eventing. The section on Eventing describes event moderation.

3.3.1 Control: Query: Invoke

To query for the value of a state variable, a control point must send a request in the following format. Values in italics are placeholders for actual values.

Listed below are details for the request line, headers, and body elements appearing in the listing above. All header values and element names are case sensitive; values are not case sensitive except where noted. Except where noted, the order of elements is insignificant. Except where noted, required elements must occur exactly once (no duplicates), and recommended or optional elements may occur at most once.

Request line
- POST Method defined by HTTP.
- path of control URL Path component of URL for control for this service (controlURL sub element of service element of device description). Single, relative URL.
- HTTP/1.1 HTTP version.
Headers
- HOST Required. Domain name or IP address and optional port components of URL for control for this service (controlURL sub element of service element of device description). If the port is empty or not given, port 80 is assumed.
- ACCEPT-LANGUAGE (No ACCEPT-LANGUAGE header is used in control messages.)
- CONTENT-LENGTH Required. Length of body in bytes. Integer
- CONTENT-TYPE Required. Must be text/xml. Should include character coding used, e.g., utf-8.
- MAN (No MAN header in request with method POST.)
- SOAPACTION Required header defined by SOAP. Must be "urn:schemas-upnp-org:control-1-0#QueryStateVariable". If used in a request with method M-POST, header name must be qualified with HTTP name space defined in MAN header. Single URI
Body
- Envelop Required element defined by SOAP. xmlns namespace attribute must be "http://schemas.xmlsoap.org/soap/envelope/". Must include encodingStyle attribute with value "http://schemas.xmlsoap.org/soap/encoding/". Contains the following sub elements:
  - Body Required element defined by SOAP. Should be qualified with SOAP namespace. Contains the following sub element:
    - QueryStateVariable Required element defined by UPnP. Action name. xmlns namespace attribute must be "urn:schemas-upnp-org:control-1-0". Must be the first sub element of Body. Contains the following, ordered sub element:
      - varName Required element defined by UPnP. Variable name. Must be qualified by QueryStateVariable namespace. Values is name of state variable to be queried. String.

For future extensibility, when processing XML like the listing above, as specified by the Flexible XML Processing Profile (FXPP), devices and control points must ignore: (a) any unknown elements and their sub elements or content, and (b) any unknown attributes and their values.

If a request with POST is rejected with a response of "405 Method Not Allowed", then a control point must send a second request with method M-POST and MAN as explained above

3.3.2 Control: Query: Response

To answer a query for the value of a state variable, the service must respond within 30 seconds, including expected transmission time. If the service fails to respond within this time, what the control point should do is application-specific. The service must send a response in the following format. Values in italics are placeholders for actual values.

Response line
- HTTP/1.1 HTTP version.
- 200 OK HTTP success code.
Headers
- CONTENT-LANGUAGE (No CONTENT-LANGUAGE header is used in control messages.)
- CONTENT-LENGTH Required. Length of body in bytes. Integer.
- CONTENT-TYPE Required. Must be text/xml. Should include character coding used, e.g., utf-8
- DATE Recommended. When response was generated. “rfc1123-date” as defined in RFC 2616.
- EXT Required. Confirms that the MAN header was understood. (Header only; no value.)
- SERVER Required. Concatenation of OS name, OS version, UPnP/1.0, product name, and product version. String.
Body
- Envelop Required element defined by SOAP. xmlns namespace attribute must be "http://schemas.xmlsoap.org/soap/envelope/". Must include encodingStyle attribute with value "http://schemas.xmlsoap.org/soap/encoding/". Contains the following sub elements:
  - Body Required element defined by SOAP. Should be qualified with SOAP namespace. Contains the following sub element:
    - QueryStateVariableResponse Required element defined by UPnP and SOAP. xmlns namespace attribute must be "urn:schemasupnp-org:control-1-0". Must be the first sub element of Body. Contains the following sub element:
      - return Required element defined by UPnP. (Element name not qualified by a namespace; element nesting context is sufficient.) Value is current value of the state variable specified in varName element in request.

When the value of any variable contains one or more characters reserved as markup (such as ampersand (“&”) or less than (“<”)), the text must be escaped in accordance with the provisions of section 2.4 of the XML specification and each such character replaced with the equivalent numeric representation or string (such as “&” or “<”). Such characters appearing in URLs may also be escaped in accordance with the URL escaping rules specified in Section 2.4 of RFC 2396.

If the service cannot provide a value for the variable, then the service must send a response within 30 seconds, including expected transmission time. The response must be sent in the following format. Values in italics are placeholders for actual values.

Response line
- HTTP/1.1 HTTP version.
- 500 Internal Server Error HTTP error code.
Headers
- CONTENT-LANGUAGE (No CONTENT-LANGUAGE header is used in control messages.)
- CONTENT-LENGTH Required. Length of body in bytes. Integer.
- CONTENT-TYPE Required. Must be text/xml. Should include character coding used, e.g., utf-8.
- DATE Recommended. When response was generated. “rfc1123-date” as defined in RFC 2616.
- EXT Required. Confirms that the MAN header was understood. (Header only; no value.)
- SERVER Required. Concatenation of OS name, OS version, UPnP/1.0, product name, and product version. String. Must accurately reflect the version number of the UPnP Device Architecture supported by the device. Control points must be prepared to accept a higher version number than the control point itself implements. For example, control points implementing UDA version 1.0 will be able to interoperate with devices implementing UDA version 1.1.
Body
- Envelope Required element defined by SOAP. xmlns namespace attribute must be "http://schemas.xmlsoap.org/soap/envelope/". Must include encodingStyle attribute with value "http://schemas.xmlsoap.org/soap/encoding/". Contains the following sub elements:
  - Body Required element defined by SOAP. Should be qualified with SOAP namespace. Contains the following sub element:
    - Fault Required element defined by SOAP. Why the service did not return a value for the variable. Should be qualified with SOAP namespace. Contains the following sub elements:
      - faultcode Required element defined by SOAP. Value should be qualified with SOAP namespace. Must be Client.
      - faultstring Required element defined by SOAP. Generic UPnP string describing errorCode. See table immediately below for values.
      - detail Required element defined by SOAP. Contains the following sub elements:
        
        UPnPError Required element defined by UPnP. Contains the following sub elements:
        
        errorCode Required element defined by UPnP. Code identifying what error was encountered. See table immediately below for values. Integer.
        
        errorDescription Recommended element defined by UPnP. Short description. See table immediately below for values. String. Recommend < 256 characters.

The following table summarizes defined error types and the corresponding value for the errorCode and errorDescription elements.

The device shall return the error code 401 Invalid Action if the QueryStateVariable action is not implemented.

For future extensibility, devices and control points must ignore (a) any unknown elements and their sub elements or content, and (b) any unknown attributes and their values.

3.4 Control references

RFC 1123 Includes format for dates, for, e.g., HTTP DATE header. 传送门
RFC 2396 Uniform Resource Identifiers: Generic Syntax 传送门
RFC 2616 HTTP: Hypertext Transfer Protocol 1.1 传送门
RFC 2774 HTTP Extension Framework. 传送门
SOAP Simple Object Access Protocol. 传送门
XML Extensible Markup Language. 传送门

4. Eventing

Eventing is Step 4 in UPnP™ networking. Eventing comes after addressing (Step 0) where devices get a network address, after discovery (Step 1) where control points find interesting device(s), and after description (Step 2) where control points learn about device capabilities. Eventing is intimately linked with control (Step 3) where control points send actions to devices. Through eventing, control points listen to state changes in device(s). Control and eventing are complementary to presentation (Step 5) where control points display a user interface provided by device(s).

After a control point has (1) discovered a device and (2) retrieved a description of the device and its services, the control point has the essentials for eventing. As the section on Description explains, a UPnP service description includes a list of actions the service responds to and a list of variables that model the state of the service at run time. If one or more of these state variables are evented, then the service publishes updates when these variables change, and a control point may subscribe to receive this information. Throughout this section, publisher refers to the source of the events (typically a device's service), and subscriber refers to the destination of events (typically a control point).

To subscribe to eventing, a subscriber sends a subscription message. If the subscription is accepted, the publisher responds with a duration for the subscription. To keep the subscription active, a subscriber must renew its subscription before the subscription expires. When a subscriber no longer needs eventing from a publisher, the subscriber should cancel its subscription. This section explains subscription, renewal, and cancellation messages in detail below.

The publisher notes changes to state variables by sending event messages. Event messages contain the names of one of more state variables and the current value of those variables, expressed in XML. A special initial event message is sent when a subscriber first subscribes; this event message contains the names and values for all evented variables and allows the subscriber to initialize its model of the state of the service. To support scenarios with multiple control points, eventing can be used to keep interested control points informed about the effects of actions performed by other control points or using other mechanisms for device control (such as front panel controls). All subscribers are sent all event messages, subscribers receive event messages for all evented variables (not just some), and event messages are sent no matter why the state variable changed (either in response to a requested action or because the state the service is modeling changed). This section explains the format of event messages in detail below.

Some state variables may change value too rapidly for eventing to be useful. One alternative is to filter, or moderate, the number of event messages sent due to changes in a variable's value. Some state variables may contain values too large for eventing to be useful; for this, or other reasons, a service may designate one or more state variables as non evented and never send event messages to subscribers. To determine the current value for such non-evented variables, control points must poll the service explicitly, presuming that an action is provided to obtain the value of the state variable. This section explains how variable eventing is described within a service description.

To send and receive subscription and event messages, control points and services use the following subset of the overall UPnP protocol stack. (The overall UPnP protocol stack is listed at the beginning of this document.)

At the highest layer, subscription and event messages contain vendor-specific information like URLs for subscription and duration of subscriptions or specific variable values. Moving down the stack, vendor content is supplemented by information from a UPnP Forum working committee, like service identifiers or variable names. Messages from the layers above are hosted in UPnP-specific protocols, defined in this document. In turn, the above messages are delivered via HTTP that has been extended using additional methods and headers. The HTTP messages are delivered via TCP over IP. For reference, colors in [square brackets] above indicate which protocol defines specific header elements in the subscription messages listed below.

The remainder of this section first explains subscription, including details of subscription messages, renewal messages, and cancellation messages. Second, it explains in detail how event messages are formatted and sent to control points, and the initial event message. Finally, it explains the UPnP Template Language as it pertains to eventing.

4.1 Eventing: Subscription

A service has eventing if and only if one or more of the state variables are evented.

If a service has eventing, it publishes event messages to interested subscribers. The publisher maintains a list of subscribers, keeping for each subscriber the following information

unique subscription identifier Required. Must be unique over the lifetime of the subscription, however long or short that may be. Generated by publisher in response to subscription message. Recommend universally-unique identifiers to ensure uniqueness. Single URI
delivery URL for event messages Required. Provided by subscriber in subscription message. Single URL
event key y Required. Key is 0 for initial event message. Key must be sequentially numbered for each subsequent event message; subscribers can verify that no event messages have been lost if the subscriber has received sequentially numbered event keys. Must wrap from 4294967295 to 1 (32-bit unsigned decimal integer). Some implementations may include leading “0” characters in the event key, which should be ignored.
subscription duration Required. Amount of time, or duration until subscription expires. Single integer or keyword “infinite”.

The publisher should accept as many subscriptions as it can reasonably maintain and deliver.

The publisher may wish to persist subscriptions across power failures. While control points can recover from complete network failure, if the problem is brief and localized to the device, reusing stored subscriptions may speed recovery.

The list of subscribers is updated via subscription, renewal, and cancellation messages explained immediately below and event messages explained later in this section.

To subscribe to eventing for a service, a subscriber sends a subscription message containing a URL for the publisher, a service identifier for the publisher, and a delivery URL for event messages. The subscription message may also include a requested duration for the subscription. The URL and service identifier for the publisher come from a description message. As the section on Description explains, a description message contains a device description. A device description contains (among other things), for each service, an eventing URL (in the eventSubURL element) and a service identifier (in the serviceId element); these correspond to the URL and service identifier for the publisher, respectively. The URL for the publisher must be unique to a particular service within this device.

The subscription message is a request to receive all event messages. No mechanism is provided to subscribe to event messages on a variable-by-variable basis. A subscriber is sent all event messages from the service. This is one factor to be considered when designing a service.

If the subscription is accepted, the publisher responds with a unique identifier for this subscription and a duration for this subscription. A duration should be chosen that matches assumptions about how frequently control points are removed from the network; if control points are removed every few minutes, then the duration should be similarly short, allowing a publisher to rapidly deprecate any expired subscribers; if control points are expected to be semi-permanent, then the duration should be very long, minimizing the processing and traffic associated with renewing subscriptions.

As soon as possible after the subscription is accepted, the publisher also sends the first, or initial event message to the subscriber. This message includes the names and current values for all evented variables. (The data type and range for each variable is described in a service description. The section on Description explains this in more detail.) This initial event message is always sent, even if the control point unsubscribes before it is delivered. The device must insure that the control point has received the response to the subscription request before sending the initial event message, to insure that the control point has received the SID (subscription ID) and can thereby correlate the event message to the subscription.

To keep the subscription active, a subscriber must renew its subscription before the subscription expires by sending a renewal message. The renewal message is send to the same URL as the subscription message, but the renewal message does not include a delivery URL for event messages; instead the renewal message includes the subscription identifier. The response for a renewal message is the same as one for a subscription message.

If a subscription expires, the subscription identifier becomes invalid, and the publisher stops sending event messages to the subscriber and can clean up its list of subscribers. If the subscriber tries to send any message other than a subscription message, the publisher will reject the message because the subscription identifier is invalid.

When a subscriber no longer needs eventing from a particular service, the subscriber should cancel its subscription. Canceling a subscription generally reduces service, control point, and network load. If a subscriber is removed abruptly from the network, it might be impossible to send a cancellation message. As a fallback, the subscription will eventually expire on its own unless renewed.

Subscribers should monitor discovery messages from the publisher. If the publisher cancels its advertisements, subscribers should assume that their subscriptions have been effectively cancelled.

Below is an explanation of the specific format of requests, responses, and errors for subscription, renewal, and cancellation messages.

4.1.1 Eventing: Subscribing: SUBSCRIBE with NT and CALLBACK

For each service in a device, a description message contains an eventing URL (eventSubURL sub element of service element in the device description) and the UPnP service identifier (serviceId sub element in service element in device description). To subscribe to eventing for a particular service, a subscription message is sent to that service's eventing URL. (Note that the eventing URL may be relative to the base URL.) The message contains that service's identifier as well as a delivery URL for event messages. A subscription message may also include a requested subscription duration.

To subscribe to eventing for a service, a subscriber must send a request with method SUBSCRIBE and NT and CALLBACK headers in the following format. Values in italics are placeholders for actual values.

(No body for request with method SUBSCRIBE, but note that the message must have a blank line following the last HTTP header.)

Listed below are details for the request line and headers appearing in the listing above. All header values are case sensitive except where noted.

Request line
- SUBSCRIBE Method to initiate or renew a subscription.
- publisher path Path component of eventing URL (eventSubURL sub element in service element in device description). Single, relative URL.
- HTTP/1.1 HTTP version
Headers
- HOST Required. Domain name or IP address and optional port components of eventing URL (eventSubURL sub element in service element in device description). If the port is missing or empty, port 80 is assumed.
- CALLBACK Required. Location to send event messages to. Defined by UPnP vendor. If there is more than one URL, when the service sends events, it will try these URLs in order until one succeeds. One or more URLs each enclosed by angle brackets (“<” and “>”). Each URL shall be an HTTP over TCP URL (prefixed by “http://”). The device shall not truncate this URL in any way; if insufficient memory is available to store the entire CALLBACK URL, the device must reject the subscription.
- NT Required. Notification Type. Must be upnp:event.
- SID (No SID header is used to subscribe.)
- TIMEOUT Recommended. Requested duration until subscription expires, either number of seconds or infinite. Recommendation by a UPnP Forum working committee. Defined by UPnP vendor. Consists of the keyword “Second-” followed (without an intervening space) by either an integer or the keyword “infinite”.

If there are enough resources to maintain the subscription, the publisher should accept it. To accept the subscription, the publisher assigns a unique identifier for the subscription, assigns a duration for the subscription, and sends an initial event message (explained in detail later in this section). To accept a subscription request, a publisher must send a response in the following format within 30 seconds, including expected transmission time. Values in italics are placeholders for actual values.

(No body for response to a request with method SUBSCRIBE, but note that the message must have a blank line following the last HTTP header.)

If the device sends the response over HTTP/1.0 without setting the KeepAlive token, or over HTTP/1.1 with the Connection: CLOSE header, the device MUST insure that the TCP FIN flag is sent BEFORE sending the initial event message. In all other cases, (unless the response is chunked), a Content-Length MUST be specified, (and set to 0), prior to sending the initial event.

Listed below are details for headers appearing in the listing above. All header values are case sensitive except where noted.

Headers
- DATE Recommended. When response was generated. “rfc1123-date” as defined in RFC 2616
- SERVER Required. Concatenation of OS name, OS version, UPnP/1.0, product name, and product version. String. Must accurately reflect the version number of the UPnP Device Architecture supported by the device. Control points must be prepared to accept a higher version number than the control point itself implements. For example, control points implementing UDA version 1.0 will be able to interoperate with devices implementing UDA version 1.1.
- SID Required. Subscription identifier. Must be universally unique. Must begin with uuid:. Defined by UPnP vendor. Single URI.
- TIMEOUT Required. Actual duration until subscription expires, either number of seconds or infinite. Recommendation by a UPnP Forum working committee. Defined by UPnP vendor. Should be greater than or equal to 1800 seconds (30 minutes). Keyword Second- followed by an integer (no space) or keyword infinite.

If a publisher cannot accept the subscription, or if there is an error with the subscription request, the publisher must send a response with one of the following errors. The response must be sent within 30 seconds, including expected transmission time.

Errors
- Incompatible headers 400 Bad Request. If SID header and one of NT or CALLBACK headers are present, the publisher must respond with HTTP error 400 Bad Request.
- Missing or invalid CALLBACK 412 Precondition Failed. If CALLBACK header is missing or does not contain a valid HTTP URL, the publisher must respond with HTTP error 412 Precondition Failed.
- Invalid NT 412 Precondition Failed. If NT header does not equal upnp:event, the publisher must respond with HTTP error 412 Precondition Failed.
- Unable to accept subscription 5xx. If a publisher is not able to accept a subscription (such as due to insufficient resources), it must respond with a HTTP 500-series error code.

Other errors may be returned by layers in the protocol stack below the UPnP protocols. Consult documentation on those protocols for details.

4.1.2 Eventing: Renewing a subscription: SUBSCRIBE with SID

To renew a subscription to eventing for a particular service, a renewal message is sent to that service's eventing URL. (Note that the eventing URL may be relative to the base URL.) However, unlike an initial subscription message, a renewal message does not contain either the service's identifier nor a delivery URL for event messages. Instead, the message contains the subscription identifier assigned by the publisher, providing an unambiguous reference to the subscription to be renewed. Like a subscription message, a renewal message may also include a requested subscription duration.

The renewal message uses the same method as the subscription message, but the two messages use a disjoint set of headers; renewal uses SID and subscription uses NT and CALLBACK. A message that includes SID and either of NT or CALLBACK headers is an error.

To renew a subscription to eventing for a service, a subscriber must send a request with method SUBSCRIBE and SID header in the following format. Values in italics are placeholders for actual values.

(No body for method with request SUBSCRIBE, but note that the message must have a blank line following the last HTTP header.)

Listed below are details for the request line and headers appearing in the listing above. All header values are case sensitive except where noted.

Request line
- SUBSCRIBE Method to initiate or renew a subscription
- publisher path Path component of eventing URL (eventSubURL sub element in service element in device description). Single, relative URL.
- HTTP/1.1 HTTP version
Headers
- HOST Required. Domain name or IP address and optional port components of eventing URL (eventSubURL sub element in service element in device description). If the port is missing or empty, port 80 is assumed.
- CALLBACK (No CALLBACK header is used to renew an event subscription.)
- NT (No NT header is used to renew an event subscription.)
- SID Required. Subscription identifier. Must be the subscription identifier assigned by publisher in response to subscription request. Must be universally unique. Must begin with uuid:. Defined by UPnP vendor. Single URI.
- TIMEOUT Recommended. Requested duration until subscription expires, either number of seconds or infinite. Recommendation by a UPnP Forum working committee. Defined by UPnP vendor. Keyword Second- followed by an integer (no space) or keyword infinite.

To accept a renewal, the publisher reassigns a duration for the subscription and must send a response in the same format and with the same conditions as a response to a request for a new subscription, except that the initial event message is not sent again.

If a publisher cannot accept the renewal, or if there is an error with the renewal request, the publisher must send a response with one of the following errors. The response must be sent within 30 seconds, including expected transmission time.

Errors
- Incompatible headers 400 Bad Request. If SID header and one of NT or CALLBACK headers are present, the publisher must respond with HTTP error 400 Bad Request.
- Invalid SID 412 Precondition Failed. If a SID does not correspond to a known, un-expired subscription, the publisher must respond with HTTP error 412 Precondition Failed.
- Missing SID 412 Precondition Failed. If the SID header is missing or empty, the publisher must respond with HTTP error 412 Precondition Failed.
- Unable to accept renewal 5xx. If the publisher is not able to accept a renewal, it must respond with a HTTP 500-series error code.

Other errors may be returned by layers in the protocol stack below the UPnP protocols. Consult documentation on those protocols for details.

4.1.3 Eventing: Canceling a subscription: UNSUBSCRIBE

When eventing is no longer needed from a particular service, a cancellation message should be sent to that service's eventing URL. (Note that the eventing URL may be relative to the base URL.) The message contains the subscription identifier. Canceling a subscription generally reduces service, control point, and network load. If a control point is removed abruptly from the network, it might be impossible to send a cancellation message. As a fallback, the subscription will eventually expire on its own unless renewed.

To cancel a subscription to eventing for a service, a subscriber should send a request with method UNSUBSCRIBE in the following format. Values in italics are placeholders for actual values.

(No body for request with method UNSUBSCRIBE, but note that the message must have a blank line following the last HTTP header.)

Listed below are details for the request line and headers appearing in the listing above. All header values are case sensitive except where noted.

Request line
- UNSUBSCRIBE Method to cancel a subscription.
- publisher path Path component of eventing URL (eventSubURL sub element in service element in device description). Single, relative URL.
- HTTP/1.1 HTTP version
Headers
- HOST Required. Domain name or IP address and optional port components of eventing URL (eventSubURL sub element in service element in device description). If the port is missing or empty, port 80 is assumed.
- CALLBACK (No CALLBACK header is used to cancel an event subscription.)
- NT (No NT header is used to cancel an event subscription.)
- SID Required. Subscription identifier. Must be the subscription identifier assigned by publisher in response to subscription request. Must be universally unique. Must begin with uuid:. Defined by UPnP vendor. Single URI.
- TIMEOUT (No TIMEOUT header is used to cancel an event subscription.)

To cancel a subscription, a publisher must send a response in the following format within 30 seconds, including expected transmission time.

                HTTP/1.1 200 OK

If there is an error with the cancellation request, the publisher must send a response with one of the following errors. The response must be sent within 30 seconds, including expected transmission time.

Errors
- Incompatible headers 400 Bad Request. If SID header and one of NT or CALLBACK headers are present, the publisher must respond with HTTP error 400 Bad Request.
- Invalid SID 412 Precondition Failed. If a SID does not correspond to a known, un-expired subscription, the publisher must respond with HTTP error 412 Precondition Failed.
- Missing SID 412 Precondition Failed. If the SID header is missing or empty, the publisher must respond with HTTP error 412 Precondition Failed.

Other errors may be returned by layers in the protocol stack below the UPnP protocols. Consult documentation on those protocols for details.

4.2 Eventing: Event messages

A service publishes changes to its state variables by sending event messages. These messages contain the names of one or more state variables and the current value of those variables. Event messages should be sent as soon as possible to get accurate information about the service to subscribers and allow subscribers to display a responsive user interface. If the value of more than one variable is changing at the same time, the publisher should bundle these changes into a single event message to reduce processing and network traffic.

As explained above, an initial event message is sent when a subscriber first subscribes; this event message contains the names and values for all evented variables and allows the subscriber to initialize its model of the state of the service. This message should be sent as soon as possible after the publisher accepts a subscription. This message should always be sent, even if the control point unsubscribes before the message is delivered.

Event messages are tagged with an event key. A separate event key must be maintained by the publisher for each subscription to facilitate error detection (as explained below). The event key for a subscription is initialized to 0 when the publisher sends the initial event message. For each subsequent event message, the publisher increments the event key for a subscription, and includes that updated key in the event message. Any implementation of event keys should handle overflow and wrap the event key from 4294967295 back to 1 (not 0). Subscribers must also handle this special case when the next event key is not an increment of the previous key. Should be implemented as a 4 Byte (32 bit) unsigned integer.

If there is no response from a subscriber to any event message, the publisher should continue to attempt to send subsequent event messages to the subscriber until the subscription expires.

To repair an event subscription, e.g., if a subscriber has missed one or more event messages, a subscriber must unsubscribe and re-subscribe. By doing so, the subscriber will get a new subscription identifier, a new initial event message, and a new event key.

All UPnP event messages shall be encoded using UTF-8.

4.2.1 Eventing: Event messages: NOTIFY

To send an event message, a publisher must send a request with method NOTIFY in the following format. Values in italics below are placeholders for actual values.

Listed below are details for the request line, headers, and body elements appearing in the listing above. All header values are case sensitive except where noted. All body elements and attributes are case sensitive; body values are not case sensitive except where noted. Except where noted, the order of elements is insignificant. Except where noted, required elements must occur exactly once (no duplicates), and recommended or optional elements may occur at most once. In particular, a single propertyset element shall not include more than one property element that specifies the same variableName element; separate event notification messages must be used.

Request line
- NOTIFY Method to notify client about event
- delivery path Path component of delivery URL (CALLBACK header in subscription message). Destination for event message. Single, relative URL. Must be one of the URLs contained in the CALLBACK header, without truncation or modification.
- HTTP/1.1 HTTP version.
Headers
- HOST Required. Domain name or IP address and optional port components of delivery URL (CALLBACK header in subscription message). If the port is missing or empty, port 80 is assumed.
- ACCEPT-LANGUAGE (No ACCEPT-LANGUAGE header is used in event messages.)
- CONTENT-LENGTH Required. Length of body in Bytes. Integer.
- CONTENT-TYPE Required. Must be text/xml.
- NT Required. Notification Type. Must be upnp:event.
- NTS Required. Notification Sub Type. Must be upnp:propchange.
- SID Required. Subscription identifier. Must be universally unique. Must begin with uuid:. Defined by UPnP vendor. Single URI.
- SEQ Required. Event key. Must be 0 for initial event message. Must be incremented by 1 for each event message sent to a particular subscriber. To prevent overflow, must be wrapped from 4294967295to 1. 32-bit unsigned value represented as a single decimal integer without leading zeroes (some implementations may include leading zeroes, which should be ignored by the recipient).
Body
- properyset Required. xmlns namespace attribute must be urn:schemas-upnp-org:event-1-0. Contains the following sub element
  - property Required. Repeat once for each variable name and value in the event message. Must be qualified by propertyset namespace. Contains the following sub element.
    - variableName Required. Element is name of a state variable that changed (name sub element of stateVariable element in service description). Must not be qualified with any namespace. Value is the new value for this state variable. Case sensitive. Single data type as specified by UPnP service description.

For future extensibility, when processing XML like the listing above, devices and control points must ignore: (a) any unknown elements and their sub elements or content, and (b) any unknown attributes and their values. Note that when subscribing to eventing with a service that is of a higher version than what is supported by the control point, event notifications may be sent by the service to the control point containing state variable names which are not recognized by the control point. The control point should discard and ignore such unrecognized state variables within event notification messages.

Control points and devices shall ignore any XML comments or XML processing instructions they may receive that they do not understand.

Note that because HTTP 1.1 allows use of chunked encoding, some devices may send the event notification using chunked encoding if the SUBSCRIBE request specified HTTP 1.1. It is therefore recommended that all implementations that include HTTP 1.1 in the SUBSCRIBE request support receiving chunked encoding.

To acknowledge receipt of this event message, a subscriber must respond within 30 seconds, including expected transmission time. If a subscriber does not respond within 30 seconds, or if the publisher is unable to connect to the subscription URL, the publisher should abandon sending this message to the subscriber but should keep the subscription active and send future event messages to the subscriber until the subscription expires or is cancelled. The subscriber must send a response in the following format.

            HTTP/1.1 200 OK

(No body for a request with method NOTIFY, but note that the message must have a blank line following the last HTTP header.)

If a device sends an event to a control point using HTTP/1.0 without the KeepAlive token, the Control Point MUST close the socket after responding. If a device sends an event to a control point using HTTP/1.1 and sets the Connection: CLOSE token, the Control Point MUST close the socket after responding.

If there is an error with the event message, the subscriber must respond with one of the following errors. The response must be sent within 30 seconds, including expected transmission time.

Errors
- MISS SID 412 Precondition Failed. If the SID header is missing or empty, the subscriber must respond with HTTP error 412 Precondition Failed.
- Invalid SID 412 Precondition Failed. If a SID does not correspond to a known subscription, the subscriber must respond with HTTP error 412 Precondition Failed. (Service must terminate this SID when it receives this error response.)
- Missing NT or NTS header 400 Bad Request. If the NT or NTS header is missing, the subscriber must respond with HTTP error 400 Bad Request.
- Invalid NT header 412 Precondition Failed. If NT header does not equal upnp:event, the subscriber must respond with HTTP error 412 Precondition Failed.
- Invalid NTS header 412 Precondition Failed. If NTS header does not equal upnp:propchange, the subscriber must respond with HTTP error 412 Precondition Failed.

Other errors may be returned by layers in the protocol stack below the UPnP protocols. Consult documentation on those protocols for details

4.3 Eventing: UPnP Template Language for eventing

The UPnP Template Language defines well-formed templates for devices and services. To a lesser extent, it also provides a template for the body of event messages. The section on Description explains the UPnP Template Language as it pertains to devices and services. As explained in that section, the UPnP Template Language is written in XML syntax and is derived from XML Schema (Part 1: Structures, Part 2: Datatypes). Below is a listing of this language as it pertains to eventing. The elements it defines are used in event messages; they are colored green here, and they are colored green in the listing above. Below is where these elements are defined (though it is a minimal definition); above is where they are used

Immediately following this is a brief explanation of the XML Schema elements, attributes, and values used. The reference to XML Schema at the end of this section has further details.

UPnP Template Language for eventing

element References an element for the purposes of declaring nesting. maxOccurs attribute defines maximum number of times the element must occur; default is maxOccurs = 1; elements that can appear one or more times have maxOccurs = *.
ElementType Defines an element in the new, derived language. name attribute defines element name. model attribute indicates whether elements in the new, derived language can contain elements not explicitly specified here; when only unspecified sub elements may be included, model=open. content attribute indicates what content may contain; elements that contain only other elements have content = eltOnly.

As explained in the section on Description, the UPnP Template Language for services also specifies a sendEvents attribute for a state variable. The default value for this attribute is yes. To denote that a state variable is evented, the value of this attribute is yes (or the attribute is omitted) in a service description; to denote that a state variable is non-evented, the value is no. Note that if all of a service's state variables are non-evented, the service has nothing to publish, and control points cannot subscribe and will not receive event messages from the service.

4.4 Eventing: Augmenting the UPnP Template Language

It is useful to augment the description of devices and services with annotations that are not captured in the UPnP Template Language. To a lesser extent, there is value in these annotations to capture event filtering, or moderation.

As explained above, some state variables may change value too rapidly for eventing to be useful. Below is a recommended vocabulary for UPnP Forum working committees or UPnP vendors to document moderation in the number of event messages sent due to changes in a variables value.

maximumRate = n Optional. State variable v will not be part of an event message more often than n seconds. If v is the only variable changing, then an event message will not be generated more often than every n seconds. If v ceases to change after an event message has been sent but before n seconds have transpired, an event message must be sent with the new value of v. Recommended for variables that model continuously changing properties. Single integer.
minimumDelta = n Optional. State variable v will not be part of an event message unless its value has changed by more than n * allowedValueRange step since the last time an event message was sent that included v, e.g., unless v has been incremented n times. (cf. INCREMENT, INCREMENT_BOUNDED, and INCREMENT_WRAP explained in the section on Control.) Only defined variables with number and real data type. Recommended for variables that model counters. Single integer.

The publisher can send out any changed moderated variable when an event goes out. The publisher should make its best attempt to meet moderation rules described above, but the publisher can flush recent changes when it sends out events.

Note that moderation affects events only and not state table updates. Specifically, control actions which return the value of state variables may return a more current value than published via eventing. Put another way, moderation means that not all state table changes result in events.

Decisions about which variables to event and any possible moderation is up to the appropriate UPnP Forum working committee (for standard services) or a UPnP vendor (for non-standard services).

4.5 Eventing references

RFC 2396 Uniform Resource Identifiers: Generic Syntax 传送门
RFC 2616 HTTP: Hypertext Transfer Protocol 1.1. 传送门
XML Extensible Markup Language. 传送门
XML Schema (Part 1: Structures, Part 2: Datatypes) Grammar defining UPnP Template Language. 传送门 / 传送门

5. Presentation

Presentation is Step 5 in UPnP™ networking. Presentation comes after addressing (Step 0) where devices get network addresses, after discovery (Step 1) where control points find interesting device(s), and after description (Step 2) where control points learn about device capabilities. Presentation exposes an HTML-based user interface for controlling and/or viewing device status. Presentation is complementary to control (Step 3) where control points send actions to devices, and eventing (Step 4) where control points listen to state changes in device(s).

After a control point has (1) discovered a device and (2) retrieved a description of the device, the control point is ready to begin presentation. If a device has a URL for presentation, then the control point can retrieve a page from this URL, load the page into a browser, and depending on the capabilities of the page, allow a user to control the device and/or view device status. The degree to which each of these can be accomplished depends on the specific capabilities of the presentation page and device.

The URL for presentation is contained within the presentationURL element in the device description. The device description is delivered via a description message. The section on Description explains the device description and description messages in detail.

Retrieving a presentation page is a simple HTTP-based process and uses the following subset of the overall UPnP protocol stack. (The overall UPnP protocol stack is listed at the beginning of this document.)

At the highest layer, the presentation page is specified by a UPnP vendor. Moving down the stack, the UPnP Device Architecture specifies that this page be written in HTML. The page is delivered via HTTP over TCP over IP. For reference, colors in [square brackets] are included for consistency with other sections in this document.

To retrieve a presentation page, the control point issues an HTTP GET request to the presentation URL, and the device returns a presentation page.

Unlike the UPnP Device and Service Templates, and standard device and service types, the capabilities of the presentation page are completely specified by the UPnP vendor. The presentation page is not under the auspices of a UPnP Forum working committee. The page must be an HTML page; it should be version HTML 3.0 or later. However, other design aspects are left to the vendor to specify. This includes, but is not limited to, all capabilities of the control point's browser, scripting language or browser plug-ins used, and means of interacting with the device. To implement a presentation page, a UPnP vendor may wish to use UPnP mechanisms for control and/or eventing, leveraging the device's existing capabilities but is not constrained to do so.

Presentation pages should use mechanisms provided by HTML for localization (e.g., META tag with charset attribute). Control points should use the ACCEPT-LANGUAGE and CONTENT-LANGUAGE feature of HTTP to try to retrieve a localized presentation page. Specifically, a control point may include a HTTP ACCEPT-LANGUAGE header in the request for a presentation page; if an ACCEPT-LANGUAGE header is present in the request, the response must include a CONTENT-LANGUAGE header to identify the page's language.

5.1 Presentation references

HTML HyperText Markup Language 传送门

我是留白；我是留白；我是留白；（重要的事情说三遍）

To Top

DLNA 粗解

你可能感兴趣的:(DLNA 粗解)