UPnP 事件触发 Eventing

Eventing is Step 4 in UPnP™ networking. Eventing comes afteraddressing (Step 0) where devices get a network address, afterdiscovery (Step 1) where control points find interesting device(s),and after description (Step 2) where control points learn aboutdevice capabilities. Eventing is intimately linked with control(Step 3) where control points send actions to devices.Througheventing, 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 bydevice(s).
控制和事件触发是展示的补充，展示是指控制点显示设备的用户接口。
After a control point has (1) discovered a device and (2) retrieveda description of the device and its services, the control point hasthe essentials for eventing. As the section on Descriptionexplains, a UPnP service description includes a list of actions theservice responds to and a list of variables that model the state ofthe service at run time. If one or more of these state variablesare evented, then the service publishes updates when thesevariables change, and a control point may subscribe to receive thisinformation. Throughout this section, publisher refers to thesource of the events (typically a device's service), and subscriberrefers to the destination of events (typically a controlpoint).
当控制点发现了设备并检索到了设备和服务的描述，控制点知道了如何去事件触发。描述那一章解释了服务描述包含了一系列服务对在服务运行是变量的动作。如果一个或者多个这些变量被触发，当变量变化时服务发布更新，控制点可以订阅来获得这些信息。通过这一章，发布者是指事件信息源（通常为设备），订阅者指的是事件的目的地（通常为控制点）


To subscribe to eventing, a subscriber sends a subscriptionmessage. If the subscription is accepted, the publisher respondswith a duration for the subscription. To keep the subscriptionactive, a subscriber must renew its subscription before thesubscription expires. When a subscriber no longer needs eventingfrom a publisher, the subscriber should cancel its subscription.This section explains subscription, renewal, and cancellationmessages in detail below.
为了订阅事件消息，订阅者发送订阅消息。如果订阅被接受，发送者在一段时间内对订阅作出响应。为了保持订阅的火星，订阅者必须在订阅过期之前重新订阅消息。当一个订阅者不在需要发布者的事件消息时，订阅者可以取消它的订阅。这一章详细解释订阅，更新，取消消息。
The publisher notes changes to state variables by sending eventmessages. Event messages contain the names of one of more statevariables and the current value of those variables, expressed inXML. A special initial event message is sent when a subscriberfirst subscribes; this event message contains the names and valuesfor all evented variables and allows the subscriber to initializeits model of the state of the service. To support scenarios withmultiple control points, eventing can be used to keep interestedcontrol points informed about the effects of actions performed byother control points or using other mechanisms for device control(such as front panel controls). All subscribers are sent all eventmessages, subscribers receive event messages for all eventedvariables (not just some), and event messages are sent no matterwhy the state variable changed (either in response to a requestedaction or because the state the service is modeling changed). Thissection explains the format of event messages in detailbelow.
发布者通过发布事件消息记录状态变量的变化。事件消息包含一个或多个状态变量的名称，当前值；使用xml表述。当订阅者第一次订阅时，一个特殊的初始事件消息将被发送；这个时间消息包含了所有事件变量的名称，允许订阅者初始化服务状态的模型。为了支持多个控制点情形，当其他控制点或使用其他设备控制机制操作设备动作后，事件触发可以被用来通知订阅者动作的结果。事件消息发送到所有订阅者，订阅者接收到时间消息的全部事件变量。不管因何原因而使状态变量改变，事件消息都将被发送。本章解释事件消息的详细格式。
Some state variables may change value too rapidly for eventing tobe useful. One alternative is to filter, or moderate, the number ofevent messages sent due to changes in a variable's value. Somestate variables may contain values too large for eventing to beuseful; for this, or other reasons, a service may designate one ormore state variables as non evented and never send event messagesto subscribers. To determine the current value for such non-eventedvariables, control points must poll the service explicitly,presuming that an action is provided to obtain the value of thestate variable. This section explains how variable eventing isdescribed within a service description.
有些状态变量的变化很快，不能用作事件触发。可以filter ormoderate因状态变量值改变而引起的事件消息的数量。有些状态变量太大，不能使用事件触发，对此，或其他原因，服务可以设定不触发或不发送事件消息给订阅者。来决定当前值为非触发的变量，控制点必须详细轮询服务，判定是否提供了统获得状态变量的值的动作。这一节解释变量事件如何使用服务描述进行描述。
To send and receive subscription and event messages, control pointsand services use the following subset of the overall UPnP protocolstack. (The overall UPnP protocol stack is listed at the beginningof this document.)


At the highest layer, subscription and event messages containvendor-specific information like URLs for subscription and durationof subscriptions or specific variable values. Moving down thestack, vendor content is supplemented by information from a UPnPForum working committee, like service identifiers or variablenames. Messages from the layers above are hosted in UPnP-specificprotocols, defined in this document. In turn, the above messagesare delivered via HTTP that has been extended using additionalmethods and headers. The HTTP messages are delivered via TCP overIP. For reference, colors in [square brackets] above indicate whichprotocol defines specific header elements in the subscriptionmessages listed below.The remainder of this section first explainssubscription, including details of subscription messages, renewalmessages, and
cancellation messages. Second, it explains in detail how eventmessages are formatted and sent to control points, and the initialevent message. Finally, it explains the UPnP Template Language asit pertains to eventing.

• 4.1 Eventing:Subscription

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

只有一个或多个状态变量被事件触发，服务才包含事件触发。

If a service has eventing, it publishes event messages tointerested subscribers. The publisher maintains a list ofsubscribers, keeping for each subscriber the followinginformation

如果服务由事件触发，它将发布事件消息给感兴趣的订阅者。发布者维护一个订阅者名单，上面保存了每个订阅者的如下信息。

unique subscriptionidentifier
Required. Must be unique over the lifetime of the subscription,however long or short that may be. Generated by publisher inresponse to subscription message. Recommend universally-uniqueidentifiers to ensure uniqueness. Single URI.

要求。订阅者的生命周期内，这个标示符必须是唯一的。作为发布者对订阅者消息的回应而生产。推荐使用UUID来保证其唯一性。单一URL
delivery URL for eventmessages
Required. Provided by subscriber in subscription message. SingleURL.

要求。订阅者在订阅消息中提供。单一URL
event key
Required. Key is 0 for initial event message. Key must besequentially numbered for each subsequent event message;subscribers can verify that no event messages have been lost if thesubscriber has received sequentially numbered event keys. Must wrapfrom 4294967295 to 1 (32-bit unsigned decimal integer). Someimplementations may include leading “0” characters in the eventkey, which should be ignored.

要求。对于初始事件消息，Key 是0.对于以后的每一个事件消息，Key必须是顺序号码。订阅者可以用来确定没有丢失事件消息。范围为4294967295 to 1(32位无符号十进制数)。一些实现可能会包含开始的 0 字符，这应该被忽略。

subscriptionduration
Required. Amount of time, or duration until subscription expires.Single integer or keyword “infinite”.

要求。时间长度，或者到过期前的持续时间。单一张数或者 关键字 infinite

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

发布者应该接收尽可能多的订阅，

The publisher may wish to persist subscriptions across powerfailures. While control points can recover from complete networkfailure, 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 eventmessages explained later in this section.

通过订阅，续约，取消消息，订阅者名单在更新，

To subscribe to eventing for a service, a subscriber sends asubscription message containing a URL for the publisher, a serviceidentifier for the publisher, and a delivery URL for eventmessages. The subscription message may also include a requestedduration for the subscription. The URL and service identifier forthe publisher come from a description message. As the section onDescription explains, a description message contains a devicedescription. A device description contains (among other things),for each service, an eventing URL (in the eventSubURL element) anda service identifier (in the serviceId element); these correspondto the URL and service identifier for the publisher, respectively.The URL for the publisher must be unique to a particular servicewithin this device.

为了订阅服务的事件，订阅者发送包含一个URL，服务标示符，和交付URL的订阅消息给发布者来获取事件消息。订阅消息可能还包含请求订阅的持续时间。URL和服务标示符包含在描述消息中。如描述 那一章所解释的，描述消息包括设备描述，设备描述包括对每个服务的 eventing URL(在eventSubURL元素中)和服务标示符（在serviceId元素中）。在一个设备中，特定服务的发布者的URL必须是唯一的。

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

订阅消息是对接受所有事件消息的请求。没有提供基于变量的事消息的订阅。订阅者接收所有来自服务的事件消息。这是一个再设计服务时要考虑的因素。

If the subscription is accepted, the publisher responds with aunique identifier for this subscription and a duration for thissubscription. A duration should be chosen that matches assumptionsabout how frequently control points are removed from the network;if control points are removed every few minutes, then the durationshould be similarly short, allowing a publisher to rapidlydeprecate any expired subscribers; if control points are expectedto be semi-permanent, then the duration should be very long,minimizing the processing and traffic associated with renewingsubscriptions.

如果订阅被接受，发布者用一个唯一标示符和持续时间响应这个订阅，持续时间应该选取符合对控制点何时离开网络的推算。如果控制点几分钟之内就离开，持续时间可以相对短些，允许发布者很快移除任何过期的订阅者。如果控制点希望半永久性，那持续时间可以非常长，以减少延长订阅的处理流量。

As soon as possible after the subscription is accepted, thepublisher also sends the first, or initial event message to thesubscriber. This message includes the names and current values forall evented variables. (The data type and range for each variableis described in a service description. The section on Descriptionexplains this in more detail.) This initial event message is alwayssent, even if the control point unsubscribes before it isdelivered. The device must insure that the control point hasreceived the response to the subscription request before sendingthe initial event message, to insure that the control point hasreceived the SID (subscription ID) and can thereby correlate theevent message to the subscription.

一旦订阅被接受，发布者任然要发送第一个，或者初始事件消息给订阅者。这个消息包含当前事件变量的名字和值。即使控制点在这个消息被交付前取消了订阅。在发送初始事件消息前，设备必须保证控制点收到了订阅请求的回应，为了保证这一点，控制点接受SID因此能关联事件消息到订阅。

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

通过保持订阅的火星，订阅者必须在订阅过期前，通过发送续约消息续约它的订阅。续约消息被发送到与订阅消息相同的URL，但是续约消息不包含交付事件消息的URL,续约消息包含订阅者标示符。对续约消息的回应与对订阅消息的回应相同。

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

如果订阅过期，订阅者标示符将无效，发送者停止发送事件消息给这个订阅者，而且将其从订阅者列表中清除。如果订阅者试着发送任何消息而不是订阅消息，发布者将拒绝这些消息，因为订阅者标示符无效。

When a subscriber no longer needs eventing from a particularservice, the subscriber should cancel its subscription. Canceling asubscription generally reduces service, control point, and networkload. If a subscriber is removed abruptly from the network, itmight be impossible to send a cancellation message. As a fallback,the subscription will eventually expire on its own unlessrenewed.

当一个订阅者不在需要特定服务的事件消息时，订阅者应该取消它的订阅。取消订阅可以减轻服务，控制点和网络的负担。如果订阅者从网络匆忙离开，它可能来不及发送取消消息。作为防备，订阅最终将自动过期，除非它续约。

Subscribers should monitor discovery messages from thepublisher. If the publisher cancels its advertisements, subscribersshould assume that their subscriptions have been effectivelycancelled.

订阅者应该监视发送者的发现消息。如果发送者取消了它的宣告，订阅者应该认为它的订阅被取消了。

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

下面详细解释订阅。续约和取消消息的请求、回应以及失败的格式。

4.1.1 Eventing: Subscribing:SUBSCRIBE with NT and CALLBACK

For each service in a device, a description message contains aneventing URL (eventSubURL sub element of service element in thedevice description) and the UPnP service identifier (serviceId subelement in service element in device description). To subscribe toeventing for a particular service, a subscription message is sentto that service's eventing URL. (Note that the eventing URL may berelative to the base URL.) The message contains that service'sidentifier as well as a delivery URL for event messages. Asubscription message may also include a requested subscriptionduration.

对于每个设备的服务，一个订阅消息包含了事件URL，（在设备描述的service 元素中的eventSubURL子元素）和服务标示符（设备描述的 service 元素中的serviceId子元素）。为了订阅特定服务的事件消息，订阅消息将被发送到服务的事件URL。（注意事件URL可能是相对于baseURL）.消息包含服务的标示符和交付事件消息的URL。订阅消息也可能包含订阅时间请求。

To subscribe to eventing for a service, a subscriber must send arequest with method SUBSCRIBE and NT and CALLBACK headers in thefollowing format. Values in italics are placeholders for actualvalues.

为了订阅服务的事件消息，一个订阅者发送UBSCRIBE方法的请求，包含NT和CALLBACK标头，格式如下。斜体占位符中需要实际值。

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

SUBSCRIBE方法的请求没有消息体，但是注意消息与下一个HTTP标头有一个空格行。

Listed below are details for the request line and headersappearing in the listing above. All header values are casesensitive except where noted.

一下是请求行的详细信息。所有标头值都区分大小写。

Request line
SUBSCRIBE
Method to initiate or renew asubscription.     初始化或者续约一个订阅的方法
publisher path
Path component of eventing URL (eventSubURL sub element in serviceelement in device description). Single, relative URL.

事件URL的路径组件（在设备描述的service 元素的 eventSubURL子元素中），单一相对URL
HTTP/1.1
HTTP version.
Headers
HOST
Required. Domain name or IP address and optional port components ofeventing URL (eventSubURL sub element in service element in devicedescription). If the port is missing or empty, port 80 isassumed.

要求。事件URL的 域名或IP地址以及一个可选端口号组件（在设备描述的service 元素的eventSubURL子元素中）如果端口号丢失或者为空，默认为80.
CALLBACK
Required. Location to send event messages to. Defined by UPnPvendor. If there is more than one URL, when the service sendsevents, it will try these URLs in order until one succeeds. One ormore 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 inany way; if insufficient memory is available to store the entireCALLBACK URL, the device must reject the subscription.

要求。发送事件消息的地址。厂商定义。如果有多于一个的URL，当服务发送事件消息时，它将按序发送，知道有一个成功。每个URL包含在“<>”当中。每个URL也应该是基于TCP的HTTP（前缀为“http://”）.在任何情况下，设备不能截断URL。如果内存不足存储整个URL，设备拒绝这个订阅。
NT
Required. Notification Type. Must be upnp:event.

要求。通知类型，必须是 upnp:event
SID
(No SID header is used to subscribe.)

订阅消息中不包含SID标头

TIMEOUT
Recommended. Requested duration until subscription expires, eithernumber of seconds or infinite. Recommendation by a UPnP Forumworking committee. Defined by UPnP vendor. Consists of the keyword“Second-” followed (without an intervening space) by either aninteger or the keyword “infinite”.

建议。直到订阅过期，要求“持续时间”，可以是秒数或者infinite.由UPnP论坛工作委员会建议。厂家定义。包含关键字“Second-”接下来(没有空格)是一个整数或者关键字“infinite”

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

如果有足够的资源来维护这个订阅，发布者应该接受这个订阅。为了接受这个订阅，发布者指定一个唯一标示符，指定持续时间，发送初始事件消息（稍后详细介绍）。为了接受这个请求，发布者必须在30秒内发送一个回应，包含预期传送时间。下面斜体占位符需要实际值。

(No body for response to a request with method SUBSCRIBE, but notethat the message must have a blank line following the last HTTPheader.)

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

在发送初始事件消息前，如果设备通过HTTP/1.0发送回应，而没有设置KeepAlivetoken,或者基于Connection:CLOSER标头的HTTP/1.1，设备必须保证TCPFIN标识被发送。在其他情况下（除了回应是分块的），必须指明Content-Length（设为0），早于发送初始事件。

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

Headers
DATE
Recommended. When response was generated. “rfc1123-date” as definedin RFC 2616.

建议。响应生成的时间。
SERVER
Required. Concatenation of OS name, OS version, UPnP/1.0, productname, and product version. String. Must accurately reflect theversion number of the UPnP Device Architecture supported by thedevice. Control points must be prepared to accept a higher versionnumber than the control point itself implements. For example,control points implementing UDA version 1.0 will be able tointeroperate with devices implementing UDA version 1.1.
SID
Required. Subscription identifier. Must be universally unique. Mustbegin with uuid:. Defined by UPnP vendor. Single URI.

要求。订阅标示符。必须是唯一的。以uuid:开头。厂家定义
TIMEOUT
Required. Actual duration until subscription expires, either numberof seconds or infinite. Recommendation by a UPnP Forum workingcommittee. Defined by UPnP vendor. Should be greater than or equalto 1800 seconds (30 minutes). Keyword Second- followed by aninteger (no space) or keyword infinite.

建议。在过期前的实际持续时间，可以是秒数或者infinite.由UPnP工作委员会建议，由厂家指定。不能低于30分钟。关键词Second-后面紧随一个没有空格的整数。

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

如果发布者不接受订阅，或者订阅请求发生了错误。订阅者必须发送以下错误回应消息。回应必须在30秒内完成。包含传送时间。

Errors
Incompatible headers
400 Bad Request. If SID header and one of NT or CALLBACK headersare present, the publisher must respond with HTTP error 400 BadRequest.

400 Bad Request.如果SID标头和 NT与CALLBACK之一的标头被呈现，发布者必须用HTTP错误 400BadRequest回应。
Missing or invalidCALLBACK
412 Precondition Failed. If CALLBACK header is missing or does notcontain a valid HTTP URL, the publisher must respond with HTTPerror 412 Precondition Failed.

412 Precondition Failed.如果CALLBACK标头丢失或者没有包含一个有效的HTTPURL，发布者必须用HTTP错误 412 Precondition Failed回应。
Invalid NT
412 Precondition Failed. If NT header does not equal upnp:event,the publisher must respond with HTTP error 412 PreconditionFailed.

412 Precondition Failed.如果NT标头不等于 upnp:event，发布者必须用HTTP错误 412Precondition Failed回应。
Unable to acceptsubscription
5xx. If a publisher is not able to accept a subscription (such asdue to insufficient resources), it must respond with a HTTP500-series error code.

5xx.如果发布者不能接收订阅（例如由于资源不足），必须用HTTP 500系列错误代码回应。

Other errors may be returned by layers in the protocol stackbelow the UPnP protocols. Consult documentation on those protocolsfor details.

网络协议栈中低于UPnP协议的其他层也可能会返回别的错误。参考这些协议的详细文档。

• 4.1.2 Eventing: Renewing asubscription: SUBSCRIBE with SID

To renew a subscription to eventing for a particular service, arenewal message is sent to that service's eventing URL. (Note thatthe eventing URL may be relative to the base URL.) However, unlikean initial subscription message, a renewal message does not containeither the service's identifier nor a delivery URL for eventmessages. Instead, the message contains the subscription identifierassigned by the publisher, providing an unambiguous reference tothe subscription to be renewed. Like a subscription message, arenewal message may also include a requested subscriptionduration.

为了续约一个特定服务的事件消息的订阅，需要发送一个续约消息到服务事件URL（注意事件URL可能是相对于基础URL），然而，与第一次订阅消息不同，续约消息不包含服务标示符和交付URL。消息中包含发布者指定的订阅标示符，提供订阅续约的明确参考。像订阅消息一样，续约消息需要包含一个要求的订阅周期。

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

续约消息使用与订阅消息相同的方法，但是两个消息使用不相交的标头集合；续约消息使用SID，而订阅消息使用NT和CALLBACK。一个包含SID的消息如果在包含NT或CALLBACK就是一个错误。

To renew a subscription to eventing for a service, a subscribermust send a request with method SUBSCRIBE and SID header in thefollowing format. Values in italics are placeholders for actualvalues.

为了续约一个服务事件的订阅，订阅者必须发送一个使用SUBSCRIBE方法的请求，格式中包含SID标头，方法如下。斜体则占位符需要实际值。

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

SUBSCRIBE请求不包含消息体，但是注意消息必须与下面的HTTP标头有一个空行。

Listed below are details for the request line and headersappearing in the listing above. All header values are casesensitive except where noted.

下面是请求行与标头的详细信息。除非特别指出，所有标头值都区分大小写。

Request line
SUBSCRIBE
Method to initiate or renew a subscription.
publisher path
Path component of eventing URL (eventSubURL sub element in serviceelement in device description). Single, relative URL.
HTTP/1.1
HTTP version.
Headers
HOST
Required. Domain name or IP address and optional port components ofeventing URL (eventSubURL sub element in service element in devicedescription). If the port is missing or empty, port 80 isassumed.
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 subscriptionidentifier assigned by publisher in response to subscriptionrequest. Must be universally unique. Must begin with uuid:. Definedby UPnP vendor. Single URI.

要求。定义标示符。必须是发布者对定义请求的响应中指定的订阅标示符。必须是唯一地。以uuid开头，厂家定义。

TIMEOUT
Recommended. Requested duration until subscription expires, eithernumber of seconds or infinite. Recommendation by a UPnP Forumworking committee. Defined by UPnP vendor. Keyword Second- followedby an integer (no space) or keyword infinite.

To accept a renewal, the publisher reassigns a duration for thesubscription and must send a response in the same format and withthe same conditions as a response to a request for a newsubscription, except that the initial event message is not sentagain.

为了接受这个续约，发布者制定一个订阅的持续时间。必须发送一个与新的订阅请求相同格式的响应，除非初始事件消息没有被发送。

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

如果发布者不能接受续约，或者在需要消息中存在错误，发布者必须发送一下错误响应。响应应该在30秒内发送，包含传输时间。

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

Other errors may be returned by layers in the protocol stackbelow the UPnP protocols. Consult documentation on those protocolsfor details.

网络协议栈中低于UPnP协议的其他层也可能会返回别的错误。参考这些协议的详细文档。

• 4.1.3 Eventing: Canceling asubscription: UNSUBSCRIBE

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

当不在需要一个特定服务的事件消息时，需要发送一个取消消息到服务的事件URL。消息中包含订阅标示符。取消一个订阅通常也减少服务，控制点，和网络负担。如果控制点从突然从网络中离开，可能来不及发送取消消息。但是，订阅最终会国企，除非它续约。

To cancel a subscription to eventing for a service, a subscribershould send a request with method UNSUBSCRIBE in the followingformat. Values in italics are placeholders for actual values.

取消一个服务的事件订阅，订阅者发送一个UNSUBSCRIBE消息，格式如下。斜体占位符需要实际值。

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

Listed below are details for the request line and headersappearing in the listing above. All header values are casesensitive except where noted.

Request line
UNSUBSCRIBE
Method to cancel a subscription.

publisher path
Path component of eventing URL (eventSubURL sub element in serviceelement in device description). Single, relative URL.
HTTP/1.1
HTTP version.
Headers
HOST
Required. Domain name or IP address and optional port components ofeventing URL (eventSubURL sub element in service element in devicedescription). If the port is missing or empty, port 80 isassumed.
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 subscriptionidentifier assigned by publisher in response to subscriptionrequest. Must be universally unique. Must begin with uuid:. Definedby UPnP vendor. Single URI.
TIMEOUT
(No TIMEOUT header is used to cancel an eventsubscription.)

To cancel a subscription, a publisher must send a response inthe following format within 30 seconds, including expectedtransmission time.

取消一个订阅，发布者必须发送一个如下格式的响应，在30秒之内。包含传输时间。

If there is an error with the cancellation request, the publishermust send a response with one of the following errors. The responsemust be sent within 30 seconds, including expected transmissiontime.

如果取消请求中包含以下错误，发布者必须发送一个如下的错误响应。响应必须在30秒内发送，包含预期的传输时间。

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

Other errors may be returned by layers in the protocol stackbelow the UPnP protocols. Consult documentation on those protocolsfor details.

• 4.2 Eventing: Eventmessages

A service publishes changes to its state variables by sendingevent messages. These messages contain the names of one or morestate variables and the current value of those variables. Eventmessages should be sent as soon as possible to get accurateinformation about the service to subscribers and allow subscribersto display a responsive user interface. If the value of more thanone variable is changing at the same time, the publisher shouldbundle these changes into a single event message to reduceprocessing and network traffic.

服务发布者通过发送事件消息更改它的状态变量。消息中包含状态变量的明智，当前值。事件消息应该尽快发送给订阅者，这样订阅者能尽快获得准确信息并展示在回应的用户接口。如果多个状态变量同时变化，发布者需要绑定这些时间消息到一个时间消息来减少处理以及网络流量。

As explained above, an initial event message is sent when asubscriber first subscribes; this event message contains the namesand values for all evented variables and allows the subscriber toinitialize its model of the state of the service. This messageshould be sent as soon as possible after the publisher accepts asubscription. 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 eventkey must be maintained by the publisher for each subscription tofacilitate error detection (as explained below). The event key fora subscription is initialized to 0 when the publisher sends theinitial event message. For each subsequent event message, thepublisher increments the event key for a subscription, and includesthat updated key in the event message. Any implementation of eventkeys should handle overflow and wrap the event key from 4294967295back to 1 (not 0). Subscribers must also handle this special casewhen the next event key is not an increment of the previous key.Should be implemented as a 4 Byte (32 bit) unsigned integer.

事件消息使用事件key做标签。发布者必须维护么个订阅的事件key来实现错误检查。当发布者法哦少年宫了一个初始事件消息后，订阅者的事件key从零开始，发布者为每一个订阅增加事件key，包含更新key 到事件消息。任何事件key 的实现都应该处理溢出，从429496725到0.当下一个事件Key不是上一个key的增加时，订阅者必须处理特殊情况，用32为无符号整数实现。

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

如果订阅者对任何事件消息都没有任何回应，发布者需要继续尝试发送顺序的事件消息给订阅者，直到订阅过期。

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

为了修复一个事件订阅，如果订阅者丢失了一个或者多个事件消息，订阅者必须取消订阅并重新订阅。通过如此，订阅者可以获得新的订阅标示符。一个新的初始订阅消息，以及新的事件Key

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

• 4.2.1 Eventing: Eventmessages: NOTIFY

To send an event message, a publisher must send a request withmethod NOTIFY in the following format. Values in italics below areplaceholders for actual values.

为了发送事件消息，发布者必须发送NOTIFY方法的请求，格式如下。斜体占位符需要实际值。

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

Request line
NOTIFY
Method to notify client aboutevent.       发送给客户的事件方法
delivery path
Path component of delivery URL (CALLBACK header in subscriptionmessage). Destination for event message. Single, relative URL. Mustbe one of the URLs contained in the CALLBACK header, withouttruncation or modification.

交付URL的路径组件（订阅消息的CALLBACK标头）。事件消息的目的地。单一相对URL。必须是CALLBACK标头的URL，不能删节或修改。
HTTP/1.1
HTTP version.
Headers
HOST
Required. Domain name or IP address and optional port components ofdelivery URL (CALLBACK header in subscription message). If the portis 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. Mustbegin with uuid:. Defined by UPnP vendor. Single URI.
SEQ
Required. Event key. Must be 0 for initial event message. Must beincremented by 1 for each event message sent to a particularsubscriber. To prevent overflow, must be wrapped from 4294967295to1. 32-bit unsigned value represented as a single decimal integerwithout leading zeroes (some implementations may include leadingzeroes, which should be ignored by the recipient).

要求。事件Key.初始事件消息必须是0.每发送给特定订阅者一个事件消息，加1.为了防止溢出，范围为4294967295to1。32位无符号值，使用十进制整数表示，不包括首位0.（有些实现可能会包含首位0，接受者对此忽略）
Body
propertyset
Required. xmlns namespace attribute must beurn:schemas-upnp-org:event-1-0. Contains the following subelement.

要求。xmlns命名空间属性必须是urn:schemas-upnp-org:event-1-0。包含以下子元素。

property
Required. Repeat once for each variable name and value in the eventmessage. Must be qualified by
propertyset namespace. Contains the following sub element.

要求。事件消息中的每个变量名和值出现一次。必须符合属性命名空间，包含以下子元素。
variableName
Required. Element is name of a state variable that changed (namesub element of stateVariable
element in service description). Must not be qualified with anynamespace. Value is the new value
for this state variable. Case sensitive. Single data type asspecified by UPnP service description.

要求。变化的状态变量的名子（服务描述的stateVariable元素的 name子元素）。不必符合任何命名空间。值为状态变量的新值。区分大小写。有UPnP服务描述指定数据类型。

For future extensibility, when processing XML like the listingabove, devices and control points must ignore: (a) any unknownelements and their sub elements or content, and (b) any unknownattributes and their values. Note that when subscribing to eventingwith a service that is of a higher version than what is supportedby the control point, event notifications may be sent by theservice to the control point containing state variable names whichare not recognized by the control point. The control point shoulddiscard and ignore such unrecognized state variables within eventnotification messages.

When the new value of any variable contains one or morecharacters reserved as markup (such as ampersand(“&”) or less than (“<”)), the textmust be escaped in accordance with the provisions of section 2.4 ofthe XML specification and each such character replaced with theequivalent numeric representation or string (such as“&amp;” or “&lt;”). Such charactersappearing in URLs that appear as values may also be escaped inaccordance with the URL escaping rules specified in Section 2.4 ofRFC 2396.

Control points and devices shall ignore any XML comments or XMLprocessing instructions they may receive that they do notunderstand.

Note that because HTTP 1.1 allows use of chunked encoding, somedevices may send the event notification using chunked encoding ifthe SUBSCRIBE request specified HTTP 1.1. It is thereforerecommended that all implementations that include HTTP 1.1 in theSUBSCRIBE request support receiving chunked encoding.

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

为了声明对事件消息的接收。订阅者比附在30秒内做出回应。包括传输时间。如果订阅者在30秒内没有回应，或者发布者没有联系到订阅者的URL，发布者需要放弃这个倒订阅者的消息，但是应该保持订阅的活性，继续发送以后的事件消息，一直到订阅过期或者被取消。订阅者必须用以下格式做出响应。

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

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

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

Errors
Missing SID
412 Precondition Failed. If the SID header is missing or empty, thesubscriber must respond with HTTP error 412 PreconditionFailed.
Invalid SID
412 Precondition Failed. If a SID does not correspond to a knownsubscription, the subscriber must respond with HTTP error 412Precondition Failed. (Service must terminate this SID when itreceives this error response.)
Missing NT or NTSheader
400 Bad Request. If the NT or NTS header is missing, the subscribermust 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 PreconditionFailed.
Invalid NTS header
412 Precondition Failed. If NTS header does not equalupnp:propchange, the subscriber must respond with HTTP error 412Precondition Failed.

Other errors may be returned by layers in the protocol stackbelow the UPnP protocols. Consult documentation on those protocolsfor details.

• 4.3 Eventing: UPnP TemplateLanguage for eventing

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

UPnP末班语言为设备和服务定义了易于格式化的模板。为了减少扩展，它也提供了事件消息主题的模板。描述那一章解释了适用于设备和服务的UPnP模板语言，就像那一章一样，UPnP模板语言使用XML语法编写，从XML策略衍生（结构：数据类型）。下面是适用于事件的语言列表。这些定义用于事件消息。颜色为绿色。下面是这些元素的定义。

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

紧随XML Schema 元素，属性和值之后的是一个简单介绍，更多详细信息，可以参见后面的参考文献。

UPnP Template Language for eventing

element
References an element for the purposes of declaring nesting.maxOccurs attribute defines maximum number of times the elementmust occur; default is maxOccurs = 1; elements that can appear oneor more times have maxOccurs = *.

为了宣布嵌套，参考一个元素。maxOccurs属性定义了元素必须发生的最大次数。默认是1.能够出现一次或者多次的元素maxOccurs = *。

ElementType
Defines an element in the new, derived language. name attributedefines element name. model attribute indicates whether elements inthe new, derived language can contain elements not explicitlyspecified 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.

使用新的，可衍生的语言定义一个元素。name属性定义了元素名，model属性显示元素师新的，derived语言可以包含元素没有在此指明。只有未指定的元素能被包含。model=  open。 content 属性显示了什么样的内容被包含。元素包含其他元素 的 content= eltOnly.

As explained in the section on Description, the UPnP TemplateLanguage for services also specifies a sendEvents attribute for astate variable. The default value for this attribute is yes. Todenote that a state variable is evented, the value of thisattribute is yes (or the attribute is omitted) in a servicedescription; to denote that a state variable is non-evented, thevalue is no. Note that if all of a service's state variables arenon-evented, the service has nothing to publish, and control pointscannot subscribe and will not receive event messages from theservice.

• 4.4 Eventing: Augmenting theUPnP Template Language

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

As explained above, some state variables may change value toorapidly for eventing to be useful. Below is a recommendedvocabulary for UPnP Forum working committees or UPnP vendors todocument moderation in the number of event messages sent due tochanges in a variables value.

maximumRate = n
Optional. State variable v will not be part of an event messagemore often than n seconds. If v is the only variable changing, thenan event message will not be generated more often than every nseconds. If v ceases to change after an event message has been sentbut before n seconds have transpired, an event message must be sentwith the new value of v. Recommended for variables that modelcontinuously changing properties. Single integer.
minimumDelta = n
Optional. State variable v will not be part of an event messageunless its value has changed by more than n * allowedValueRangestep 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 onControl.) 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 whenan event goes out. The publisher should make its best attempt tomeet moderation rules described above, but the publisher can flushrecent changes when it sends out events.

Note that moderation affects events only and not state tableupdates. Specifically, control actions which return the value ofstate variables may return a more current value than published viaeventing. Put another way, moderation means that not all statetable changes result in events.

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