4. 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
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.
SUBSCRIBE publisher path HTTP/1.1 HOST: publisher host:publisher port
CALLBACK: <delivery URL>
NT: upnp:event
TIMEOUT: Second-requested subscription duration
(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.
HTTP/1.1 200 OK
DATE: when response was generated
SERVER: OS/version UPnP/1.0 product/version SID: uuid:subscription-UUID
TIMEOUT: Second-actual subscription duration
(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.
SUBSCRIBE publisher path HTTP/1.1 HOST: publisher host:publisher port
SID: uuid:subscription UUID
TIMEOUT: Second-requested subscription duration
(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.
UNSUBSCRIBE publisher path HTTP/1.1 HOST: publisher host:publisher port
SID: uuid:subscription UUID
(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.