Eventing: Event messages

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.

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.

NOTIFY delivery path HTTP/1.1 HOST: delivery host:delivery port

CONTENT-TYPE: text/xml

CONTENT-LENGTH: Bytes in body NT: upnp:event

NTS: upnp:propchange SID: uuid:subscription-UUID SEQ: event key

<?xml version="1.0"?>

<e:propertyset xmlns:e="urn:schemas-upnp-org:event-1-0">

<e:property>

<variableName>new value</variableName>

</e:property>

Other variable names and values (if any) go here.

</e:propertyset>

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 propertyset

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.

When the new 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 “&amp;” or “&lt;”). Such characters appearing in URLs that appear as values may also be escaped in accordance with the URL escaping rules specified in Section 2.4 of RFC 2396.

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 Missing 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.