diff --git a/docs/218762_218762.pdf b/docs/218762_218762.pdf new file mode 100644 index 0000000..ce34c98 Binary files /dev/null and b/docs/218762_218762.pdf differ diff --git a/docs/AVTransport1.0.pdf b/docs/AVTransport1.0.pdf new file mode 100644 index 0000000..922caee Binary files /dev/null and b/docs/AVTransport1.0.pdf differ diff --git a/docs/ConnectionManager1.0.pdf b/docs/ConnectionManager1.0.pdf new file mode 100644 index 0000000..e9789ee Binary files /dev/null and b/docs/ConnectionManager1.0.pdf differ diff --git a/docs/ContentDirectory1.0.pdf b/docs/ContentDirectory1.0.pdf new file mode 100644 index 0000000..a281ed3 Binary files /dev/null and b/docs/ContentDirectory1.0.pdf differ diff --git a/docs/MediaRenderer1.0_000.pdf b/docs/MediaRenderer1.0_000.pdf new file mode 100644 index 0000000..0fb0c7f Binary files /dev/null and b/docs/MediaRenderer1.0_000.pdf differ diff --git a/docs/MediaServer1.0.pdf b/docs/MediaServer1.0.pdf new file mode 100644 index 0000000..b45bee7 Binary files /dev/null and b/docs/MediaServer1.0.pdf differ diff --git a/docs/RenderingControl1.0.pdf b/docs/RenderingControl1.0.pdf new file mode 100644 index 0000000..bbd17b6 Binary files /dev/null and b/docs/RenderingControl1.0.pdf differ diff --git a/docs/UPnPAvArchtiecture0.83.pdf b/docs/UPnPAvArchtiecture0.83.pdf new file mode 100644 index 0000000..262845b Binary files /dev/null and b/docs/UPnPAvArchtiecture0.83.pdf differ diff --git a/docs/draft-cohen-gena-client-01.txt b/docs/draft-cohen-gena-client-01.txt new file mode 100644 index 0000000..057de1d --- /dev/null +++ b/docs/draft-cohen-gena-client-01.txt @@ -0,0 +1,812 @@ + INTERNET DRAFT J. Cohen, Microsoft + S. Aggarwal, Microsoft + Y. Y. Goland, Microsoft + Expires April, 2000 September 6, 2000 + + General Event Notification Architecture Base: Client to Arbiter + + Status of this memo + + This document is an Internet-Draft and is in full conformance with all + provisions of Section 10 of RFC2026. + + Internet-Drafts are working documents of the Internet Engineering Task + Force (IETF), its areas, and its working groups. Note that other + groups may also distribute working documents as Internet-Drafts. + + Internet-Drafts are draft documents valid for a maximum of six months + and may be updated, replaced, or obsoleted by other documents at any + time. It is inappropriate to use Internet- Drafts as reference + material or to cite them other than as "work in progress." + + The list of current Internet-Drafts can be accessed at + http://www.ietf.org/ietf/1id-abstracts.txt + + The list of Internet-Draft Shadow Directories can be accessed at + http://www.ietf.org/shadow.html. + + Please send comments to the SSDP mailing list. Subscription information + for the SSDP mailing list is available at + http://www.upnp.org/resources/ssdpmail.htm. + + Abstract + + This document provides for the ability to send and receive + notifications using HTTP over TCP/IP and administratively scoped + unreliable multicast UDP. Provisions are made for the use of + intermediary arbiters, called subscription arbiters, which handle + routing notifications to their intended destination. + + 1 Introduction + + This document provides for the sending of HTTP Notifications using + administratively scoped unreliable Multicast UDP. Multicast UDP is + useful in that it allows a single notification to be delivered to a + potentially large group of recipients using only a single request. + + However administrative scoped unreliable Multicast UDP suffers from a + number of problems including: how to route it, how to handle + firewalling and how to deal with multiple scopes. This document only + addresses the use of Multicast UDP within a single administrative scope + and only countenances its use for scenarios where there is no + notification proxy. + + In order to allow for notifications to be distributed beyond a single + administrative multicast scope it is necessary to provide for relaying + + Cohen et al. [Page 1] + + INTERNET-DRAFT GENA Base September 6, 2000 + + + arbiters. These arbiters, called subscription arbiters, are able to + form, through an unspecified mechanism, relationships with other + subscription arbiters in order to distribute notifications. This allows + a client to send a single HTTP notification to its subscription arbiter + and have that notification forwarded on to one or more recipients. It + is the subscription arbiter, not the client, who is responsible for + maintaining the list of potential recipients and distributing + notifications to those recipients. + + In order for subscription arbiters to know to whom to distribute + notifications clients who wish to receive notifications, known as + subscribers, must subscribe to the subscription arbiter. + + 2 Changes + 2.1 Since V00 + [Ed. Note: Aren’t there times when the service needs to hear the + subscriptions? When the identity of the subscriber will effect the + output? Of course… Notification identifiers must be explicit in the + notification, not implicit as a function of the address.] + [Ed. Note: We need to look into adding support for sequence numbers on + events, this is needed for things like UPnP. If this doesn't end up + effecting how the arbiter works then we should put it into a separate + draft.] + [Talk about the scope header having values other than the URL of the + resource, we are using the UPnP example where you would put the USN + value into the scope. Everyone needs to pay attention to the scope + header!!!!] + [Add a note that if no Scope header is included then the default is to + treat the Request-URI as the scope.] + [What do you do if someone subscribes to something they are already + subscribed to? The question is tricky because, short of using + authentication, you don’t know who “someone” is and even then, because + multiple programs may be running, you can’t be sure if you are really + talking to the same person. My instinct would be to just give them a + second parallel subscription.] + [Think REALLY hard about allowing for multiple values in a NT header] + + 3 Definitions + + 3.1 Event + + Any occurrence that may potentially trigger a notification. + + 3.2 Subscription + + An established relationship in which a resource has indicated interest + in receiving certain notifications. + + 3.3 Subscriber + + A resource that negotiates a subscription with a subscription arbiter. + + + Cohen et al. [Page 2] + + INTERNET-DRAFT GENA Base September 6, 2000 + + + 3.4 Implied Subscriber + + A resource that did not negotiate a subscription with a subscription + arbiter but will still be notified of events on that arbiter. + + 3.5 Notifying Resource + + A resource that issues notifications, for example, a subscription + arbiter. + + 3.6 Subscription Arbiter + + A resource that accepts subscriptions, receives notifications and + forwards those notifications to its subscribers. + + 3.7 Notification + + A message sent by a notifying resource to provide notification of an + event. + + 3.8 Notification Type + + A mechanism to classify notifications into categories. This allows + subscribers to specify exactly what class of notifications they want to + receive. It also allows notifying resources to specify what class of + notification they are sending out. + + Notification types do not necessarily identify a single event but + rather identify a group of related notifications. The notification sub- + type is used to specify a particular event. + + 3.9 Notification Sub-Type + + Identification of a particular event within a notification type. + + For example, the fictional notification of type home:doors may contain + notification sub-types such as door:open, close:door, etc. + + There is no requirement that the URI identifying the notification type + and the URI identifying the notification sub-type have a syntactic + relationship, only a semantic one. + + 3.10 Subscription ID + + A unique identifier for a subscription. Subscription Ids MUST be URIs + and MUST be unique across all subscriptions across all resources for + all time. + + 3.11 Scope + + Scopes are used in a subscription to indicate the notifying resource + the subscriber is interested in. + + Cohen et al. [Page 3] + + INTERNET-DRAFT GENA Base September 6, 2000 + + + + 4 Notification Model + + [Ed. Note: Aren’t there times when the service needs to hear the + subscriptions? When the identity of the subscriber will effect the + output? Of course… Notification identifiers must be explicit in the + notification, not implicit as a function of the address.] + + [Ed. Note: We need to look into adding support for sequence numbers on + events, this is needed for things like UPnP. If this doesn't end up + effecting how the arbiter works then we should put it into a separate + draft.] + + The notification model for GENA is based on the following picture: + + [Subscriber] <- [1+ Subscription Arbiters] <- [Notifying Resource] + Notification Request Notification Request + -> + Subscription Request + + Subscribers send subscription requests to their subscription arbiter. + The arbiter will then forward to the subscriber any notifications it + receives which match the subscriber's subscription. + + Notifying resources send notifications to their subscription arbiter to + be passed on to subscribers. + + Subscription arbiters communicate with each other in order to pass + along notifications and subscriptions. Subscription arbiter to + subscription arbiter communication is out of scope for this + specification. + + For the purposes of this protocol all communication is between + subscribers/notifying resources and their subscription arbiter. This + does not preclude direct communication between a subscriber and a + notifying resource. Rather it means that the notifying resource is + acting as a subscription arbiter. + + This document also deals with a degenerate case where no subscription + arbiter is available but administratively scoped unreliable multicast + UDP facilities are. In that case provisions are made to allow a + notifying resource to send its notifications directly to a previously + agreed upon administratively scoped multicast UDP address where + interested resources can listen in to the notification. + + 4.1 Sending HTTP Notifications through a Subscription Arbiter + + A notifying resource finds its subscription arbiter through an + unspecified mechanism. The notifying resource will send all of its + notifications to the subscription arbiter who will then forward those + subscriptions on to subscribers. + + + Cohen et al. [Page 4] + + INTERNET-DRAFT GENA Base September 6, 2000 + + + This document does not provide a mechanism by which the notifying + resource can retrieve information about which resources have subscribed + to receive notifications from the notifying resource. + + 4.2 Receiving HTTP Notifications through a Subscription Arbiter + + A subscribing resource finds its subscription arbiter through an + unspecified mechanism. It is the responsibility of the subscribing + resource to send subscription requests to the subscription arbiter in + order to inform the arbiter as to which notifications the subscriber + would like to receive. + + A subscription request can be thought of as a persistent search filter + on the set of notifications that the subscription arbiter is aware of. + Whenever the subscription arbiter receives a notification that matches + the search filter it will forward the notification to the subscriber. + + This document defines a very basic search filter that allows a + subscribing resource to specify a particular resource and a type of + notification the subscribing resource is interested in. Whenever a + notification of the specified type is made by the specified resource + the subscription arbiter will forward the notification to the + subscriber. + + 5 Subscription Arbiters and Forwarded Notifications + + When forwarding a notification the subscription arbiter will change the + Request-URI and the Host header value to match the subscriber who is to + be notified. Subscription arbiters MUST NOT make any other changes to + be made to the message unless the definition of the header or body + element specifically provides for such alteration and/or for security + reasons. + + 6 Stuff + In the case where a subscriber sends a subscription request to an + arbiter: Is it OK if the arbiter rejects subscription requests that + don't match certain notification type criteria? or should the arbiter + be totally unaware of any notification types at this point? + In the case where a notifying resource sends a notify request to an + arbiter: Is it OK if the arbiter rejects notification requests that + don't match certain notification type criteria? or should the arbiter + just accept the notification request and filter the available + subscriptions taking the notification type as criteria? + In the hypothetical case where the arbiter just accepted subscriptions + of certain types, could an arbiter just be dedicated to one + subscription type? If the previous statement was affirmative then the + existence of a notification type for that particular arbiter wouldn't + even make sense right? + + We need to discuss the implicit relationship between an arbiter and its + subscribers, all the unstated assumptions. + + + Cohen et al. [Page 5] + + INTERNET-DRAFT GENA Base September 6, 2000 + + + The subscription server may not necessarily have been the one who + created a SID, it could have been the service who is using the + subscription server to do replication. In that case a subscription + request could come in with a SID on it, a ref-counted SID. But this bug + me because a SID indicates a relationship. How does one change one’s + call back for a SID? Especially if you want to send in the change + command from somewhere other than the place receiving the notification + so you can’t just check the address on the packet. Do we need tow types + of SIDs? I don’t just want to overload NT. I think NT and NTS should be + left alone to just give notification type. They shouldn’t be overloaded + to also provide functional information… functional is the wrong word. + They shouldn’t be overloaded to provide routing information. + Event type. + Event Sub-type. + Event group (if any). + Individual subscription. + + The problem is that the last two are not always both necessary. For + example, an individual subscription ID is not necessary if the events + are only sent to a multicast group. Additionally the event group ID + isn’t necessary if the event only goes to a single end point. + Maybe we need an end point identifier? We need a way to say “Stop + sending the events to this call-back, send it to this other call-back.” + THIS ISN’T GOOD ENOUGH. What if two programs are both at the same call- + back? You need ref counting. + I guess what I’m trying to avoid is implicit ref-counting, I would + rather have explicit ref-counting. That is, I would like the ref count + to be included in each request in the person of an ID that is unique to + every listener, this is independent of call-back address. + + + Make sure that if you leave off the NT then this means you want to + receive all notifications from the identified scope. + + Also make sure that we can use scope as a selector for video streams on + a video server. + + We need to add a “connect and flood” mechanism such that if you connect + to a certain TCP port you will get events. There is no + subscribe/unsubscribe. We also need to discuss this feature for + multicasting. If you cut the connection then you won’t get any more + events. + + 7 NOTIFY HTTP Method + + The NOTIFY method is used to transmit a notification. The Request-URI + of the notification method is the notifying resource's subscription + arbiter who will handle forwarding the message to interested + subscribers. + + The NOTIFY method may be sent using unreliable administrative scoped + multicast UDP as specified in [HTTPMU]. In such a case the multicast + + Cohen et al. [Page 6] + + INTERNET-DRAFT GENA Base September 6, 2000 + + + channel is treated as the subscription arbiter. When a NOTIFY is sent + using multicast UDP as a transport there is no response. + + The NOTIFY method MUST contain a NT header and MAY contain a body, a + NTS header and SID. Subscribers MAY ignore the body in a subscription + request. Subscription arbiters MAY remove and/or alter the value of the + SID header in order to set it to the value that their subscriber is + expecting. Note that in general notifying resources will not put SID + headers on their notifications. This is generally a value that + subscription arbiters add. + + Note that notifications to implied subscribers may not necessarily have + SIDs. The client can tell the subscription arbiter to stop sending the + notification by returning a 412 (Precondition Failed). + + 7.1 Response Codes + + 200 (OK) - This is the standard response to a NOTIFY received by a + subscriber. + + 202 (Accepted) - This is the standard response to a NOTIFY received by + a subscription arbiter. + + 412 (Precondition Failed) - The client doesn't recognize the SID or the + request doesn't have a SID and the client doesn't want to receive the + notification. + + 7.2 Examples + + 7.2.1 TCP/IP + + NOTIFY /foo/bar HTTP/1.1 + Host: blah:923 + NT: ixl:pop + NTS: clock:bark + SID: uuid:kj9d4fae-7dec-11d0-a765-00a0c91e6bf6 + + HTTP/1.1 200 O.K. + + A notification of type ixl:pop sub-type clock:bark has been sent out in + response to the specified subscription. The request-URI could either + identify a particular resource who is to be notified or a subscription + arbiter who will then take responsibility for forwarding the + notification to the appropriate subscribers. + + 7.2.2 Multicast UDP + + NOTIFY * HTTP/1.1 + Host: somemulticastIPaddress:923 + NT: ixl:pop + NTS: clock:bark + + + Cohen et al. [Page 7] + + INTERNET-DRAFT GENA Base September 6, 2000 + + + As in the previous example this is a notification of type ixl:pop sub- + type clock:bark but it has been sent out to the multicast channel as an + unsolicited notification. Hence it does not have a SID header. Also, + because it was sent out to a multicast UDP channel it also doesn’t have + a response. + + 8 SUBSCRIBE HTTP Method + + [Talk about the scope header having values other than the URL of the + resource, we are using the UPnP example where you would put the USN + value into the scope. Everyone needs to pay attention to the scope + header!!!!] + + The SUBSCRIBE method is used to provide a subscription arbiter with a + search filter to be used in determining what notifications to forward + to the subscriber. + + The Request-URI of the SUBSCRIBE method specifies the subscription + arbiter which will handle the subscription. + + A SUBSCRIBE request MUST have a NT header unless it is a re- + subscription request. The NT header specifies what sort of notification + the subscriber wishes to be notified of. + + A SUBSCRIBE request MUST have a Call-Back header unless it is a re- + subscription request. The Call-Back header specifies how the subscriber + is to be contacted in order to deliver the notification. + + A SUBSCRIBE method MUST NOT have a NTS header. The base subscription + search filter only supports filtering on the NT value of a + notification. This limitation is meant to keep the subscription + functionality at the minimum useful level. It is expected that future + specifications will provide for more flexible subscription search + filters. + + A SUBSCRIBE method MUST have a scope header unless it is a re- + subscription request. The scope header identifies the resource that the + subscriber wishes to receive notifications about. + + The Timeout request header, whose syntax is defined in section 9.8 of + [WEBDAV] MAY be used on a SUBSCRIBE request. The header is used to + request that a subscription live for the specified period of time + before having to be renewed. Subscription arbiters are free to ignore + this header. + + A subscription arbiter MUST ignore the body of a SUBSCRIBE request if + it does not understand that body. + + A successful response to the SUBSCRIBE method MUST include a Timeout + response header and a SUBID header. + + + + Cohen et al. [Page 8] + + INTERNET-DRAFT GENA Base September 6, 2000 + + + [Add a note that if no Scope header is included then the default is to + treat the Request-URI as the scope.] + + [What do you do if someone subscribes to something they are already + subscribed to? The question is tricky because, short of using + authentication, you don’t know who “someone” is and even then, because + multiple programs may be running, you can’t be sure if you are really + talking to the same person. My instinct would be to just give them a + second parallel subscription.] + + 8.1 Re-Subscribing + + When the period of time specified in the Timeout response header passes + the subscription MAY expire. In order to keep the subscription alive + the subscriber MUST issue a SUBSCRIBE method with a SID header set to + the subscription to be re-subscribed. A re-subscribe request MUST NOT + have a NT header but it MAY have a Timeout and/or a Call-Back header. + + Note that the value in the Timeout response header will not take into + account the time needed from when the value was generated until it was + passed through the arbiter, put on the wire, sent to the subscriber, + parsed by the subscriber’s system and finally passed to the + subscriber’s program. Hence the value should be taken as an absolute + upper bound. Subscribers are encouraged to re-subscribe a good period + of time before the actual expiration of the subscription. + + 8.2 Response Codes + + 200 (OK) - The subscription request has been successfully processed and + a subscription ID assigned. + + 400 (Bad Request) - A required header is missing. + + 412 Precondition Failed - Either the subscription arbiter doesn't + support any of the call-backs, doesn't support the NT or doesn't + support the scope. This code is also used on resubscription requests to + indicate that the subscription no longer exists. + + 8.3 Examples + + 8.3.1 Subscription + + SUBSCRIBE dude HTTP/1.1 + Host: iamthedude:203 + NT: ixl:pop + Call-Back: + Scope: http://icky/pop + Timeout: Infinite + + HTTP/1.1 200 O.K. + Subscription-ID: uuid:kj9d4fae-7dec-11d0-a765-00a0c91e6bf6 + Timeout: Second-604800 + + Cohen et al. [Page 9] + + INTERNET-DRAFT GENA Base September 6, 2000 + + + + This subscription request asks the subscription arbiter + http://iamthedude/dude:203 for a subscription on notifications of type + ixl:pop from the resource http://icky/pop. + + 8.3.2 Re-Subscription + + SUBSCRIBE dude HTTP/1.1 + Host: iamthedude:203 + Subscription-ID: uuid:kj9d4fae-7dec-11d0-a765-00a0c91e6bf6 + Timeout: Infinite + + HTTP/1.1 200 O.K. + Subscription-ID: uuid:kj9d4fae-7dec-11d0-a765-00a0c91e6bf6 + Timeout: Second-604800 + + The subscription has been successfully renewed. + + 9 UNSUBSCRIBE HTTP Method + + The UNSUBSCRIBE method is used to terminate a subscription. The + UNSUBSCRIBE method MUST include a SID header with the value of the + subscription to be un-subscribed. + + If the SID identifies a subscription that the subscription arbiter does + not recognize or knows is already expired then the arbiter MUST respond + with a 200 (OK). + + 9.1 Response Codes + + 200 (OK) - Unsubscribe succeeded. + + 412 (Precondition Failed) – The SID was not recognized. + + 9.2 Example + + UNSUBSCRIBE dude HTTP/1.1 + Host: iamtheproxy:203 + SID: uuid:kj9d4fae-7dec-11d0-a765-00a0c91e6bf6 + + HTTP/1.1 200 O.k. + + 10 New HTTP Headers + + 10.1 NT Header + + [Think REALLY hard about allowing for multiple values in a NT header] + + The NT header is used to indicate the notification type. + + NT = "NT" ":" absoluteURI ; See section 3 of [RFC2396] + + + Cohen et al. [Page 10] + + INTERNET-DRAFT GENA Base September 6, 2000 + + + 10.2 NTS Response Header + + The NTS response header is used to indicate the notification sub-type + of a notification. + + NTS = "NTS" ":" absoluteURI + + 10.3 Call-Back Header + + The Call-Back header specifies, in order of preference, the means the + subscriber would like the subscription arbiter to use to deliver + notifications. + + Call-Back = "Call-Back" ":" *Coded-URI; See section 9.4 of [WEBDAV] + + 10.4 Timeout Response Header + + The Timeout response header has the same syntax as the Timeout request + header defined in section 9.8 of [WEBDAV]. The subscription arbiter + informs the subscriber how long the subscription arbiter will keep + their subscription active without a re-subscribe using the Timeout + response header. + + 10.5 SID Header + + The SID header contains a subscription ID. + + SID = "SID" ":" absoluteURI + + 10.6 Scope Request Header + + The scope request header indicates the resource the subscriber wishes + to receive notifications about. + + SCOPE = "Scope" ":" absoluteURI + + 11 Future Work + + This specification defines a minimally useful set of notification + functionality. It does not, however, address three critical issues that + are needed by some notification environments. It is expected that all + of these features can be provided in extension specifications to this + base specification. + + The first issue is polling. In some environments, especially those with + intermittent connectivity, it would be desirable for subscription + arbiters to be able to pool up notifications and then to deliver them + when the subscriber asks for them. + + The second issue is subscription arbiter to subscription arbiter + communication. It is likely that subscription arbiters will want to + communicate directly with each other in order to efficiently distribute + + Cohen et al. [Page 11] + + INTERNET-DRAFT GENA Base September 6, 2000 + + + notifications and subscriptions. This requires provision for + notification routing and loop prevention. + + The third issue is support for depth functionality. In some systems one + wishes to receive a notification about a resource and any of its + children as the term is defined in [WEBDAV]. + + 12 Security Considerations + + TBD. + + [Notes: + The really horrible security concerns don't start until you build the + subscription arbiter to arbiter protocol. Otherwise the arbiter is very + close to a proxy in that it takes confidential information from a + subscriber and/or notifying resource and is expected to do the right + thing (TM) with it. Authentication and such prevents bogus + notifications and subscriptions. + + Another problem is if someone sends in a subscription request with the + call-back pointing at someone else. This could be used for a denial of + service attack. Arbiters should authenticate subscribers and probably + the call-back points as well.] + + 13 Acknowledgements + Jesus Ruiz-Scougall (Exchange) + Erik Christensen (VB) (Exchange) + Ting Cai + 14 IANA Considerations + + None. + + 15 Copyright + + The following copyright notice is copied from RFC 2026 [Bradner, 1996], + Section 10.4, and describes the applicable copyright for this document. + + Copyright (C) The Internet Society February 10, 1998. All Rights + Reserved. + + This document and translations of it may be copied and furnished to + others, and derivative works that comment on or otherwise explain it or + assist in its implementation may be prepared, copied, published and + distributed, in whole or in part, without restriction of any kind, + provided that the above copyright notice and this paragraph are + included on all such copies and derivative works. However, this + document itself may not be modified in any way, such as by removing the + copyright notice or references to the Internet Society or other + Internet organizations, except as needed for the purpose of developing + Internet standards in which case the procedures for copyrights defined + in the Internet Standards process must be followed, or as required to + translate it into languages other than English. + + Cohen et al. [Page 12] + + INTERNET-DRAFT GENA Base September 6, 2000 + + + + The limited permissions granted above are perpetual and will not be + revoked by the Internet Society or its successors or assignees. + + This document and the information contained herein is provided on an + "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING + TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT + NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL + NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR + FITNESS FOR A PARTICULAR PURPOSE. + + 16 Intellectual Property + + The following notice is copied from RFC 2026 [Bradner, 1996], Section + 10.4, and describes the position of the IETF concerning intellectual + property claims made against this document. + + The IETF takes no position regarding the validity or scope of any + intellectual property or other rights that might be claimed to pertain + to the implementation or use other technology described in this + document or the extent to which any license under such rights might or + might not be available; neither does it represent that it has made any + effort to identify any such rights. Information on the IETF's + procedures with respect to rights in standards-track and standards- + related documentation can be found in BCP-11. Copies of claims of + rights made available for publication and any assurances of licenses to + be made available, or the result of an attempt made to obtain a general + license or permission for the use of such proprietary rights by + implementers or users of this specification can be obtained from the + IETF Secretariat. + + The IETF invites any interested party to bring to its attention any + copyrights, patents or patent applications, or other proprietary rights + which may cover technology that may be required to practice this + standard. Please address the information to the IETF Executive + Director. + + 17 References + + [WEBDAV] + + [Bradner, 1996] S. Bradner, "The Internet Standards Process - Revision + 3." RFC 2026, BCP 9. Harvard University. October, 1996. + + [HTTPMU] + + [HTTP11] R. Fielding, J. Gettys, J. C. Mogul, H. Frystyk, L. Masinter, + P. Leach and T. Berners-Lee. Hypertext Transfer Protocol – HTTP/1.1. + Internet Draft – Work in Progress. http://www.ietf.org/internet- + drafts/draft-ietf-http-v11-spec-rev-06.txt, November 18, 1998. + + [RFC2396] http://www.rfc-editor.org/rfc/rfc2396.txt + + Cohen et al. [Page 13] + + INTERNET-DRAFT GENA Base September 6, 2000 + + + + 18 Authors' Addresses + + Josh Cohen, Sonu Aggarwal, Yaron Y. Goland + Microsoft Corporation + One Microsoft Way + Redmond, WA 98052-6399 + + Email: {joshco,sonuag,yarong}@microsoft.com + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Cohen et al. [Page 14] + \ No newline at end of file diff --git a/docs/draft-goland-fxpp-01.txt b/docs/draft-goland-fxpp-01.txt new file mode 100644 index 0000000..78f194b --- /dev/null +++ b/docs/draft-goland-fxpp-01.txt @@ -0,0 +1,348 @@ + + +UPnP Forum Technical Committee Yaron Y. Goland +Document: draft-goland-fxpp-01.txt CrossGain + Jeffrey C. Schlimmer + Microsoft Corporation + 19 June 2000 + + + Flexible XML Processing Profile (FXPP) + + +Status of this Memo + + This document is under review by the UPnP Forum Technical Committee. + It was previously submitted to the IETF as an Internet Draft and has + expired. This document is formatted in a manner consistent with the + IETF formatting guidelines to facilitate possible future + consideration by the IETF. + + This document is available on http://www.upnp.org. + + +Abstract + + This document provides an independent reference for the XML + processing profile developed by the WebDAV WG in [RFC2518]. It does + this by copying Section 14 and Appendix 4 as well as examples from + Appendix 3 of [RFC2518] and editing out any WebDAV specific parts. + + This document also defines handling of unknown XML attributes. + + This information has been broken out into its own independent + reference in order to make it easier for other standards to + reference just the WebDAV XML processing profile without having to + reference the entire WebDAV standard or require their readers to + understand which parts of the profile are WebDAV specific and which + parts are not. + +1. Introduction + + This document provides an independent reference for the XML + processing profile developed by the WebDAV WG in [RFC2518]. It does + this by copying Section 14 and Appendix 4 as well as examples from + Appendix 3 of [RFC2518] and editing out any WebDAV specific parts. + + This document also defines handling of unknown XML attributes. + + This information has been broken out into its own independent + reference in order to make it easier for other standards to + reference just the WebDAV XML processing profile without having to + reference the entire WebDAV standard or require their readers to + understand which parts of the profile are WebDAV specific and which + parts are not. + + + +Goland, Schlimmer 1 +UPnP Forum FXPP 19 June 2000 + + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in + this document are to be interpreted as described in [RFC2119]. + +2. XML Support Requirement + + All FXPP compliant systems MUST support [XML]. + +3. XML Ignore Rule + + All FXPP compliant XML processors (a) MUST ignore any unknown XML + element and all its children, and (b) MUST ignore any unknown XML + attribute and its value. This rule may be overridden on an element- + by-element or attribute-by-attribute basis, but implementers should + be aware that systems unfamiliar with the element or attribute will + follow the ignore rule. + +4. XML Mime Type Support + + A FXPP compliant system MUST be able to both accept and send + text/xml and application/xml. + +5. Ordering of XML Elements + + Unless the definition of a XML element explicitly specifies + otherwise the ordering of XML elements has no semantic significance + to FXPP compliant systems. + + Note to Implementers - A generic FXPP compliant XML processor will + not know which of the elements it is processing have meaningful + ordering. As such, such processors need to maintain the order of + the elements when presenting the parsed information so as not to + loose any meaningful data. + +6. XML Namespace Support + + All FXPP compliant systems MUST support the XML namespace extensions + as specified in [REC-XML-NAMES]. + + FXPP compliant XML processors MUST interpret a qualified name as a + URI constructed by appending the LocalPart to the namespace name + URI. + + Example + + + + Johnny Updraft + + + + + + +Goland, Schlimmer 2 +UPnP Forum FXPP 19 June 2000 + + + In this example, the qualified element name "del:glider" is + interpreted as the URL "http://www.del.jensen.org/glider". + + + + Johnny Updraft + + + + + Even though this example is syntactically different from the + previous example, it is semantically identical. Each instance of + the namespace name "bar" is replaced with + "http://www.del.jensen.org/" and then appended to the local name for + each element tag. The resulting tag names in this example are + exactly the same as for the previous example. + + + + Johnny Updraft + + + + + This example is semantically identical to the two previous ones. + Each instance of the namespace name "foo" is replaced with + "http://www.del.jensen.org/glide" which is then appended to the + local name for each element tag, the resulting tag names are + identical to those in the previous examples. + +7. XML Element Declaration Syntax + + The following format is recommended for FXPP compliant + specifications as a means to provide uniform declaration of XML + elements. + + Name: + Namespace: + Purpose: + Value: + + DTD + + The name is the name of the XML element. The Namespace is the + namespace the element belongs to. The purpose is a short + description of the use of the XML element. As DTDs are not very + good at expressing the format of characters inside of an XML element + when an XML element needs to contain formatted pcdata the optional + Value description will be used to provide a BNF for the character + data. At the end of the template is the ELEMENT DTD declaration for + the element. + +8. Notes on Empty XML Elements + +Goland, Schlimmer 3 +UPnP Forum FXPP 19 June 2000 + + + + XML supports two mechanisms for indicating that an XML element does + not have any content. The first is to declare an XML element of the + form . The second is to declare an XML element of the form + . The two XML elements are semantically identical. + + It is a violation of the XML specification to use the form + if the associated DTD declares the element to be EMPTY (e.g., + ). If such a statement is included, then the + empty element format, must be used. If the element is not + declared to be EMPTY, then either form or may be used + for empty elements. + +9. Notes on Illegal XML Processing + + XML is a flexible data format that makes it easy to submit data that + appears legal but in fact is not. The philosophy of "Be flexible in + what you accept and strict in what you send" still applies, but it + must not be applied inappropriately. XML is extremely flexible in + dealing with issues of white space, element ordering, inserting new + elements, etc. This flexibility does not require extension, + especially not in the area of the meaning of elements. + + There is no kindness in accepting illegal combinations of XML + elements. At best it will cause an unwanted result and at worst it + can cause real damage. + +9.1. Example - XML Syntax Error + + The following request body for a WebDAV PROPFIND method is illegal. + + + + + + + + The definition of the propfind element only allows for the allprop + or the propname element, not both. Thus the above is an error and + must be responded to with a 400 (Bad Request). + + Imagine, however, that a server wanted to be "kind" and decided to + pick the allprop element as the true element and respond to it. A + client running over a bandwidth limited line who intended to execute + a propname would be in for a big surprise if the server treated the + command as an allprop. + + Additionally, if a server were lenient and decided to reply to this + request, the results would vary randomly from server to server, with + some servers executing the allprop directive, and others executing + the propname directive. This reduces interoperability rather than + increasing it. + + +Goland, Schlimmer 4 +UPnP Forum FXPP 19 June 2000 + + +9.2. Example - Unknown XML Element + + The previous example was illegal because it contained two elements + that were explicitly banned from appearing together in the propfind + element. However, XML is an extensible language, so one can imagine + new elements being defined for use with propfind. Below is the + request body of a PROPFIND and, like the previous example, must be + rejected with a 400 (Bad Request) by a server that does not + understand the expired-props element. + + + + + + + To understand why a 400 (Bad Request) is returned let us look at the + request body as the server unfamiliar with expired-props sees it. + + + + + + As the server does not understand the expired-props element, + according to the WebDAV-specific XML processing rules specified in + section 14 of [RFC 2518], it must ignore it. Thus the server sees + an empty propfind, which by the definition of the propfind element + is illegal. + + Please note that had the extension been additive it would not + necessarily have resulted in a 400 (Bad Request). For example, + imagine the following request body for a PROPFIND: + + + + + *boss* + + + The previous example contains the fictitious element leave-out. Its + purpose is to prevent the return of any property whose name matches + the submitted pattern. If the previous example were submitted to a + server unfamiliar with leave-out, the only result would be that the + leave-out element would be ignored and a propname would be executed. + +10. References + + [RFC2119] S. Bradner. Key words for use in RFCs to Indicate + Requirement Levels. RFC 2119, March 1997. + + + +Goland, Schlimmer 5 +UPnP Forum FXPP 19 June 2000 + + + [RFC2068] R. Fielding, J. Gettys, J. Mogul, H. Frystyk, and T. + Berners-Lee. Hypertext Transfer Protocol -- HTTP/1.1. RFC 2068, + January 1997. + + [RFC2158] Y. Goland, E. Whitehead, A. Faizi, S. Carter, and D. + Jensen. HTTP Extensions for Distributed Authoring WEBDAV. RFC 2518, + February 1999. + + [XML] T. Bray, J. Paoli, C. M. Sperberg-McQueen, "Extensible Markup + Language (XML)." World Wide Web Consortium Recommendation REC-xml- + 19980210. http://www.w3.org/TR/1998/REC-xml-19980210. + +11. Author's Addresses + + Yaron Y. Goland + CrossGain + 2039 152nd Avenue NE + Redmond, WA 98052 + + + Jeffrey C. Schlimmer + Microsoft Corporation + One Microsoft Way + Redmond, WA 98052 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Goland, Schlimmer 6 \ No newline at end of file diff --git a/docs/draft-goland-http-udp-04.txt b/docs/draft-goland-http-udp-04.txt new file mode 100644 index 0000000..6296a05 --- /dev/null +++ b/docs/draft-goland-http-udp-04.txt @@ -0,0 +1,928 @@ + + +UPnP Forum Technical Committee Yaron Y. Goland +Document: draft-goland-http-udp-04.txt CrossGain + Jeffrey C. Schlimmer + Microsoft + 02 October 2000 + + + Multicast and Unicast UDP HTTP Messages + + +Status of this Memo + + This document is under review by the UPnP Forum Technical Committee. + It was previously submitted to the IETF as an Internet Draft and has + expired. This document is formatted in a manner consistent with the + IETF formatting guidelines to facilitate possible future + consideration by the IETF. + + This document is available on http://www.upnp.org. + +Abstract + + This document provides rules for encapsulating HTTP messages in + multicast and unicast UDP packets to be sent within a single + administrative scope. No provisions are made for guaranteeing + delivery beyond re-broadcasting. + +1. Introduction + + This document provides rules for encapsulating HTTP messages in + multicast and unicast UDP messages. No provisions are made for + guaranteeing delivery beyond re-broadcasting. + + This technology is motivated by applications such as SSDP where it + is expected that messages which are primarily transmitted over TCP + HTTP need to be transmitted over Multicast or Unicast UDP, because + of the unique requirements of extremely lightweight servers. + + This document will not specify a mechanism suitable for replacing + HTTP over TCP. Rather this document will define a limited mechanism + only suitable for extreme circumstances where the use of TCP is + impossible. Thus this mechanism will not have the robustness of + functionality and congestion control provided by TCP. It is expected + that in practice the mechanisms specified here in will only be used + as a means to get to TCP based HTTP communications. + +2. Changes + +2.1. Since 00 + + Divided each section of the spec into three parts, problem + definition, proposed solution and design rationale. When the spec is + ready for standardization the problem definition and design + rationale sections will be removed. Design rationale is presented in + +Goland, Schlimmer 1 +UPnP Forum UDP HTTP 24 Aug 2000 + + + question/answer form because I have found that to be very effective + in addressing design issues. + + Clarified that a HTTPU/HTTPMU URI without an abs_path translates to + "*" in the request-URI. + + Added the S header to allow request and responses to be associated. + Note that while clients aren't required to send out S headers, + servers are required to return them. + + Got rid of MM. The lower bound is always 0. + + The introduction of the S header makes proxying and caching possible + so the sections on those topics have been expanded, but they should + be considered experimental at best. + +2.2. Since 02 + + Added requirement for HTTP/1.1 as the version identifier in the + request line. (See section on HTTP Version in Request Line.) + + Removed requirement that requests without an S header MUST NOT be + responded to. (See section on Unicast UDP HTTP Messages.) + + Clarified that a server should respond to each request it receives + but not duplicate those responses. (See section on Retrying + Requests.) + + Clarified caching when responding to repeated requests. (See section + on Caching.) + + Expanded that if a server has > 1 response per HTTPMU request, it + should spread them out. (See section on MX header.) + + Tied behavior of duplicate responses with the same S header value to + the semantics of the method (was discard duplicates). (See section + on S header.) + + Outlined initial security considerations. (See section on Security.) + +2.3. Since 03 + Clarified the "no abs_path" requirement for HTTPU/HTTPMU request- + URIs. + + Clarified use of "*" as a request-URI. + + Removed requirement for HTTPU/HTTPMU servers to support "chunked" + transfer-coding. + +3. Terminology + + Since this document describes a set of extensions to the HTTP/1.1 + protocol, the augmented BNF used herein to describe protocol + +Goland, Schlimmer 2 +UPnP Forum UDP HTTP 24 Aug 2000 + + + elements is exactly the same as described in section 2.1 of + [RFC2616]. Since this augmented BNF uses the basic production rules + provided in section 2.2 of [RFC2616], these rules apply to this + document as well. + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + document are to be interpreted as described in RFC 2119 [RFC2119]. + +4. HTTPU URL + +4.1. Problem Definition + + A mechanism is needed to allow for communications that are to be + sent over Unicast UDP HTTP to be identified in the URI namespace. + +4.2. Proposed Solution + + The HTTPU URL specifies that the HTTP request be sent over unicast + UDP according to the rules laid out in this document. + + HTTPU_URL = "HTTPU:" "//" host [ ":" port ] [ abs path [ "?" query]] + + The BNF productions host, port and abs path are defined in + [RFC2616]. + + The syntax of the HTTPU URL is to be processed identically to the + HTTP URL with the exception of the transport. + + One MUST NOT assume that if a HTTP, HTTPU or HTTPMU URL are + identical in all ways save the protocol that they necessarily point + to the same resource. + +4.3. Design Rationale + +4.3.1. Why would we ever need a HTTPU/HTTPMU URL? + + Imagine one wants to tell a system to send responses over HTTPU. How + would one express this? If one uses a HTTP URL there is no way for + the system to understand that you really meant HTTPU. + +5. HTTPMU URL + +5.1. Problem Definition + + A mechanism is needed to allow for communications that are to be + sent over Multicast UDP HTTP to be identified in the URI namespace. + +5.2. Proposed Solution + + The HTTPMU URL specifies that the HTTP request that HTTP request is + to be sent over multicast UDP according to the rules laid out in + this document. + +Goland, Schlimmer 3 +UPnP Forum UDP HTTP 24 Aug 2000 + + + + HTTPMU_URL = "HTTPMU:" "//" host [ ":" port ] [ abs path [ "?" + query]] + + The BNF productions host, port and abs path are defined in + [RFC2616]. + + The syntax of the HTTPMU URL is to be processed identically to the + HTTP URL with the exception of the transport. + + One MUST NOT assume that if a HTTP, HTTPU or HTTPMU URL are + identical in all ways save the protocol that they necessarily point + to the same resource. + + If a HTTPMU URL does not have an abs path element then when the HTTP + multicast UDP request is made the request-URI MUST be "*". + + For example, HTTPU://www.foo.com would translate into a request-URI + of "*". A request-URI of HTTPU://www.foo.com/ would still translate + to the absoluteURI "HTTPU://www.foo.com/". + +5.3. Design Rationale + +5.3.1. In the HTTPMU URL a request such as http://www.foo.com is + translated to a "*" in the request-URI rather than a "/", why + isn't the same the case for HTTPU? + + A HTTPU request is a point-to-point request. There is one sender and + one receiver. Thus the semantics of the URL are identical to HTTP + with the exception of the transport. + + Generally, a HTTPMU client will want to send its request to many + receivers at once, where each receiver represents a different set of + resources. A client can specify this in the HTTPMU request itself by + using the request-URI "*". Unfortunately, there is no present way to + construct an HTTP URL that will have this request-URI. As such, a + mechanism had to be added. + +5.3.2. Why would an HTTPMU client want to use a request-URI of "*" + anyway? + + In TCP HTTP, the client will often specify a single resource on + which the request should operate. For example, a GET of the URL + http://foo.org/baz.gif should retrieve the resource at that single, + well-defined location. + + One big reason for a client to send a request over multicast UDP, + though, is the ability to send a request to many receivers at once, + even when the number of receivers is not known. + + Specifying an absoluteURI in the request, though, would defeat this; + all receivers without that exact resource would be forced to reject + the request. + +Goland, Schlimmer 4 +UPnP Forum UDP HTTP 24 Aug 2000 + + + + By specifying a request-URI of "*" client signifies that the request + "does not apply to a particular resource, but to the server itself, + and is only allowed when the method used does not necessarily apply + to a resource." [RFC 2616] + +5.3.3. So when would an HTTPMU client want to use a request-URI other + than "*"? + + This may be useful when a client knows the URI for the resource, but + not the server on which the resource lives. If the client knows + both, though, it is expected that TCP HTTP or HTTPU would be used. + + Servers MUST NOT assume that an HTTPMU request containing an + absoluteURI necessarily refers to the same resource as a HTTPU + request with the same absoluteURI. For example, servers that support + both HTTPMU and HTTPU may reject a request for a particular resource + when received through HTTPMU, but accept it when received through + HTTPU. +6. HTTP Version in Request Line + +6.1. Problem Definition + + A message format identifier is needed for the HTTPU and HTTPMU + request lines. + +6.2. Proposed Solution + + Request lines for HTTPU and HTTPMU requests MUST use HTTP/1.1 as the + version. + + Request-Line = Method SP Request-URI SP HTTP/1.1 CRLF + + The BNF production Method is defined in [RFC2616]. + +6.3. Design Rationale + +6.3.1. Why not define separate HTTPU and HTTPMU versions? + + While HTTP/1.1 does hint at underlying features (like pipelining), + it principally specifies a message format. HTTPU and HTTPMU use the + same message format as defined by HTTP/1.1. Reusing this message + format identifier enables syntactic parsing / generating of HTTPU + and HTTPMU request by existing HTTP message mungers. + +6.3.2. If the version in the request line is the same as an HTTP + request, once a request was stored, how could one distinguish an + HTTPU (or HTTPMU) request from an HTTP request? + + TBD + +7. Unicast UDP HTTP Messages + + +Goland, Schlimmer 5 +UPnP Forum UDP HTTP 24 Aug 2000 + + +7.1. Problem Definition + + A mechanism is needed to send HTTP messages over the unicast UDP + transport. + +7.2. Proposed Solution + + HTTP messages sent over unicast UDP function identically to HTTP + messages sent over TCP as defined in [RFC2616] except as specified + below. + + For brevity's sake HTTP messages sent over unicast UDP will be + referred to as HTTPU messages. + + HTTPU messages MUST fit entirely in a single UDP message. If a HTTPU + message can not be fit into a single UDP message then it MUST NOT be + sent using unicast UDP. Incomplete HTTPU messages SHOULD be ignored. + + The request-URI of a HTTPU message MUST always be fully qualified. + + A single unicast UDP message MUST only contain a single HTTPU + message. As such, an HTTPU server MAY reject messages with "chunked" + transfer-coding. + When responding to a HTTPU request with an S header the rules for + the proper handling of S headers, as specified below MUST be + followed. + +7.3. Design Rationale + + See also the subsection on the S header below for the design + rationale of the S header. + +7.3.1. Why can't a single HTTP message be sent over multiple UDP + messages? + + The ability to send unlimited size messages across the Internet is + one of the key features of TCP. The goal of this paper is not to + reinvent TCP but rather to provide a very simple emergency back up + HTTP system that can leverage UDP where TCP cannot be used. As such + features to allow a single HTTP message to span multiple UDP + messages is not provided. + +7.3.2. Why are request-URIs sent over HTTPU required to be fully + qualified? + + A relative URI in a HTTP message is assumed to be relative to a HTTP + URL. However this would clearly be inappropriate for a HTTPU or + HTTPMU message. The easiest solution would be to simply state that a + relative URI is relative to the type of message it was sent in. But + one of the goals of this draft is to allow current HTTP message + processors to be able to munch on HTTPU/HTTPMU messages and this + would cause a change to those processors. + + +Goland, Schlimmer 6 +UPnP Forum UDP HTTP 24 Aug 2000 + + + The cost of this simplification is that you repeat the host + information, once in the URI and once in the host header. + But again, taking out the host header would make a lot of existing + HTTP message munchers very unhappy. + +7.3.3. Why is the requirement for ignoring incomplete HTTPU messages a + SHOULD instead of a MUST? + + Some systems use a lot of redundant data or have good mechanisms for + handling partial data. As such they could actually do something + intelligent with a partial message. A SHOULD allows them to do this + while still making it clear that in the majority case partial + HTTPU/HTTPMU messages are going to get thrown out. + +7.3.4. Why aren't multiple HTTP messages allowed into a single UDP + message if they will fit? + + It was easier to ban it, and it didn't seem to buy us much. It was + especially worrying because it would start to convince people that + they could actually order their UDP requests in a pipelinesque + manner. It was easier to just keep things simple and ban it. + +7.3.5. Why aren't we allowed to leave off content-lengths if only a + single HTTPU message is allowed in a UDP message? + + In general we try to only change from RFC 2616 when we are forced + to. Although including a content-length is annoying it makes it easy + to use HTTP/1.1 message parsing/generating systems with this spec. + +7.3.6. Why might a HTTPU message choose to not have an S header? + + Leaving off the S header would be useful for throwaway events. In + systems with a high event rate it is usually easier to just throw + away an event rather than re-sending it. As such there is no real + benefit to correlating unnecessary responses with requests. + +7.3.7. Why isn't the MX header used on HTTPU messages? + + As HTTPU messages are point-to-point there will be exactly one + response. MX is only useful in cases, such as HTTPMU requests, where + there can be many potential responses from numerous different + clients. MX helps to prevent the client from getting creamed with + responses. + +7.3.8. Can I send 1xx responses over HTTPU? + + Yes. Error handling is identical to RFC 2616. + +8. Multicast UDP HTTP Requests + +8.1. Problem Definition + + + +Goland, Schlimmer 7 +UPnP Forum UDP HTTP 24 Aug 2000 + + + A mechanism is needed to send HTTP messages over the multicast UDP + transport. + +8.2. Proposed Solution + + HTTP messages sent over multicast UDP MUST obey all the requirements + for HTTPU messages in addition to the requirements provided below. + + For brevity's sake HTTP messages sent over multicast UDP will be + referred to as HTTPMU messages. + + Resources that support receiving multicast UDP HTTP requests MUST + honor the MX header if included in the request. + + If a resource has a single response, it MUST generate a random + number between 0 and MX that represents the number of seconds the + resource MUST wait before sending a response. If a resource has + multiple responses per request, it SHOULD send these resources + spread over the interval [0..MX]. This prevents all responses from + being sent at once. + + HTTP clients SHOULD keep listening for responses for a reasonable + delta of time after MX. That delta will be based on the type of + network the request is being sent over. This means that if a server + cannot respond to a request before MX then there is little point in + sending the response, as the client will most likely not be + listening for it. + + When used with a multicast UDP HTTP request, the "*" request-URI + means "to everyone who is listening to this IP address and port." + + A HTTPMU request without a MX header MUST NOT be responded to. + +8.3. Design Rationale + +8.3.1. Why is there a "delta" after the MX time when the client should + still be listening? + + So let's say the MX value is 5 seconds. The HTTP resource generates + a number between 0 and 5 and gets 5. After 5 seconds of waiting the + HTTP resource will send its response. + + Now for some math: + + 0.5 seconds - Time it took the client's request to reach + the HTTP resource. + 5 seconds - Time the HTTP resource waited after + receiving the message to respond, based on + the MX value. + 0.5 seconds - Time for the response to get back to the + client. + Total time elapsed - 6 seconds + + +Goland, Schlimmer 8 +UPnP Forum UDP HTTP 24 Aug 2000 + + + If the client only waits 5 seconds, the MX value, then they would + have stopped listening for this response by the time it arrived, + hence the need for the delta. + +8.3.2. What should the "delta" after MX expires be? + + Unfortunately this is an impossible question to answer. How fast is + your network? How far is the message going? Is there any congestion? + In general delta values will be set based on a combination of + heuristics and application necessity. That is, if you are displaying + information to a user any data that comes in after 20 or 30 seconds + is probably too late. + +8.3.3. When would a HTTPMU request not be responded to? + + When a HTTP resource is making a general announcement, such as "I am + here", it generally isn't useful to have everyone respond confirming + they received the message. This is especially the case given that + the HTTP resource probably doesn't know who should have received the + announcement so the absence of a HTTP client in the responses + wouldn't be meaningful. + + Whether a particular request requires a response is dependant on the + application, and is beyond the scope of this specification. + +8.3.4. Why do we require the MX header on HTTPMU requests that are to + be responded to? + + This is to prevent overloading the HTTP client. If all the HTTP + resources responded simultaneously the client would probably loose + most of the responses as its UDP buffer overflowed. + +9. Retrying Requests + +9.1. Problem Definition + + UDP is an unreliable transport with no failure indicators; as such + some mechanism is needed to reasonably increase the chance that a + HTTPU/HTTPMU message will be delivered. + +9.2. Proposed Solution + + UDP is an inherently unreliable transport and subject to routers + dropping packets without notice. Applications requiring delivery + guarantees SHOULD NOT use HTTPU or HTTPMU. + + In order to increase the probability that a HTTPU or HTTPMU message + is delivered the message MAY be repeated several times. If a + multicast resource would send a response(s) to any copy of the + request, it SHOULD send its response(s) to each copy of the request + it receives. It MUST NOT repeat its response(s) per copy of the + reuqest. + + +Goland, Schlimmer 9 +UPnP Forum UDP HTTP 24 Aug 2000 + + + In order to prevent the network from being flooded a message SHOULD + NOT be repeated more than MAX_RETRIES time. A random period of time + between 0 and MAX_RETRY_INTERVAL SHOULD be selected between each + retry to determine how long to wait before issuing the retry. + +9.3. Design Rationale + +9.3.1. Why is the requirement "applications requiring delivery + guarantees should not use HTTPU or HTTPMU" only a SHOULD and not + a MUST? + + Because there might come a day when it makes sense to use HTTPU or + HTTPMU for guaranteed delivery and there is no reason to completely + ban the possibility. + +9.3.2. Why is the requirement that a request not be repeated more than + MAX_RETRIES times a SHOULD and not a MUST? + + Local knowledge may make the limit unnecessary. For example, if one + knew that the message was being delivered using a super reliable + network then repeats are not necessary. Similarly if one knew that + the network the requests were going through were particularly + unreliable and assuming one had properly accounted for the effects + of additional messages on that congestion, one might have a good + reason to send more than MAX_RETRIES. + +9.3.3. Why SHOULD multicast resources respond to each copy of a request + it receives? + + Because the earlier responses might have been lost. + +9.3.4. Why MUST multicast resources not repeat its response(s) to each + copy of a request it receives? + + This strategy provides the lowest network loading for any desired + level of reliability, or equivalently, the highest reliability for + any specified level of network loading. + +10. Caching + +10.1. Problem Definition + + Caching is a feature that has demonstrated its usefulness in HTTP, + provisions need to be made to ensure that HTTPU/HTTPMU messages can + be cached using a consistent algorithm. + +10.2. Proposed Solution + + [Ed. Note: Never having tried to actually build a HTTPU/HTTPMU + generic cache we suspect there are some very serious gotchas here + that we just haven't found yet. This section should definitely be + treated as "under development."] + + +Goland, Schlimmer 10 +UPnP Forum UDP HTTP 24 Aug 2000 + + + Caching rules for HTTPU/HTTPMU responses are no different than + normal HTTP responses. HTTPU/HTTPMU responses are matched to their + requests through the S header value. + + When responding to a multicast request, a resource MAY cache its + response(s) and retransmit from the cache in response to duplicate + requests. + +10.3. Design Rationale + +10.3.1. Wouldn't it be useful to be able to cache HTTPU/HTTPMU requests + if they don't have responses? + + Yes, it probably would, especially if we are talking about a client- + side cache. It is probably worth investigating the use of cache + control headers on requests for this very purpose. + +11. Proxying UDP HTTP Requests + +11.1. Problem Definition + + For security or caching reasons it is sometimes necessary to place a + proxy in a message path. Provisions need to be made to ensure that + HTTPU/HTTPMU messages can be proxied. + +11.2. Proposed Solution + + [Ed. Note: This section should be considered experimental. No one + has really had to design much less implement a HTTPU/HTTPMU proxy + yet.] + + All transport independent rules for proxying, such as length of time + to cache a response, hop-by-hop header rules, etc. are the same for + HTTPU/HTTPMU as they are for HTTP messages. + + [Ed. Note: I'm not sure how far to go into the "transport + independent rules". The RFC 2616 doesn't really call them out very + well but I also don't want to have to re-write RFC 2616 spec inside + this spec.] + + The transport dependent rules, however, are different. For example, + using TCP any pipelined messages are guaranteed to be delivered in + order. There are no ordering guarantees of any form for HTTPU/HTTPMU + proxies. + + In general a proxy is required to forward a HTTPU/HTTPMU message + exactly once. It SHOULD NOT repeat the message. Rather the client is + expected to repeat the message and, as the proxy receives the + repeats, they will be forwarded. + + Note that it is acceptable, if not encouraged, for proxies to + analyze network conditions and determine the likelihood, on both + incoming and outgoing connections, of UDP messages being dropped. If + +Goland, Schlimmer 11 +UPnP Forum UDP HTTP 24 Aug 2000 + + + the likelihood is too high then it would be expected for the proxy, + taking into consideration the possibility of making congestion even + worse, to repeat requests and responses on its own. In a sense the + proxy could be thought of as a signal regenerator. This is why the + prohibition against repeating messages is a SHOULD NOT rather than a + MUST NOT. + + HTTPMU messages are sent with the assumption that the message will + only be seen by the multicast address they were sent to. Thus when a + proxy forwards the request it is expected to only do so to the + appropriate multicast channel. Note, however, that proxies may act + as multicast bridges. + + Also note that proxied HTTPMU messages with a HTTPMU URL without an + absolute path are to be treated as if they were sent to the + specified multicast address with the request-URI "*". + + If a HTTPMU request is sent with a host that does not resolve to a + multicast address then the request MUST be rejected with a 400 Bad + Request error. + + There is no requirement that a HTTPU proxy support HTTPMU or vice + versa. + +11.3. Design Rationale + +11.3.1. Why would anyone proxy HTTPMU requests? + + Proxying HTTPMU requests can be a neat way to create virtual + multicast channels. Just hook a bunch of proxies together with + unicast connections and tell the proxies' users that they are all on + the same multicast scope. + +12. HTTP Headers + +12.1. AL (Alternate Location) General Header + +12.1.1. Problem Definition + + There are many instances in which a system needs to provide location + information using multiple URIs. The LOCATION header only allows a + single URI. Therefore a mechanism is needed to allow multiple + location URIs to be returned. + +12.1.2. Proposed Solution + + AL = "AL" ":" 1*("<" AbsoluteURI ">") ; AbsoluteURI is defined in + section 3.2.1 of [RFC2616] + + The AL header is an extension of the LOCATION header whose semantics + are the same as the LOCATION header. That is, the AL header allows + one to return multiple locations where as the LOCATION header allows + one to return only one. The contents of an AL header are ordered. If + +Goland, Schlimmer 12 +UPnP Forum UDP HTTP 24 Aug 2000 + + + both a LOCATION header and an AL header are included in the same + message then the URI in the LOCATION header is to be treated as if + it were the first entry in the AL header. The AL header MAY be used + by itself but implementers should be aware that existing systems + will ignore the header. + +12.1.3. Design Rationale + +12.1.3.1. Why not just fix the BNF for the LOCATION header? + + This is tempting but the goal of maintaining compatibility with RFC + 2616's message format overrides the usefulness of this solution. + +12.2. MX Request Header + +12.2.1. Problem Definition + + A mechanism is needed to ensure that responses to HTTPMU requests do + not come at a rate greater than the requestor can handle. + +12.2.2. Proposed Solution + + MX = "MX" ":" Integer + Integer = First_digit *More_digits + First_digit = "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" + More_digits = "0" | First_digit + + The value of the MX header indicates the maximum number of seconds + that a multicast UDP HTTP resource MUST wait before it sends a + response stimulated by a multicast request. + + HTTP resources MAY treat any MX header value greater than MX_MAX as + being equal to MX_MAX. + +12.2.3. Design Rationale + +12.2.3.1. Why is MX in seconds? + + In practice wait periods shorter than a second proved useless and + longer proved too coarse. Of course as faster networks get deployed + finer-grain times would be useful, but we need a compromise + measurement that will meet everyone's needs. Seconds seem to do that + quite well. + +12.2.3.2. Couldn't MX still overload the requestor if there are too + many responders? + + Absolutely. If there are a 100,000 clients that want to respond even + pushing them over 30 seconds on a 10 Mbps link is still going to + blow both the client and the network away. However the only way to + prevent these sorts of situations is to know the current available + network bandwidth and the total number of likely responders ahead of + + +Goland, Schlimmer 13 +UPnP Forum UDP HTTP 24 Aug 2000 + + + time. Both generally prove between difficult to impossible to figure + out. So we are left with heuristics and the MX header. + +12.3. S (Sequence) General Header + +12.3.1. Problem Definition + + A mechanism is needed to associate HTTPU/HTTPMU requests with + responses, as UDP does not have any connection semantics. + +12.3.2. Proposed Solution + + S = "S" ":" AbsoluteURI + + The S header is a URI that is unique across the entire URI namespace + for all time. When an S header is sent on a HTTPU/HTTPMU request it + MUST be returned, with the same value, on the response. + + If a client receives multiple responses with the same S header then + the client MAY assume that all the responses are in response to the + same request. If the messages differ from each other then the client + MUST behave based on the specification of the request method. + +12.3.3. Design Rationale + +12.3.3.1. Why do we need the S header? + + Without an S header the only way to match requests with responses is + to ensure that there is enough information in the response to know + what request it was intended to answer. Even in that case it is + still possible to confuse which request a response goes to if it + does not have the equivalent of an S header. + +12.3.3.2. Why aren't S headers mandatory on all requests with a + response? + + Some systems don't need them. + +12.3.3.3. Why aren't S headers guaranteed to be sequential so you could + do ordering? + + Because HTTPU/HTTPMU is not interested in ordering. If one wants + ordering one should use TCP. + +12.3.3.4. Do S headers allow detecting and removing duplicates? + + Yes, for methods (like GET) that define a single responses to a + request. No, for methods (like SEARCH) that define multiple + responses to a request. + +13. Interaction of HTTP, HTTPU and HTTPMU Messages + +13.1. Problem Definition + +Goland, Schlimmer 14 +UPnP Forum UDP HTTP 24 Aug 2000 + + + + [Ed. Note: Concerns include HTTPU request redirected to HTTP? > 1 + HTTPU responses to 1 HTTPMU request?] + +13.2. Proposed Solution + + TBD + +13.3. Design Rationale + + TBD + +14. Security Considerations + + All the normal HTTP security considerations apply. + +14.1. Cookies + + There is no danger that the S header will be used as a cookie since + the client generates it, and the server returns it. (A cookie is + generated by a server and returned by the client.) +14.2. Spoofing + + Servers and multicast resources could fake S headers, but this is + not a major threat if some form of authentication over UDP is used. + (Defining authentication over UDP is beyond the scope of this + document, but briefly, one could assume the challenge and send the + authentication response as part of the HTTPU/MU request.) + +14.3. Lost Requests + + TBD + +14.4. Oversized Requests + + TBD + +15. Acknowledgements + + Thanks to John Stracke for his excellent comments. Dale Worley + devised the single-response-per-each-copy-of-request mechanism + outlined in the section on Retrying Requests. Chris Rude clarified + request URI rules. + +16. Constants + + MAX_RETRIES - 3 + + MAX_RETRY_INTERVAL - 10 seconds + + MAX_MX - 120 seconds + +17. Reference + +Goland, Schlimmer 15 +UPnP Forum UDP HTTP 24 Aug 2000 + + + + [RFC2119] S. Bradner. Key words for use in RFCs to Indicate + Requirement Levels. RFC 2119, March 1997. + + [RFC2616] R. Fielding, J. Gettys, J. C. Mogul, H. Frystyk, L. + Masinter, P. Leach and T. Berners-Lee. Hypertext Transfer Protocol - + HTTP/1.1. RFC 2616, November 1998. + +18. Authors' Address + + Yaron Y. Goland + CrossGain + 2039 152nd Avenue NE + Redmond, WA 98052 + + + Jeffrey C. Schlimmer + Microsoft Corporation + One Microsoft Way + Redmond, WA 98052 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Goland, Schlimmer 16 \ No newline at end of file diff --git a/docs/draft-leach-uuids-guids-00.txt b/docs/draft-leach-uuids-guids-00.txt new file mode 100644 index 0000000..854285a --- /dev/null +++ b/docs/draft-leach-uuids-guids-00.txt @@ -0,0 +1,1040 @@ + +Network Working Group Paul J. Leach, Microsoft +INTERNET-DRAFT Rich Salz, Open Group + +Category: Informational +Expires August 24, 1997 February 24, 1997 + + + + UUIDs and GUIDs + +STATUS OF THIS MEMO + + This document is an Internet-Draft. Internet-Drafts are working + documents of the Internet Engineering Task Force (IETF), its areas, + and its working groups. Note that other groups may also distribute + working documents as Internet-Drafts. + + Internet-Drafts are draft documents valid for a maximum of six months + and may be updated, replaced, or obsoleted by other documents at any + time. It is inappropriate to use Internet-Drafts as reference + material or to cite them other than as "work in progress". + + To learn the current status of any Internet-Draft, please check the + "1id-abstracts.txt" listing contained in the Internet-Drafts Shadow + Directories on ftp.is.co.za (Africa), nic.nordu.net (Europe), + munnari.oz.au (Pacific Rim), ds.internic.net (US East Coast), or + ftp.isi.edu (US West Coast). + + Distribution of this document is unlimited. Please send comments to + the authors or the CIFS mailing list at . + Discussions of the mailing list are archived at + . + + +ABSTRACT + + This specification defines the format of UUIDs (Universally Unique + IDentifier), also known as GUIDs (Globally Unique IDentifier). A UUID + is 128 bits long, and if generated according to the one of the + mechanisms in this document, is either guaranteed to be different + from all other UUIDs/GUIDs generated until 3400 A.D. or extremely + likely to be different (depending on the mechanism chosen). UUIDs + were originally used in the Network Computing System (NCS) [1] and + later in the Open Software Foundation's (OSF) Distributed Computing + Environment [2]. + + This specification is derived from the latter specification with the + kind permission of the OSF. + + +Table of Contents + +1. Introduction......................................................2 + + +[Page 1] + + + Internet-Draft UUIDs and GUIDs (DRAFT) 02/24/97 + + +2. Motivation........................................................2 + +3. Specification.....................................................3 + + 3.1 Format ..........................................................3 + + 3.2 Algorithms for Creating a UUID ..................................5 + + 3.2.1 Clock Sequence...............................................5 + + 3.2.2 System Reboot................................................6 + + 3.2.3 Clock Adjustment.............................................7 + + 3.2.4 Clock Overrun................................................7 + + 3.2.5 UUID Generation..............................................7 + + 3.3 String Representation of UUIDs ..................................8 + + 3.4 Comparing UUIDs .................................................9 + + 3.5 Byte order of UUIDs .............................................9 + +4. Node IDs when no IEEE 802 network card is available...............9 + +5. Obtaining IEEE 802 addresses.....................................11 + +6. Security Considerations..........................................12 + +7. Acknowledgements.................................................12 + +8. References.......................................................12 + +9. Authors' addresses...............................................12 + + + + +1. Introduction + + This specification defines the format of UUIDs (Universally Unique + IDentifiers), also known as GUIDs (Globally Unique IDentifiers). A + UUID is 128 bits long, and if generated according to the one of the + mechanisms in this document, is either guaranteed to be different + from all other UUIDs/GUIDs generated until 3400 A.D. or extremely + likely to be different (depending on the mechanism chosen). + + +2. Motivation + + One of the main reasons for using UUIDs is that no centralized + authority is required to administer them (beyond the one that + allocates IEEE 802.1 node identifiers). As a result, generation on + + Leach, Salz expires July 1997 [Page 2] + + + Internet-Draft UUIDs and GUIDs (DRAFT) 02/24/97 + + + demand can be completely automated, and they can be used for a wide + variety of purposes. The UUID generation algorithm described here + supports very high allocation rates: 10 million per second per + machine if you need it, so that they could even be used as + transaction IDs. + + UUIDs are fixed-size (128-bits) which is reasonably small relative to + other alternatives. This fixed, relatively small size lends itself + well to sorting, ordering, and hashing of all sorts, storing in + databases, simple allocation, and ease of programming in general. + + +3. Specification + + A UUID is an identifier that is unique across both space and time, + with respect to the space of all UUIDs. To be precise, the UUID + consists of a finite bit space. Thus the time value used for + constructing a UUID is limited and will roll over in the future + (approximately at A.D. 3400, based on the specified algorithm). A + UUID can be used for multiple purposes, from tagging objects with an + extremely short lifetime, to reliably identifying very persistent + objects across a network. + + The generation of UUIDs does not require that a registration + authority be contacted for each identifier. Instead, it requires a + unique value over space for each UUID generator. This spatially + unique value is specified as an IEEE 802 address, which is usually + already available to network-connected systems. This 48-bit address + can be assigned based on an address block obtained through the IEEE + registration authority. This section of the UUID specification + assumes the availability of an IEEE 802 address to a system desiring + to generate a UUID, but if one is not available section 4 specifies a + way to generate a probabilistically unique one that can not conflict + with any properly assigned IEEE 802 address. + + +3.1 Format + + The following table gives the format of a UUID. The UUID consists of + a record of 16 octets. The fields are in order of significance for + comparison purposes, with "time_low" the most significant, and "node" + the least significant. + + Field Data Octet Note + Type # + + time_low unsigned 0-3 The low field of the + 32 bit timestamp. + integer + + time_mid unsigned 4-5 The middle field of the + 16 bit timestamp. + integer + + + Leach, Salz expires July 1997 [Page 3] + + + Internet-Draft UUIDs and GUIDs (DRAFT) 02/24/97 + + + time_hi_and_version unsigned 6-7 The high field of the + 16 bit timestamp multiplexed + integer with the version number. + + clock_seq_hi_and_reserved unsigned The high field of the + 8 bit clock sequence 8 + integer multiplexed with the + variant. + + clock_seq_low unsigned 9 The low field of the + 8 bit clock sequence. + integer + + node unsigned The spatially unique + 48 bit node identifier. 10-15 + integer + + + + To minimize confusion about bit assignments within octets, the UUID + record definition is defined only in terms of fields that are + integral numbers of octets. The version number is in the most + significant 4 bits of the time stamp (time_hi), and the variant field + is in the most significant 3 bits of the clock sequence + (clock_seq_high). + + The timestamp is a 60 bit value. For UUID version 1, this is + represented by Coordinated Universal Time (UTC) as a count of 100- + nanosecond intervals since 00:00:00.00, 15 October 1582 (the date of + Gregorian reform to the Christian calendar). + + The following table lists currently defined versions of the UUID. + + Msb0 Msb1 Msb2 Msb3 Version Description + + 0 0 0 1 1 The version specified + in this document. + + 0 0 1 0 2 Reserved for DCE + Security version, with + embedded POSIX UIDs. + + The variant field determines the layout of the UUID. The structure of + UUIDs is fixed across different versions within a variant, but not + across variants; hence, other UUID variants may not interoperate with + the UUID variant specified in this document. Interoperability of + UUIDs is defined as the applicability of operations such as string + conversion, comparison, and lexical ordering across different + systems. The variant field consists of a variable number of the msbs + of the clock_seq_hi_and_reserved field. + + The following table lists the contents of the variant field. + + + + Leach, Salz expires July 1997 [Page 4] + + + Internet-Draft UUIDs and GUIDs (DRAFT) 02/24/97 + + + Msb0 Msb1 Msb2 Description + + 0 - - Reserved, NCS backward compatibility. + + 1 0 - The variant specified in this document. + + 1 1 0 Reserved, Microsoft Corporation GUID. + + 1 1 1 Reserved for future definition. + + The clock sequence is required to detect potential losses of + monotonicity of the clock. Thus, this value marks discontinuities and + prevents duplicates. An algorithm for generating this value is + outlined in the _Clock Sequence_ section below. + + The clock sequence is encoded in the 6 least significant bits of the + clock_seq_hi_and_reserved field and in the clock_seq_low field. + + The node field consists of the IEEE address, usually the host + address. For systems with multiple IEEE 802 nodes, any available node + address can be used. The lowest addressed octet (octet number 10) + contains the global/local bit and the unicast/multicast bit, and is + the first octet of the address transmitted on an 802.3 LAN. + + Depending on the network data representation, the multi-octet + unsigned integer fields are subject to byte swapping when + communicated between different endian machines. + + The nil UUID is special form of UUID that is specified to have all + 128 bits set to 0 (zero). + + +3.2 Algorithms for Creating a UUID + + Various aspects of the algorithm for creating a UUID are discussed in + the following sections. UUID generation requires a guarantee of + uniqueness within the node ID for a given variant and version. + Interoperability is provided by complying with the specified data + structure. To prevent possible UUID collisions, which could be caused + by different implementations on the same node, compliance with the + algorithm specified here is required. + + +3.2.1 Clock Sequence + The clock sequence value must be changed whenever: + + - the UUID generator detects that the local value of UTC has gone + backward. + + - the UUID generator has lost its state of the last value of UTC + used, indicating that time may have gone backward; this is typically + the case on reboot. + + + + Leach, Salz expires July 1997 [Page 5] + + + Internet-Draft UUIDs and GUIDs (DRAFT) 02/24/97 + + + While a node is operational, the UUID service always saves the last + UTC used to create a UUID. Each time a new UUID is created, the + current UTC is compared to the saved value and if either the current + value is less (the non-monotonic clock case) or the saved value was + lost, then the clock sequence is incremented modulo 16,384, thus + avoiding production of duplicate UUIDs. + + The clock sequence must be initialized to a random number to minimize + the correlation across systems. This provides maximum protection + against node identifiers that may move or switch from system to + system rapidly. The initial value MUST NOT be correlated to the node + identifier. + + The rule of initializing the clock sequence to a random value is + waived if, and only if all of the following are true: + + - The clock sequence value is stored in non-volatile storage. + + - The system is manufactured such that the IEEE address ROM is + designed to be inseparable from the system by either the user or + field service, so that it cannot be moved to another system. + + - The manufacturing process guarantees that only new IEEE address + ROMs are used. + + - Any field service, remanufacturing or rebuilding process that could + change the value of the clock sequence must reinitialise it to a + random value. + + In other words, the system constraints prevent duplicates caused by + possible migration of the IEEE address, while the operational system + itself can protect against non-monotonic clocks, except in the case + of field service intervention. At manufacturing time, such a system + may initialise the clock sequence to any convenient value. + + +3.2.2 System Reboot + There are two possibilities when rebooting a system: + + - the UUID generator state - the last UTC, adjustment, and clock + sequence - of the UUID service has been restored from non-volatile + store + + - the state of the last UTC or adjustment has been lost. + + If the state variables have been restored, the UUID generator just + continues as normal. Alternatively, if the state variables cannot be + restored, they are reinitialised, and the clock sequence is changed. + + If the clock sequence is stored in non-volatile store, it is + incremented; otherwise, it is reinitialised to a new random value. + + + + + Leach, Salz expires July 1997 [Page 6] + + + Internet-Draft UUIDs and GUIDs (DRAFT) 02/24/97 + + +3.2.3 Clock Adjustment + UUIDs may be created at a rate greater than the system clock + resolution. Therefore, the system must also maintain an adjustment + value to be added to the lower-order bits of the time. Logically, + each time the system clock ticks, the adjustment value is cleared. + Every time a UUID is generated, the current adjustment value is read + and incremented atomically, then added to the UTC time field of the + UUID. + + +3.2.4 Clock Overrun + The 100 nanosecond granularity of time should prove sufficient even + for bursts of UUID creation in high-performance multiprocessors. If a + system overruns the clock adjustment by requesting too many UUIDs + within a single system clock tick, the UUID service may raise an + exception, handled in a system or process-dependent manner either by: + + - terminating the requester + + - reissuing the request until it succeeds + + - stalling the UUID generator until the system clock catches up. + + If the processors overrun the UUID generation frequently, additional + node identifiers and clocks may need to be added. + + +3.2.5 UUID Generation + UUIDs are generated according to the following algorithm: + + - Determine the values for the UTC-based timestamp and clock sequence + to be used in the UUID, as described above. + + - For the purposes of this algorithm, consider the timestamp to be a + 60-bit unsigned integer and the clock sequence to be a 14-bit + unsigned integer. Sequentially number the bits in a field, starting + from 0 (zero) for the least significant bit. + + - Set the time_low field equal to the least significant 32-bits (bits + numbered 0 to 31 inclusive) of the time stamp in the same order of + significance. + + - Set the time_mid field equal to the bits numbered 32 to 47 + inclusive of the time stamp in the same order of significance. + + - Set the 12 least significant bits (bits numbered 0 to 11 inclusive) + of the time_hi_and_version field equal to the bits numbered 48 to 59 + inclusive of the time stamp in the same order of significance. + + - Set the 4 most significant bits (bits numbered 12 to 15 inclusive) + of the time_hi_and_version field to the 4-bit version number + corresponding to the UUID version being created, as shown in the + table above. + + + Leach, Salz expires July 1997 [Page 7] + + + Internet-Draft UUIDs and GUIDs (DRAFT) 02/24/97 + + + - Set the clock_seq_low field to the 8 least significant bits (bits + numbered 0 to 7 inclusive) of the clock sequence in the same order of + significance. + + - Set the 6 least significant bits (bits numbered 0 to 5 inclusive) + of the clock_seq_hi_and_reserved field to the 6 most significant bits + (bits numbered 8 to 13 inclusive) of the clock sequence in the same + order of significance. + + - Set the 2 most significant bits (bits numbered 6 and 7) of the + clock_seq_hi_and_reserved to 0 and 1, respectively. + + - Set the node field to the 48-bit IEEE address in the same order of + significance as the address. + + +3.3 String Representation of UUIDs + + For use in human readable text, a UUID string representation is + specified as a sequence of fields, some of which are separated by + single dashes. + + Each field is treated as an integer and has its value printed as a + zero-filled hexadecimal digit string with the most significant digit + first. The hexadecimal values a to f inclusive are output as lower + case characters, and are case insensitive on input. The sequence is + the same as the UUID constructed type. + + The formal definition of the UUID string representation is provided + by the following extended BNF: + + UUID = "-" "-" + "-" + + "-" + time_low = 4* + time_mid = 2* + time_high_and_version = 2* + clock_seq_and_reserved = + clock_seq_low = + node = 6* + hexDigit = + "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" + | "a" | "b" | "c" | "d" | "e" | "f" + | "A" | "B" | "C" | "D" | "E" | "F" + + The following is an example of the string representation of a UUID: + + f81d4fae-7dec-11d0-a765-00a0c91e6bf6 + + + + + + Leach, Salz expires July 1997 [Page 8] + + + Internet-Draft UUIDs and GUIDs (DRAFT) 02/24/97 + + +3.4 Comparing UUIDs + + Consider each field of the UUID to be an unsigned integer as shown in + the table in section 3.1. Then, to compare a pair of UUIDs, + arithmetically compare the corresponding fields from each UUID in + order of significance and according to their data type. Two UUIDs are + equal if and only if all the corresponding fields are equal. The + first of two UUIDs follows the second if the most significant field + in which the UUIDs differ is greater for the first UUID. The first of + a pair of UUIDs precedes the second if the most significant field in + which the UUIDs differ is greater for the second UUID. + + +3.5 Byte order of UUIDs + + UUIDs may be transmitted in many different forms, some of which may + be dependent on the presentation or application protocol where the + UUID may be used. In such cases, the order, sizes and byte orders of + the UUIDs fields on the wire will depend on the relevant presentation + or application protocol. However, it is strongly RECOMMENDED that + the order of the fields conform with ordering set out in section 3.1 + above. Furthermore, the payload size of each field in the application + or presentation protocol MUST be large enough that no information + lost in the process of encoding them for transmission. + + In the absence of explicit application or presentation protocol + specification to the contrary, a UUID is encoded as a 128-bit object, + as follows: the fields are encoded as 16 octets, with the sizes and + order of the fields defined in section 3.1, and with each field + encoded with the Most Significant Byte first (also known as network + byte order). + + 0 1 2 3 + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | time_high | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | time_mid | time_hi_and_version | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + |clk_seq_hi_res | clk_seq_low | node (0-1) | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | node (2-5) | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + + + +4. Node IDs when no IEEE 802 network card is available + + If a system wants to generate UUIDs but has no IEE 802 compliant + network card or other source of IEEE 802 addresses, then this section + describes how to generate one. + + The ideal solution is to obtain a 47 bit cryptographic quality random + number, and use it as the low 47 bits of the node ID, with the most + + Leach, Salz expires July 1997 [Page 9] + + + Internet-Draft UUIDs and GUIDs (DRAFT) 02/24/97 + + + significant bit of the first octet of the node ID set to 1. This bit + is the unicast/multicast bit, which will never be set in IEEE 802 + addresses obtained from network cards; hence, there can never be a + conflict between UUIDs generated by machines with and without network + cards. + + If a system does not have a primitive to generate cryptographic + quality random numbers, then in most systems there are usually a + fairly large number of sources of randomness available from which one + can be generated. Such sources are system specific, but often + include: + + - the percent of memory in use + + - the size of main memory in bytes + + - the amount of free main memory in bytes + + - the size of the paging or swap file in bytes + + - free bytes of paging or swap file + + - the total size of user virtual address space in bytes + + - the total available user address space bytes + + - the size of boot disk drive in bytes + + - the free disk space on boot drive in bytes + + - the current time + + - the amount of time since the system booted + + - the individual sizes of files in various system directories + + - the creation, last read, and modification times of files in various + system directories + + - the utilization factors of various system resources (heap, etc.) + + - current mouse cursor position + + - current caret position + + - current number of running processes, threads + + - handles or IDs of the desktop window and the active window + + - the value of stack pointer of the caller + + - the process and thread ID of caller + + + + Leach, Salz expires July 1997 [Page 10] + + + Internet-Draft UUIDs and GUIDs (DRAFT) 02/24/97 + + + - various processor architecture specific performance counters + (instructions executed, cache misses, TLB misses) + + (Note that it precisely the above kinds of sources of randomness that + are used to seed cryptographic quality random number generators on + systems without special hardware for their construction.) + + In addition, items such as the computer's name and the name of the + operating system, while not strictly speaking random, will help + differentiate the results from those obtained by other systems. + + The exact algorithm to generate a node ID using these data is system + specific, because both the data available and the functions to obtain + them are often very system specific. However, assuming that one can + concatenate all the values from the randomness sources into a buffer, + and that a cryptographic hash function such as MD5 [3] is available, + the following code will compute a node ID: + + #include + #define HASHLEN 16 + + void GenNodeID( + unsigned char * pDataBuf, // concatenated "randomness values" + long cData, // size of randomness values + unsigned char NodeID[6] // node ID + ) + { + int i, j, k; + unsigned char Hash[HASHLEN]; + MD_CTX context; + + MDInit (&context); + MDUpdate (&context, pDataBuf, cData); + MDFinal (Hash, &context); + + for (j = 0; j<6; j++) NodeId[j]=0; + for (i = 0,j = 0; i < HASHLEN; i++) { + NodeID[j++] ^= Hash[i]; + if (j == 6) j = 0; + }; + NodeID[0] |= 0x80; // set the multicast bit + }; + + Other hash functions, such as SHA-1 [4], can also be used (in which + case HASHLEN will be 20). The only requirement is that the result be + suitably random _ in the sense that the outputs from a set uniformly + distributed inputs are themselves uniformly distributed, and that a + single bit change in the input can be expected to cause half of the + output bits to change. + + +5. Obtaining IEEE 802 addresses + + The following URL + + Leach, Salz expires July 1997 [Page 11] + + + Internet-Draft UUIDs and GUIDs (DRAFT) 02/24/97 + + + + + + http://stdsbbs.ieee.org/products/oui/forms/index.html + + contains information on how to obtain an IEEE 802 address block. Cost + is $1000 US. + + +6. Security Considerations + + It should not be assumed that UUIDs are hard to guess; they should + not be used as capabilities. + + +7. Acknowledgements + + This document draws heavily on the OSF DCE specification for UUIDs. + Ted Ts'o provided helpful comments, especially on the byte ordering + section which we mostly plagiarized from a proposed wording he + supplied (all errors in that section are our responsibility, + however). + + +8. References + + [1] Lisa Zahn, et. al., Network Computing Architecture, Prentice + Hall, Englewood Cliffs, NJ, 1990 + + [2] DCE: Remote Procedure Call, Open Group CAE Specification C309 + ISBN 1-85912-041-5 28cm. 674p. pbk. 1,655g. 8/94 + + [3] R. Rivest, RFC 1321, "The MD5 Message-Digest Algorithm", + 04/16/1992. + + [4] SHA Spec - TBD + + +9. Authors' addresses + + Paul J. Leach + Microsoft + 1 Microsoft Way + Redmond, WA, 98052, U.S.A. + Email: + + paulle@microsoft.com + + Rich Salz + The Open Group + 11 Cambridge Center + Cambridge, MA 02142, U.S.A. + Email r.salz@opengroup.org + + + + +Appendix A _ UUID Reference Implementation + + /* + ** Copyright (c) 1990- 1993, 1996 Open Software Foundation, Inc. + + Leach, Salz expires July 1997 [Page 12] + + + Internet-Draft UUIDs and GUIDs (DRAFT) 02/24/97 + + + ** Copyright (c) 1989 by Hewlett-Packard Company, Palo Alto, Ca. & + ** Digital Equipment Corporation, Maynard, Mass. + ** To anyone who acknowledges that this file is provided "AS IS" + ** without any express or implied warranty: permission to use, copy, + ** modify, and distribute this file for any purpose is hereby + ** granted without fee, provided that the above copyright notices and + ** this notice appears in all source code copies, and that none of + ** the names of Open Software Foundation, Inc., Hewlett-Packard + ** Company, or Digital Equipment Corporation be used in advertising + ** or publicity pertaining to distribution of the software without + ** specific, written prior permission. Neither Open Software + ** Foundation, Inc., Hewlett-Packard Company, nor Digital Equipment + ** Corporation makes any representations about the suitability of + ** this software for any purpose. + */ + #include + #include + + typedef unsigned long unsigned32; + typedef unsigned short unsigned16; + typedef unsigned char unsigned8; + typedef unsigned char byte; + + #define CLOCK_SEQ_LAST 0x3FFF + #define RAND_MASK CLOCK_SEQ_LAST + + typedef struct _uuid_t { + unsigned32 time_low; + unsigned16 time_mid; + unsigned16 time_hi_and_version; + unsigned8 clock_seq_hi_and_reserved; + unsigned8 clock_seq_low; + byte node[6]; + } uuid_t; + + typedef struct _unsigned64_t { + unsigned32 lo; + unsigned32 hi; + } unsigned64_t; + + /* + ** Add two unsigned 64-bit long integers. + */ + #define ADD_64b_2_64b(A, B, sum) \ + { \ + if (!(((A)->lo & 0x80000000UL) ^ ((B)->lo & 0x80000000UL))) { + \ + if (((A)->lo&0x80000000UL)) { \ + (sum)->lo = (A)->lo + (B)->lo; \ + (sum)->hi = (A)->hi + (B)->hi + 1; \ + } \ + else { \ + (sum)->lo = (A)->lo + (B)->lo; \ + (sum)->hi = (A)->hi + (B)->hi; \ + + Leach, Salz expires July 1997 [Page 13] + + + Internet-Draft UUIDs and GUIDs (DRAFT) 02/24/97 + + + } \ + } \ + else { \ + (sum)->lo = (A)->lo + (B)->lo; \ + (sum)->hi = (A)->hi + (B)->hi; \ + if (!((sum)->lo&0x80000000UL)) (sum)->hi++; \ + } \ + } + + /* + ** Add a 16-bit unsigned integer to a 64-bit unsigned integer. + */ + #define ADD_16b_2_64b(A, B, sum) \ + { \ + (sum)->hi = (B)->hi; \ + if ((B)->lo & 0x80000000UL) { \ + (sum)->lo = (*A) + (B)->lo; \ + if (!((sum)->lo & 0x80000000UL)) (sum)->hi++; \ + } \ + else \ + (sum)->lo = (*A) + (B)->lo; \ + } + + /* + ** Global variables. + */ + static unsigned64_t time_last; + static unsigned16 clock_seq; + + static void + mult32(unsigned32 u, unsigned32 v, unsigned64_t *result) + { + /* Following the notation in Knuth, Vol. 2. */ + unsigned32 uuid1, uuid2, v1, v2, temp; + + uuid1 = u >> 16; + uuid2 = u & 0xFFFF; + v1 = v >> 16; + v2 = v & 0xFFFF; + temp = uuid2 * v2; + result->lo = temp & 0xFFFF; + temp = uuid1 * v2 + (temp >> 16); + result->hi = temp >> 16; + temp = uuid2 * v1 + (temp & 0xFFFF); + result->lo += (temp & 0xFFFF) << 16; + result->hi += uuid1 * v1 + (temp >> 16); + } + + static void + get_system_time(unsigned64_t *uuid_time) + { + struct timeval tp; + unsigned64_t utc, usecs, os_basetime_diff; + + + Leach, Salz expires July 1997 [Page 14] + + + Internet-Draft UUIDs and GUIDs (DRAFT) 02/24/97 + + + gettimeofday(&tp, (struct timezone *)0); + mult32((long)tp.tv_sec, 10000000, &utc); + mult32((long)tp.tv_usec, 10, &usecs); + ADD_64b_2_64b(&usecs, &utc, &utc); + + /* Offset between UUID formatted times and Unix formatted times. + * UUID UTC base time is October 15, 1582. + * Unix base time is January 1, 1970. */ + os_basetime_diff.lo = 0x13814000; + os_basetime_diff.hi = 0x01B21DD2; + ADD_64b_2_64b(&utc, &os_basetime_diff, uuid_time); + } + + /* + ** See "The Multiple Prime Random Number Generator" by Alexander + ** Hass pp. 368-381, ACM Transactions on Mathematical Software, + ** 12/87. + */ + static unsigned32 rand_m; + static unsigned32 rand_ia; + static unsigned32 rand_ib; + static unsigned32 rand_irand; + + static void + true_random_init(void) + { + unsigned64_t t; + unsigned16 seed; + + /* Generating our 'seed' value Start with the current time, but, + * since the resolution of clocks is system hardware dependent and + * most likely coarser than our resolution (10 usec) we 'mixup' the + * bits by xor'ing all the bits together. This will have the effect + * of involving all of the bits in the determination of the seed + * value while remaining system independent. Then for good measure + * to ensure a unique seed when there are multiple processes + * creating UUIDs on a system, we add in the PID. + */ + rand_m = 971; + rand_ia = 11113; + rand_ib = 104322; + rand_irand = 4181; + get_system_time(&t); + seed = t.lo & 0xFFFF; + seed ^= (t.lo >> 16) & 0xFFFF; + seed ^= t.hi & 0xFFFF; + seed ^= (t.hi >> 16) & 0xFFFF; + rand_irand += seed + getpid(); + } + + static unsigned16 + true_random(void) + { + if ((rand_m += 7) >= 9973) + + Leach, Salz expires July 1997 [Page 15] + + + Internet-Draft UUIDs and GUIDs (DRAFT) 02/24/97 + + + rand_m -= 9871; + if ((rand_ia += 1907) >= 99991) + rand_ia -= 89989; + if ((rand_ib += 73939) >= 224729) + rand_ib -= 96233; + rand_irand = (rand_irand * rand_m) + rand_ia + rand_ib; + return (rand_irand >> 16) ^ (rand_irand & RAND_MASK); + } + + /* + ** Startup initialization routine for the UUID module. + */ + void + uuid_init(void) + { + true_random_init(); + get_system_time(&time_last); + #ifdef NONVOLATILE_CLOCK + clock_seq = read_clock(); + #else + clock_seq = true_random(); + #endif + } + + static int + time_cmp(unsigned64_t *time1, unsigned64_t *time2) + { + if (time1->hi < time2->hi) return -1; + if (time1->hi > time2->hi) return 1; + if (time1->lo < time2->lo) return -1; + if (time1->lo > time2->lo) return 1; + return 0; + } + + static void new_clock_seq(void) + { + clock_seq = (clock_seq + 1) % (CLOCK_SEQ_LAST + 1); + if (clock_seq == 0) clock_seq = 1; + #ifdef NONVOLATILE_CLOCK + write_clock(clock_seq); + #endif + } + + void uuid_create(uuid_t *uuid) + { + static unsigned64_t time_now; + static unsigned16 time_adjust; + byte eaddr[6]; + int got_no_time = 0; + + get_ieee_node_identifier(&eaddr); /* TO BE PROVIDED */ + + do { + get_system_time(&time_now); + + Leach, Salz expires July 1997 [Page 16] + + + Internet-Draft UUIDs and GUIDs (DRAFT) 02/24/97 + + + switch (time_cmp(&time_now, &time_last)) { + case -1: + /* Time went backwards. */ + new_clock_seq(); + time_adjust = 0; + break; + case 1: + time_adjust = 0; + break; + default: + if (time_adjust == 0x7FFF) + /* We're going too fast for our clock; spin. */ + got_no_time = 1; + else + time_adjust++; + break; + } + } while (got_no_time); + + time_last.lo = time_now.lo; + time_last.hi = time_now.hi; + + if (time_adjust != 0) { + ADD_16b_2_64b(&time_adjust, &time_now, &time_now); + } + + /* Construct a uuid with the information we've gathered + * plus a few constants. */ + uuid->time_low = time_now.lo; + uuid->time_mid = time_now.hi & 0x0000FFFF; + uuid->time_hi_and_version = (time_now.hi & 0x0FFF0000) >> 16; + uuid->time_hi_and_version |= (1 << 12); + uuid->clock_seq_low = clock_seq & 0xFF; + uuid->clock_seq_hi_and_reserved = (clock_seq & 0x3F00) >> 8; + uuid->clock_seq_hi_and_reserved |= 0x80; + memcpy(uuid->node, &eaddr, sizeof uuid->node); + } + + + + + + + + + + + + + + + + + + + Leach, Salz expires July 1997 [Page 17] diff --git a/docs/draft_cai_ssdp_v1_03.txt b/docs/draft_cai_ssdp_v1_03.txt new file mode 100644 index 0000000..f58b491 --- /dev/null +++ b/docs/draft_cai_ssdp_v1_03.txt @@ -0,0 +1,1044 @@ +Internet Engineering Task Force Yaron Y. Goland +INTERNET DRAFT Ting Cai + Paul Leach + Ye Gu + Microsoft Corporation + Shivaun Albright + Hewlett-Packard Company + October 28, 1999 + Expires April 2000 + + + + Simple Service Discovery Protocol/1.0 + Operating without an Arbiter + + + + +Status of this Memo + + This document is an Internet-Draft and is in full conformance with + all provisions of Section 10 of RFC2026. + + Internet-Drafts are working documents of the Internet Engineering + Task Force (IETF), its areas, and its working groups. Note that + other groups may also distribute working documents as Internet- + Drafts. + + Internet-Drafts are draft documents valid for a maximum of six + months and may be updated, replaced, or obsoleted by other documents + at any time. It is inappropriate to use Internet- Drafts as + reference material or to cite them other than as "work in progress." + + The list of current Internet-Drafts can be accessed at + http://www.ietf.org/ietf/1id-abstracts.txt + + The list of Internet-Draft Shadow Directories can be accessed at + http://www.ietf.org/shadow.html. + + Please send comments to the SSDP mailing list. Subscription + information for the SSDP mailing list is available at + http://www.upnp.org/resources/ssdpmail.htm. + +Abstract + + The Simple Service Discovery Protocol (SSDP) provides a mechanism + where by network clients, with little or no static configuration, + can discover network services. SSDP accomplishes this by providing + for multicast discovery support as well as server based notification + and discovery routing. + +Table of Contents + + Status of this Memo................................................1 + Abstract...........................................................1 + + +Goland et al. [Page 1] +INTERNET-DRAFT SSDP/V1 October 28, 1999 + + + Table of Contents..................................................1 + 1. Changes Since 02.............................................3 + 2. Introduction.................................................3 + 2.1. Problem Statement.........................................3 + 2.2. Proposed Solution.........................................4 + 2.2.1. Message Flow on the SSDP Multicast Channel...........4 + 2.2.2. SSDP Discovery Information Caching Model.............4 + 2.3. Design Rationale..........................................5 + 2.3.1. Message Flow on the SSDP Multicast Channel...........5 + 2.3.2. SSDP Discovery Information Caching Model.............7 + 3. Terminology..................................................8 + 4. SSDP Discovery Requests......................................8 + 4.1. Problem Statement.........................................8 + 4.2. Proposed Solution.........................................8 + 4.3. Design Rationale.........................................10 + 4.3.1. Why is the ST header so limited? Why doesn't it support + at least and/or/not? Why not name/value pair searching?.....10 + 4.3.2. If we are using the SEARCH method why aren't you using + the DASL search syntax?.....................................10 + 4.3.3. Why can we only specify one search type in the ST + header of a ssdp:discover request?..........................10 + 4.3.4. Why do we only provide support for multicast UDP, not + TCP, ssdp:discover requests?................................10 + 4.3.5. Why do we require that responses without caching + information not be cached at all?...........................11 + 5. SSDP Presence Announcements.................................11 + 5.1. Problem Statement........................................11 + 5.2. Proposed Solution........................................11 + 5.2.1. ssdp:alive..........................................11 + 5.2.2. ssdp:byebye.........................................12 + 5.3. Design Rationale.........................................13 + 5.3.1. Why are we using GENA NOTIFY requests?..............13 + 5.3.2. Why is there no response to the ssdp:alive/ssdp:byebye + requests sent to the SSDP multicast channel/port?...........13 + 5.3.3. Could NTS values other than ssdp:alive/ssdp:byebye be + sent to the SSDP multicast channel/port?....................13 + 5.3.4. Why do we include the NT header on ssdp:byebye + requests?...................................................13 + 5.3.5. Shouldn't the NT and NTS values be switched?........13 + 6. SSDP Auto-Shut-Off Algorithm................................13 + 6.1. Problem Statement........................................13 + 6.2. Proposed Solution........................................13 + 6.3. Design Rationale.........................................14 + 6.3.1. Why do we need an auto-shut-off algorithm?..........14 + 6.3.2. Why not just require everyone to support directories + and thus get around the scaling issue?......................15 + 7. ssdp:all....................................................15 + 7.1. Problem Statement........................................15 + 7.2. Proposed Solution........................................15 + 7.3. Design Rationale.........................................16 + 7.3.1. Why would anyone want to enumerate all services?....16 + 8. SSDP Reserved Multicast Channel.............................16 + + +Goland et al. [Page 2] +INTERNET-DRAFT SSDP/V1 October 28, 1999 + + + 8.1. Problem Statement........................................16 + 8.2. Proposed Solution........................................16 + 8.3. Design Rationale.........................................16 + 8.3.1. Why didn't SSDP just get a static local administrative + scope address rather than a relative address?...............16 + 8.3.2. Why does SSDP need to use a port other than 80?.....16 + 9. HTTP Headers................................................17 + 9.1. USN Header...............................................17 + 9.2. ST Header................................................17 + 10. Security Considerations.....................................17 + 11. IANA Considerations.........................................17 + 12. Appendix - Constants........................................17 + 13. Acknowledgements............................................17 + 14. References..................................................17 + 15. Author's Addresses..........................................18 + +1. Changes Since 02 + + The entire specification has been extensively re-written. As such + the reader is advised to re-read the entire specification rather + than to just look for particular changes. + + Removed the arbiter and related functionality. + + Spec used to contain both ssdp:discover and ssdp:discovery, settled + on ssdp:discover. + + Changed SSDP multicast message examples to use the reserved relative + multicast address "5" provided by IANA. In the local administrative + scope, the only scope currently used by SSDP, this address + translates to 239.255.255.250. + + An application has been made for a reserved port for SSDP but no + response from IANA has been received. + +2. Introduction + + [Ed. Note: In my experience, one of the best ways to enable a + specification to be quickly and successfully developed is to provide + a problem statement, a proposed solution and a design rationale. I + came across this three-part design structure when Larry Masinter + proposed it to the WebDAV WG. To that end, I have divided this spec + in a similar manner. Once the specification is sufficiently mature, + the problem statement and design rationale sections will be placed + in a separate document and the proposed solutions will be presented + for standardization.] + + This document assumes the reader is very familiar with [RFC2616], + [HTTPUDP], [GENA], [MAN] and [RFC2365]. + +2.1. Problem Statement + + + +Goland et al. [Page 3] +INTERNET-DRAFT SSDP/V1 October 28, 1999 + + + A mechanism is needed to allow HTTP clients and HTTP resources to + discover each other in local area networks. That is, a HTTP client + may need a particular service that may be provided by one or more + HTTP resources. The client needs a mechanism to find out which HTTP + resources provide the service the client desires. + + For the purposes of this specification the previously mentioned HTTP + client will be referred to as a SSDP client. The previous mentioned + HTTP resource will be referred to as a SSDP service. + + In the simplest case this discovery mechanism needs to work without + any configuration, management or administration. For example, if a + user sets up a home network or a small company sets up a local area + network they must not be required to configure SSDP before SSDP can + be used to help them discover SSDP services in the form of Printers, + Scanners, Fax Machines, etc. + + It is a non-goal for SSDP to provide for multicast scope bridging or + for advanced query facilities. + +2.2. Proposed Solution + +2.2.1. Message Flow on the SSDP Multicast Channel + + The following is an overview of the messages used to implement SSDP. + + SSDP clients discover SSDP services using the reserved local + administrative scope multicast address 239.255.255.250 over the SSDP + port [NOT YET ALLOCATED BY IANA]. + + For brevity's sake the SSDP reserved local administrative scope + multicast address and port will be referred to as the SSDP multicast + channel/Port. + + Discovery occurs when a SSDP client multicasts a HTTP UDP discovery + request to the SSDP multicast channel/Port. SSDP services listen to + the SSDP multicast channel/Port in order to hear such discovery + requests. If a SSDP service hears a HTTP UDP discovery request that + matches the service it offers then it will respond using a unicast + HTTP UDP response. + + SSDP services may send HTTP UDP notification announcements to the + SSDP multicast channel/port to announce their presence. + + Hence two types of SSDP requests will be sent across the SSDP + multicast channel/port. The first are discovery requests, a SSDP + client looking for SSDP services. The second are presence + announcements, a SSDP service announcing its presence. + +2.2.2. SSDP Discovery Information Caching Model + + + + +Goland et al. [Page 4] +INTERNET-DRAFT SSDP/V1 October 28, 1999 + + + The following provides an overview of the data provided in a SSDP + system. + + Services are identified by a unique pairing of a service type URI + and a Unique Service Name (USN) URI. + + Service types identify a type of service, such as a refrigerator, + clock/radio, what have you. The exact meaning of a service type is + outside the scope of this specification. For the purposes of this + specification, a service type is an opaque identifier that + identifies a particular type of service. + + A USN is a URI that uniquely identifies a particular instance of a + service. USNs are used to differentiate between two services with + the same service type. + + In addition to providing both a service type and a USN, discovery + results and presence announcements also provide expiration and + location information. + + Location information identifies how one should contact a particular + service. One or more location URIs may be included in a discovery + response or a presence announcement. + + Expiration information identifies how long a SSDP client should keep + information about the service in its cache. Once the entry has + expired it is to be removed from the SSDP client's cache. + + Thus a SSDP client service cache might look like: + + USN URI | Service Type URI | Expiration | Location + -----------------|------------------|------------|------------------ + upnp:uuid:k91... | upnp:clockradio | 3 days | http://foo.com/cr + -----------------|------------------|------------|------------------ + uuid:x7z... | ms:wince | 1 week | http://msce/win + -----------------|------------------|------------|------------------ + + In the previous example both USN URIs are actually UUIDs such as + upnp:uuid:k91d4fae-7dec-11d0-a765-00a0c91c6bf6. + + If an announcement or discovery response is received that has a USN + that matches an entry already in the cache then the information in + the cache is to be completely replaced with the information in the + announcement or discovery response. + +2.3. Design Rationale + + [Ed. Note: In my own experience one of the most powerful ways to + explain design rationale is in a question/answer form. Therefore I + have used that format here.] + +2.3.1. Message Flow on the SSDP Multicast Channel + + +Goland et al. [Page 5] +INTERNET-DRAFT SSDP/V1 October 28, 1999 + + + + Please see section 8.3 for more design rationale behind our use of + multicasting. + +2.3.1.1. Why use multicast for communication? + + We needed a solution for communication that would work even if there + was no one around to configure things. The easiest solution would + have been to build a discovery server, but who would set the server + up? Who would maintain it? We needed a solution that could work even + if no one had any idea what discovery was. By using multicasting we + have the equivalent of a "party channel." Everyone can just grab the + channel and scream out what they need and everyone else will hear. + This means no configuration worries. Of course it brings up other + problems which are addressed throughout this specification. + +2.3.1.2. Why use a local administrative scope multicast address? + + Multicasting comes in many scopes, from link local all the way to + "the entire Internet." Our goal is to provide for discovery for + local area networks not for the entire Internet. LANs often are + bridged/routed so a link local multicast scope was too restrictive. + The next level up was a local administrative scope. The idea being + that your administrator decides how many machines should be grouped + together and considered a "unit". This seemed the ideal scope to use + for a local discovery protocol. + +2.3.1.3. Why does SSDP support both service discovery requests as well +as service presence announcements? + + Some discovery protocols only support discovery requests, that is, + the client must send out a request in order to find out who is + around. The downside to such solutions is that they tend to be very + expensive on the wire. For example, we want to display to our user + all the VCRs in her house. So we send out a discovery request. + However our user has just purchased a new VCR and, after starting + our program, plugged it in. The only way we would find out about the + new VCR and be able to display it on our user's screen is by + constantly sending out discovery requests. Now imagine every client + in the network having to send out a torrent of discovery requests + for service they care about in order to make sure they don't miss a + new service coming on-line. + + Other systems use the opposite extreme, they only support + announcements. Therefore, when our user opens the VCR display window + we would just sit and listen for announcements. In such systems all + the services have to send out a constant stream of announcements in + order to make sure that no one misses them. Users aren't the most + patient people in the world so each service will probably need to + announce itself at least every few seconds. This constant stream of + traffic does horrible things to network efficient, especially for + shared connections like Ethernets. + + +Goland et al. [Page 6] +INTERNET-DRAFT SSDP/V1 October 28, 1999 + + + + SSDP decided to adopt a hybrid approach and do both discovery and + announcements. This can be incredibly efficient. When a service + first comes on-line it will send out an announcement so that + everyone knows it is there. At that point it shouldn't ever need to + send out another announcement unless it is going off-line, has + changed state or its cache entry is about to expire. Any clients who + come on-line after the service came on-line will discover the + desired service by sending out a discovery request. The client + should never need to repeat the discovery request because any + services that subsequently come on-line will announce themselves. + The end result is that no one needs to send out steady streams of + messages. The entire system is event driven, only when things change + will messages need to be sent out. The cost, however, is that the + protocol is more complex. We felt this was a price worth paying as + it meant that SSDP could be used successfully in fairly large + networks. + +2.3.1.4. Doesn't the caching information turn SSDP back into a +"announcement driven" protocol? + + Discovery protocols that only support announcements generally have + to require services to send announcements every few seconds. + Otherwise users screens will take too long to update with + information about which services are available. + + SSDP, on the other hand, allows the service to inform clients how + long they should assume the service is around. Thus a service can + set a service interval to seconds, minutes, days, weeks, months or + even years. + + Clients do not have to wait around for cache update messages because + they can perform discovery. + +2.3.2. SSDP Discovery Information Caching Model + +2.3.2.1. Why do we need USNs, isn't the location good enough? + + When a service announces itself it usually includes a location + identifying where it may be found. However that location can and + will change over time. For example, a user may decide to change the + DNS name assigned to that device. Were we to depend on locations, + not USNs, when the service's location was changed we would think we + were seeing a brand new service. This would be very disruptive to + the user's experience. Imagine, for example, that the user has set + up a PC program that programs their VCR based on schedules pulled + off the Internet. If the user decides to change the VCR's name from + the factory default to something friendly then a location based + system would loose track of the VCR it is supposed to be programming + because the name has changed. By using unique Ids instead we are + able to track the VCR regardless of the name change. So the user can + + + +Goland et al. [Page 7] +INTERNET-DRAFT SSDP/V1 October 28, 1999 + + + change the VCR's name at will and the VCR programming application + will still be able to program the correct VCR. + +2.3.2.2. Why are USNs URIs and why are they required to be unique +across the entire URI namespace for all time? + + In general making a name universally unique turns out to usually be + a very good idea. Mechanisms such as UUIDs allow universally unique + names to be cheaply created in a decentralized manner. In this case + making USNs globally unique is very useful because services may be + constantly moved around, if they are to be successfully tracked they + need an identifier that isn't going to change and isn't going to get + confused with any other service. + + URIs were chosen because they have become the de facto managed + namespace for use on the Internet. Anytime someone wants to name + something it is easy to just use a URI. + +3. Terminology + + SSDP Client - A HTTP client that makes use of a service. + + SSDP Service - A HTTP resource that provides a service used by SSDP + clients. + + + Service Type - A URI that identifies the type or function of a + particular service. + + Unique Service Name (USN) - A URI that is guaranteed to be unique + across the entire URI namespace for all time. It is used to uniquely + identify a particular service in order to allow services with + identical service type URIs to to be differentiated. + + In addition, the key words "MUST", "MUST NOT", "REQUIRED", "SHALL", + "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and + "OPTIONAL" in this document are to be interpreted as described in + RFC 2119 [RFC2119]. + +4. SSDP Discovery Requests + +4.1. Problem Statement + + A mechanism is needed for SSDP clients to find desired SSDP + services. + +4.2. Proposed Solution + + The SEARCH method, introduced by [DASL], is extended using the [MAN] + mechanism to provide for SSDP discovery. + + The SSDP SEARCH extension is identified by the URI ssdp:discover. + + +Goland et al. [Page 8] +INTERNET-DRAFT SSDP/V1 October 28, 1999 + + + + For brevity's sake a HTTP SEARCH method enhanced with the + ssdp:discover functionality will be referred to as a ssdp:discover + request. + + ssdp:discover requests MUST contain a ST header. ssdp:discover + requests MAY contain a body but the body MAY be ignored if not + understood by the HTTP service. + + The ST header contains a single URI. SSDP clients may use the ST + header to specify the service type they want to discover. + + This specification only specifies the use of ssdp:discover requests + over HTTP Multicast UDP although it is expected that future + specifications will expand the definition to handle ssdp:discover + requests sent over HTTP TCP. + + ssdp:discover requests sent to the SSDP multicast channel/port MUST + have a request-URI of "*". Note that future specifications may allow + for other request-URIs to be used so implementations based on this + specification MUST be ready to ignore ssdp:discover requests on the + SSDP multicast channel/port with a request-URI other than "*". + + Only SSDP services that have a service type that matches the value + in the ST header MAY respond to a ssdp:discover request on the SSDP + multicast channel/port. + + Responses to ssdp:discover requests sent over the SSDP multicast + channel/port are to be sent to the IP address/port the ssdp:discover + request came from. + + A response to a ssdp:discover request SHOULD include the service's + location expressed through the Location and/or AL header. A + successful response to a ssdp:discover request MUST also include the + ST and USN headers. + + Response to ssdp:discover requests SHOULD contain a cache-control: + max-age or Expires header. If both are present then they are to be + processed in the order specified by HTTP/1.1, that is, the cache- + control header takes precedence of the Expires header. If neither + the cache-control nor the Expires header is provided on the response + to a ssdp:discover request then the information contained in that + response MUST NOT be cached by SSDP clients. + +4.2.1.1. Example + + M-SEARCH * HTTP/1.1 + S: uuid:ijklmnop-7dec-11d0-a765-00a0c91e6bf6 + Host: 239.255.255.250:reservedSSDPport + Man: "ssdp:discover" + ST: ge:fridge + MX: 3 + + +Goland et al. [Page 9] +INTERNET-DRAFT SSDP/V1 October 28, 1999 + + + + HTTP/1.1 200 OK + S: uuid:ijklmnop-7dec-11d0-a765-00a0c91e6bf6 + Ext: + Cache-Control: no-cache="Ext", max-age = 5000 + ST: ge:fridge + USN: uuid:abcdefgh-7dec-11d0-a765-00a0c91e6bf6 + AL: + +4.3. Design Rationale + +4.3.1. Why is the ST header so limited? Why doesn't it support at +least and/or/not? Why not name/value pair searching? + + Deciding the "appropriate" level of search capability is a hopeless + task. So we decided to pare things back to the absolute minimum, a + single opaque token, and see what happens. The result so far has + been a very nice, simple, easy to implement, easy to use discovery + system. There are lots of great features it doesn't provide but most + of them, such as advanced queries and scoping, require a search + engine and a directory. This level of capability is beyond many + simple devices, exactly the sort of folks we are targeting with + SSDP. Besides, search functionality seems to be an all or nothing + type of situation. Either you need a brain dead simple search + mechanism or you need a full fledged near SQL class search system. + Instead of making SSDP the worst of both worlds we decided to just + focus on the dirt simple search problem and leave the more advanced + stuff to the directory folk. + +4.3.2. If we are using the SEARCH method why aren't you using the +DASL search syntax? + + We couldn't come up with a good reason to force our toaster ovens to + learn XML. The features the full-fledged DASL search syntax provides + are truly awesome and thus way beyond our simple scenarios. We fully + expect that DASL will be the preferred solution for advanced search + scenarios, but that isn't what this draft is about. + +4.3.3. Why can we only specify one search type in the ST header of a +ssdp:discover request? + + We wanted to start as simple as possible and be forced, kicking and + screaming, into adding additional complexity. The simplest solution + was to only allow a single value in the ST header. We were also + concerned that if we allowed multiple values into the ST headers + somebody would try to throw in and/or/not functionality. Given the + minimal byte savings of allowing multiple values into the ST header + it seems better to just leave the protocol simpler. + +4.3.4. Why do we only provide support for multicast UDP, not TCP, +ssdp:discover requests? + + + +Goland et al. [Page 10] +INTERNET-DRAFT SSDP/V1 October 28, 1999 + + + We only define what we need to make the discovery protocol work and + we don't need TCP to make the discovery protocol work. Besides to + make TCP discovery really work you need to be able to handle + compound responses which means you need a compound response format + which is probably XML and that is more than we wanted to handle. + Eventually we expect that you will be able to go up to the SSDP port + on a server using a HTTP TCP request and discover what service, if + any, lives there. But that will be described in a future + specification. + +4.3.5. Why do we require that responses without caching information +not be cached at all? + + Because that was a lot easier thing to do then trying to explain the + various heuristics one could use to deal with services who don't + provide caching information. + +5. SSDP Presence Announcements + +5.1. Problem Statement + + A mechanism is needed for SSDP services to be able to let interested + SSDP clients know of their presence. + + A mechanism is needed to allow SSDP services to update expiration + information in cache entries regarding them. + + A mechanism is needed to allow SSDP services to notify interested + SSDP clients when their location changes. + + A mechanism is needed to allow SSDP services to inform interested + SSDP clients that they are going to de-activate themselves. + +5.2. Proposed Solution + +5.2.1. ssdp:alive + + SSDP services may declare their presence on the network by sending a + [GENA] NOTIFY method using the NTS value ssdp:alive to the SSDP + multicast channel/port. + + For brevity's sake HTTP NOTIFY methods with the NTS value ssdp:alive + will be referred to as ssdp:alive requests. + + When a ssdp:alive request is received whose USN matches the USN of + an entry already in the SSDP client's cache then all information + regarding that USN is to be replaced with the information on the + ssdp:alive request. Hence ssdp:alive requests can be used to update + location information and prevent cache entries from expiring. + + + + + +Goland et al. [Page 11] +INTERNET-DRAFT SSDP/V1 October 28, 1999 + + + The value of NT on a ssdp:alive request MUST be set to the service's + service type. ssdp:alive requests MUST contain a USN header set to + the SSDP service's USN. + + ssdp:alive requests SHOULD contain a Location and/or AL header. If + there is no DNS support available on the local network then at least + one location SHOULD be provided using an IP address of the SSDP + service. + + ssdp:alive requests SHOULD contain a cache-control: max-age or + Expires header. If both are present then they are to be processed in + the order specified by HTTP/1.1, that is, the cache-control header + takes precedence of the Expires header. If neither the cache-control + nor the Expires header is provided the information in the ssdp:alive + request MUST NOT be cached by SSDP clients. + + There is no response to a ssdp:alive sent to the SSDP multicast + channel/port. + +5.2.1.1. Example + + NOTIFY * HTTP/1.1 + Host: 239.255.255.250:reservedSSDPport + NT: blenderassociation:blender + NTS: ssdp:alive + USN: someunique:idscheme3 + AL: + Cache-Control: max-age = 7393 + +5.2.2. ssdp:byebye + + SSDP services may declare their intention to cease operating by + sending a [GENA] NOTIFY method using the NTS value ssdp:byebye to + the SSDP multicast channel/port. + + For brevity's sake HTTP NOTIFY methods with the NTS value + ssdp:byebye will be referred to as ssdp:byebye requests. + + The value of NT on a ssdp:byebye request MUST be set to the + service's service type. ssdp:byebye requests MUST contain a USN + header set to the SSDP service's USN. + + There is no response to a ssdp:byebye sent to the SSDP multicast + channel/port. + + When a ssdp:byebye request is received all cached information + regarding that USN SHOULD be removed. + +5.2.2.1. Example + + NOTIFY * HTTP/1.1 + Host: 239.255.255.250:reservedSSDPport + + +Goland et al. [Page 12] +INTERNET-DRAFT SSDP/V1 October 28, 1999 + + + NT: someunique:idscheme3 + NTS: ssdp:byebye + USN: someunique:idscheme3 + +5.3. Design Rationale + +5.3.1. Why are we using GENA NOTIFY requests? + + We needed to use some notification format and GENA seemed as good as + any. Moving forward, GENA gives us a framework to do notification + subscriptions which will be necessary if SSDP services are to be + able to provide status updates across the wilds of the Internet + without depending on the largely non-existent Internet multicast + infrastructure. + + +5.3.2. Why is there no response to the ssdp:alive/ssdp:byebye +requests sent to the SSDP multicast channel/port? + + What response would be sent? There isn't much of a point of having + the SSDP clients send response saying "we received your + notification" since there may be a lot of them. + +5.3.3. Could NTS values other than ssdp:alive/ssdp:byebye be sent to +the SSDP multicast channel/port? + + Yes. + +5.3.4. Why do we include the NT header on ssdp:byebye requests? + + Technically it isn't necessary since the only useful information is + the USN. But we want to stick with the GENA format that requires a + NT header. In truth the requirement of including the NT header is a + consequence of the next issue. + +5.3.5. Shouldn't the NT and NTS values be switched? + + Yes, they should. Commands such as ssdp:alive and ssdp:byebye should + be NT values and the service type, where necessary, should be the + NTS. The current mix-up is a consequence of a previous design where + the NT header was used in a manner much like we use the USN today. + This really needs to change. + +6. SSDP Auto-Shut-Off Algorithm + +6.1. Problem Statement + + A mechanism is needed to ensure that SSDP does not cause such a high + level of traffic that it overwhelms the network it is running on. + +6.2. Proposed Solution + + + +Goland et al. [Page 13] +INTERNET-DRAFT SSDP/V1 October 28, 1999 + + + [Ed. Note: We have a proposed solution but it is still a bit rough, + so we will be publishing to the SSDP mailing list for further + discussion before including it in the draft.] + +6.3. Design Rationale + +6.3.1. Why do we need an auto-shut-off algorithm? + + The general algorithm for figuring out how much bandwidth SSDP uses + over a fixed period of time based on the number of ssdp:discover + requests is : + + DR = Total number of SSDP clients making ssdp:discover requests over + the time period in question. + RS = Total number of services that will respond to the ssdp:discover + requests over the time period in question. + AM = Average size of the ssdp:discover requests/responses. + TP = Time period in question. + + ((DR*3 + DR*9*RS)*AM)/TP + + The 3 is the number of times the ssdp:discover request will be + repeated. + The 9 is the number of times the unicast responses to the + ssdp:discover requests will be sent out assuming the worst case in + which all 3 original requests are received. + + So let's look at a real world worst-case scenario. Some companies, + in order to enable multicast based services such as voice or video + streaming to be easily configured set their local administrative + multicast scope to encompass their entire company. This means one + gets networks with 100,000 machines in a single administrative + multicast scope. Now imagine that there is a power outage and all + the machines are coming back up at the same time. Further imagine + that they all want to refresh their printer location caches so they + all send out ssdp:discover requests. Let us finally imagine that + there are roughly 5000 printers in this network. To simplify the + math we will assume that the ssdp:discover requests are evenly + distributed over the 30 seconds. + + DR = 100,000 requesting clients + RS = 5000 services + AM = 512 bytes + TP = 30 seconds + + ((100000*3+100000*9*5000)*512)/30 = 76805120000 bytes/s = + 585976.5625 Megabits per second + + This is what one would call an awful number. + + + + + +Goland et al. [Page 14] +INTERNET-DRAFT SSDP/V1 October 28, 1999 + + + In a more reasonably sized network SSDP is able to handle this worst + case scenario much better. For example, let's look at a network with + 1000 clients and 50 printers. + + DR = 1000 requesting clients + RS = 50 services + AM = 512 bytes + TP = 30 seconds + + ((1000*3+1000*9*50)*512)/30 = 7731200 bytes/s = 59 Mbps + + Now this looks like an awful amount but remember that that this is + the total data rate needed for 30 seconds. This means that the total + amount of information SSDP needs to send out to survive a reboot is + 59*30 = 1770 Mb. Therefore a 10 Mbps network, assuming an effective + data rate 5 Mbps under constant load that means it will take 1770/5 + = 354 seconds = 6 minutes for the network to settle down. + + That isn't bad considering that this is an absolute worst case in a + network with 1000 clients and 50 services all of whom want to talk + to each other at the exact same instant. + + In either case, there are obvious worst-case scenarios and we need + to avoid network storms, therefore we need a way for SSDP to de- + activate before it causes a network storms. + +6.3.2. Why not just require everyone to support directories and thus +get around the scaling issue? + + Many manufacturers stick every protocol they can think of in their + clients and services. So if your network administrator happened to + buy some clients and servers that supported SSDP but didn't know + they supported SSDP then you can imagine the problems. Therefore + even if we required directory support there are still many cases + where SSDP clients and services may inadvertently end up in a + network without anyone knowing it and cause problems. + +7. ssdp:all + +7.1. Problem Statement + + A mechanism is needed to enable a client to enumerate all the + services available on a particular SSDP multicast channel/port. + +7.2. Proposed Solution + + All SSDP services MUST respond to SEARCH requests over the SSDP + multicast channel/port with the ST value of ssdp:all by responding + as if the ST value had been their service type. + + For brevity's sake a SEARCH request with a ST of ssdp:all will be + referred to as a ssdp:all request. + + +Goland et al. [Page 15] +INTERNET-DRAFT SSDP/V1 October 28, 1999 + + + +7.3. Design Rationale + +7.3.1. Why would anyone want to enumerate all services? + + This feature is mostly for network analysis tools. It also will + prove very useful in the feature when directories become SSDP aware. + They will be able to discover all services, record information about + them and make that information available outside the local + administrative multicast scope. + +8. SSDP Reserved Multicast Channel + +8.1. Problem Statement + + SSDP needs a local administrative multicast channel that will be + guaranteed to only be used by SSDP compliant clients and services. + +8.2. Proposed Solution + + IANA has reserved the relative multicast address "5" for the + exclusive use of SSDP. In the local administrative scope used by + this version of SSDP the relative address translates to + 239.255.255.250. + + An application has been put in for a SSDP reserved port but IANA has + not yet responded. + +8.3. Design Rationale + +8.3.1. Why didn't SSDP just get a static local administrative scope +address rather than a relative address? + + We got a relative address because we expect that SSDP may be used to + discover basic system services such as directories. In that case if + you can't find a directory in your local scope you may want to try a + wider multicast scope. This is exactly the sort of functionality + enabled by MALLOC (http://www.ietf.org/html.charters/malloc- + charter.html). MALLOC allows one to enumerate all the multicast + scopes that are supported on the network. The SSDP client can then + try progressively larger scopes to find the service they are seeing. + However this progressively wider discovery only works if SSDP uses a + relative address. + +8.3.2. Why does SSDP need to use a port other than 80? + + There is a bug in the Berkley Sockets design that was inherited by + WinSock as well. The bug is as follows: One can not grab a + particular port on a particular multicast address without owning the + same port on the local unicast address. + + + + +Goland et al. [Page 16] +INTERNET-DRAFT SSDP/V1 October 28, 1999 + + + The result is that if we used port 80 on the SSDP multicast scope + then we would require that the SSDP software also grab port 80 for + the local machine. This would mean that SSDP could only be + implemented on machines which either didn't have HTTP servers or + whose HTTP servers had been enhanced to support SSDP. + + We felt this was a unnecessary restriction. Therefore we are + choosing to use a port other than 80 on the SSDP multicast channel. + +9. HTTP Headers + +9.1. USN Header + + USN = "USN" ":" AbsoluteURI; defined in section 3.2.1 of [RFC2616] + +9.2. ST Header + + ST = "ST" ":" AbsoluteURI + +10. Security Considerations + + TBD. + +11. IANA Considerations + + To ensure correct interoperation based on this specification, IANA + must reserve the URI namespace starting with "ssdp:" for use by this + specification, its revisions, and related SSDP specifications. + + IANA has reserved the relative multicast address "5" for exclusive + use by SSDP. An application has been made for a registered port. + +12. Appendix - Constants + + MAX_UNIQUE - 50 - Maximum number of unique IP address/port pairs + that may be sent over UDP before tripping the auto-shut-off + algorithm. + + MAX_COUNT - 30 seconds - When the "go quiet" process is begun a + message is sent out that is delayed a random interval between 0 to + MAX_COUNT seconds. + +13. Acknowledgements + + This document is the result of enormous effort by a large number of + people including but not limited to: + Alan Boshier, Babak Jahromi, Brandon Watson, Craig White, Dave + Thaler, Holly Knight, Michel Guittet, Mike Zintel, Munil Shah, Paul + Moore, Peter Ford, Pradeep Bahl, and Todd Fisher. + +14. References + + + +Goland et al. [Page 17] +INTERNET-DRAFT SSDP/V1 October 28, 1999 + + + [HTTPUDP] Y. Y. Goland. Multicast and Unicast UDP HTTP Requests. + Internet Draft - a work in progress, draft-goland-http-udp-00.txt. + + [GENA] J. Cohen, S. Aggarwal, Y. Y. Goland. General Event + Notification Architecture Base: Client to Arbiter. Internet Draft - + a work in progress, draft-cohen-gena-client-00.txt. + + [MAN] H. Nielsen, P. Leach, S. Lawrence. Mandatory Extensions in + HTTP. Internet Draft - a work in progress, draft-frystyk-http- + extensions-03.txt. + + [RFC2119] S. Bradner. Key words for use in RFCs to Indicate + Requirement Levels. RFC 2119, March 1997. + + [RFC2365] D. Meyer. Administratively Scoped IP Multicast. RFC + 2365, July 1998. + + [RFC2396] T. Berners-Lee, R. Fielding and L. Masinter. Uniform + Resource Identifiers (URI): Generic Syntax. RFC 2396, August 1998. + + [RFC2518] Y. Goland, E. Whitehead, A. Faizi, S. Carter, and D. + Jensen. HTTP Extensions for Distributed Authoring – WEBDAV. RFC + 2518, February 1999. + + [RFC2616] R. Fielding, J. Gettys, J. C. Mogul, H. Frystyk, L. + Masinter, P. Leach and T. Berners-Lee. Hypertext Transfer Protocol - + HTTP/1.1. RFC 2616, November 1998. + + [DASL] S. Reddy, D. Lowry, S. Reddy, R. Henderson, J. Davis, A. + Babich. DAV Searching & Locating. a work in progress - draft-ietf- + dasl-protocol-00.txt. + +15. Author's Addresses + + Yaron Y. Goland, Ting Cai, Paul Leach, Ye Gu + Microsoft Corporation + One Microsoft Way + Redmond, WA 98052 + + Email: {yarong, tingcai, paulle, yegu}@microsoft.com + + Shivaun Albright + Hewlett-Packard Company + Roseville, CA + + Email: SHIVAUN_ALBRIGHT@HP-Roseville-om2.om.hp.com + + This document will expire in April 2000. + + + + + +Goland et al. [Page 18] + diff --git a/docs/xml data files/device/MediaRenderer1.xml b/docs/xml data files/device/MediaRenderer1.xml new file mode 100644 index 0000000..9362e07 --- /dev/null +++ b/docs/xml data files/device/MediaRenderer1.xml @@ -0,0 +1,17 @@ + + + + urn:schemas-upnp-org:service:RenderingControl:1 + RenderingControl + + + urn:schemas-upnp-org:service:ConnectionManager:1 + ConnectionManager + + + + urn:schemas-upnp-org:service:AVTransport:1 + AVTransport + + + diff --git a/docs/xml data files/device/MediaServer1.xml b/docs/xml data files/device/MediaServer1.xml new file mode 100644 index 0000000..87f82a9 --- /dev/null +++ b/docs/xml data files/device/MediaServer1.xml @@ -0,0 +1,17 @@ + + + + + urn:schemas-upnp-org:service:AVTransport:1 + AVTransport + + + urn:schemas-upnp-org:service:ContentDirectory:1 + ContentDirectory + + + urn:schemas-upnp-org:service:ConnectionManager:1 + ConnectionManager + + + diff --git a/docs/xml data files/service/AVTransport1.xml b/docs/xml data files/service/AVTransport1.xml new file mode 100644 index 0000000..e6a0a49 --- /dev/null +++ b/docs/xml data files/service/AVTransport1.xml @@ -0,0 +1,477 @@ + + + + TransportState + no + string + + STOPPED + PLAYING + + + + TransportStatus + no + string + + OK + ERROR_OCCURRED + + + + PlaybackStorageMedium + no + string + + + RecordStorageMedium + no + string + + + PossiblePlaybackStorageMedia + no + string + + + PossibleRecordStorageMedia + no + string + + + CurrentPlayMode + no + string + + NORMAL + + NORMAL + + + TransportPlaySpeed + no + string + + 1 + + + + no + RecordMediumWriteStatus + string + + + CurrentRecordQualityMode + no + string + + + PossibleRecordQualityModes + no + string + + + NumberOfTracks + no + ui4 + + 0 + + + + CurrentTrack + no + ui4 + + 0 + 1 + + + + CurrentTrackDuration + no + string + + + CurrentMediaDuration + no + string + + + CurrentTrackMetaData + no + string + + + CurrentTrackURI + no + string + + + AVTransportURI + no + string + + + AVTransportURIMetaData + no + string + + + NextAVTransportURI + no + string + + + NextAVTransportURIMetaData + no + string + + + RelativeTimePosition + no + string + + + AbsoluteTimePosition + no + string + + + RelativeCounterPosition + no + i4 + + + AbsoluteCounterPosition + no + i4 + + + + CurrentTransportActions + no + string + + + LastChange + yes + string + + + A_ARG_TYPE_SeekMode + no + string + + TRACK_NR + + + + A_ARG_TYPE_SeekTarget + no + string + + + A_ARG_TYPE_InstanceID + no + ui4 + + + + + SetAVTransportURI + + + InstanceID + in A_ARG_TYPE_InstanceID + + + CurrentURI + in AVTransportURI + + + CurrentURIMetaData + in AVTransportURIMetaData + + + + + SetNextAVTransportURI + + + InstanceID + in A_ARG_TYPE_InstanceID + + + NextURI + in NextAVTransportURI + + + NextURIMetaData + in NextAVTransportURIMetaData + + + + + GetMediaInfo + + + InstanceID + in A_ARG_TYPE_InstanceID + + + NrTracks + out NumberOfTracks + + + MediaDuration + out CurrentMediaDuration + + + CurrentURI + out AVTransportURI + + + CurrentURIMetaData + out AVTransportURIMetaData + + + NextURI + out NextAVTransportURI + + + NextURIMetaData + out NextAVTransportURIMetaData + + + PlayMedium + out PlaybackStorageMedium + + + RecordMedium + out RecordStorageMedium + + + WriteStatus + out RecordMediumWriteStatus + + + + + GetTransportInfo + + + InstanceID + in A_ARG_TYPE_InstanceID + + + CurrentTransportState + out TransportState + + + CurrentTransportStatus + out TransportStatus + + + CurrentSpeed + out TransportPlaySpeed + + + + + GetPositionInfo + + + InstanceID + in A_ARG_TYPE_InstanceID + + + Track + out CurrentTrack + + + TrackDuration + out CurrentTrackDuration + + + TrackMetaData + out CurrentTrackMetaData + + + TrackURI + out CurrentTrackURI + + + RelTime + out RelativeTimePosition + + + AbsTime + out AbsoluteTimePosition + + + RelCount + out RelativeCounterPosition + + + AbsCount + out AbsoluteCounterPosition + + + + + GetDeviceCapabilities + + + InstanceID + in A_ARG_TYPE_InstanceID + + + PlayMedia + out PossiblePlaybackStorageMedia + + + RecMedia + out PossibleRecordStorageMedia + + + RecQualityModes + out PossibleRecordQualityModes + + + + + GetTransportSettings + + + InstanceID + in A_ARG_TYPE_InstanceID + + + PlayMode + out CurrentPlayMode + + + RecQualityMode + out CurrentRecordQualityMode + + + + + Stop + + + InstanceID + in A_ARG_TYPE_InstanceID + + + + + Play + + + InstanceID + in A_ARG_TYPE_InstanceID + + + Speed + in TransportPlaySpeed + + + + + Pause + + + InstanceID + in A_ARG_TYPE_InstanceID + + + + + Record + + + InstanceID + in A_ARG_TYPE_InstanceID + + + + + Seek + + + InstanceID + in A_ARG_TYPE_InstanceID + + + Unit + in A_ARG_TYPE_SeekMode + + + Target + in A_ARG_TYPE_SeekTarget + + + + + Next + + + InstanceID + in A_ARG_TYPE_InstanceID + + + + + Previous + + + InstanceID + in A_ARG_TYPE_InstanceID + + + + + SetPlayMode + + + InstanceID + in A_ARG_TYPE_InstanceID + + + NewPlayMode + in CurrentPlayMode + + + + + SetRecordQualityMode + + + InstanceID + in A_ARG_TYPE_InstanceID + + + NewRecordQualityMode + in CurrentRecordQualityMode + + + + + + GetCurrentTransportActions + + + InstanceID + in A_ARG_TYPE_InstanceID + + + Actions + out CurrentTransportActions + + + + + + diff --git a/docs/xml data files/service/ConnectionManager1.xml b/docs/xml data files/service/ConnectionManager1.xml new file mode 100644 index 0000000..72d2114 --- /dev/null +++ b/docs/xml data files/service/ConnectionManager1.xml @@ -0,0 +1,170 @@ + + + + SourceProtocolInfo + yes + string + + + SinkProtocolInfo + yes + string + + + CurrentConnectionIDs + yes + string + + + A_ARG_TYPE_ConnectionStatus + no + string + + OK + ContentFormatMismatch + InsufficientBandwidth + UnreliableChannel + Unknown + + + + A_ARG_TYPE_ConnectionManager + no + string + + + A_ARG_TYPE_Direction + no + string + + Input + Output + + + + A_ARG_TYPE_ProtocolInfo + no + string + + + A_ARG_TYPE_ConnectionID + no + i4 + + + A_ARG_TYPE_AVTransportID + no + i4 + + + A_ARG_TYPE_RcsID + no + i4 + + + + + GetProtocolInfo + + + Source + out SourceProtocolInfo + + + Sink + out SinkProtocolInfo + + + + + + PrepareForConnection + + + RemoteProtocolInfo + in A_ARG_TYPE_ProtocolInfo + + + PeerConnectionManager + in A_ARG_TYPE_ConnectionManager + + + PeerConnectionID + in A_ARG_TYPE_ConnectionID + + + Direction + in A_ARG_TYPE_Direction + + + ConnectionID + out A_ARG_TYPE_ConnectionID + + + AVTransportID + out A_ARG_TYPE_AVTransportID + + + RcsID + out A_ARG_TYPE_RcsID + + + + + + ConnectionComplete + + + ConnectionID + in A_ARG_TYPE_ConnectionID + + + + + GetCurrentConnectionIDs + + + ConnectionIDs + out CurrentConnectionIDs + + + + + GetCurrentConnectionInfo + + + ConnectionID + in A_ARG_TYPE_ConnectionID + + + RcsID + out A_ARG_TYPE_RcsID + + + AVTransportID + out A_ARG_TYPE_AVTransportID + + + ProtocolInfo + out A_ARG_TYPE_ProtocolInfo + + + PeerConnectionManager + out A_ARG_TYPE_ConnectionManager + + + PeerConnectionID + out A_ARG_TYPE_ConnectionID + + + Direction + out A_ARG_TYPE_Direction + + + Status + out A_ARG_TYPE_ConnectionStatus + + + + + diff --git a/docs/xml data files/service/ContentDirectory1.xml b/docs/xml data files/service/ContentDirectory1.xml new file mode 100644 index 0000000..9ad8157 --- /dev/null +++ b/docs/xml data files/service/ContentDirectory1.xml @@ -0,0 +1,405 @@ + + + + TransferIDs +yes + string + + + A_ARG_TYPE_ObjectID no + string + + + A_ARG_TYPE_Result no + string + + + A_ARG_TYPE_SearchCriteria no + string + + + A_ARG_TYPE_BrowseFlag no + string + + BrowseMetadata + BrowseDirectChildren + + + + A_ARG_TYPE_Filter +no + string + + + A_ARG_TYPE_SortCriteria no + string + + + A_ARG_TYPE_Index no + ui4 + + + A_ARG_TYPE_Count no + ui4 + + + A_ARG_TYPE_UpdateID no + ui4 + + + A_ARG_TYPE_TransferID no + ui4 + + + A_ARG_TYPE_TransferStatus no + string + + COMPLETED + ERROR + IN_PROGRESS + STOPPED + + + + A_ARG_TYPE_TransferLength no + string + + + A_ARG_TYPE_TransferTotal no + string + + + A_ARG_TYPE_TagValueList no + string + + + A_ARG_TYPE_URI +no + uri + + + SearchCapabilities +no + string + + + SortCapabilities +no + string + + + SystemUpdateID +yes + ui4 + + + ContainerUpdateIDs +yes + string + + + + + GetSearchCapabilities + + + SearchCaps + out + SearchCapabilities + + + + + GetSortCapabilities + + + SortCaps + out + SortCapabilities + + + + + GetSystemUpdateID + + + Id + out + SystemUpdateID + + + + + Browse + + + ObjectID + in + A_ARG_TYPE_ObjectID + + + BrowseFlag + in + A_ARG_TYPE_BrowseFlag + + + Filter + in + A_ARG_TYPE_Filter + + + StartingIndex + in + A_ARG_TYPE_Index + + + RequestedCount + in + A_ARG_TYPE_Count + + + SortCriteria + in + A_ARG_TYPE_SortCriteria + + + Result + out + A_ARG_TYPE_Result + + + NumberReturned + out + A_ARG_TYPE_Count + + + TotalMatches + out + A_ARG_TYPE_Count + + + UpdateID + out + A_ARG_TYPE_UpdateID + + + + + Search + + + ContainerID + in + A_ARG_TYPE_ObjectID + + + SearchCriteria + in + A_ARG_TYPE_SearchCriteria + + + Filter + in + A_ARG_TYPE_Filter + + + StartingIndex + in + A_ARG_TYPE_Index + + + RequestedCount + in + A_ARG_TYPE_Count + + + SortCriteria + in + A_ARG_TYPE_SortCriteria + + + Result + out + A_ARG_TYPE_Result + + + NumberReturned + out + A_ARG_TYPE_Count + + + TotalMatches + out + A_ARG_TYPE_Count + + + UpdateID + out + A_ARG_TYPE_UpdateID + + + + + CreateObject + + + ContainerID + in + A_ARG_TYPE_ObjectID + + + Elements + in + A_ARG_TYPE_Result + + + ObjectID + out + A_ARG_TYPE_ObjectID + + + Result + out + A_ARG_TYPE_Result + + + + + DestroyObject + + + ObjectID + in + A_ARG_TYPE_ObjectID + + + + + UpdateObject + + + ObjectID + in + A_ARG_TYPE_ObjectID + + + CurrentTagValue + in + A_ARG_TYPE_TagValueList + + + NewTagValue + in + A_ARG_TYPE_TagValueList + + + + + ImportResource + + + SourceURI + in + A_ARG_TYPE_URI + + + DestinationURI + in + A_ARG_TYPE_URI + + + TransferID + out + A_ARG_TYPE_TransferID + + + + + ExportResource + + + SourceURI + in + A_ARG_TYPE_URI + + + DestinationURI + in + A_ARG_TYPE_URI + + + TransferID + out + A_ARG_TYPE_TransferID + + + + + StopTransferResource + + + TransferID + in + A_ARG_TYPE_TransferID + + + + + GetTransferProgress + + + TransferID + in + A_ARG_TYPE_TransferID + + + TransferStatus + out + A_ARG_TYPE_TransferStatus + + + TransferLength + out + A_ARG_TYPE_TransferLength + + + TransferTotal + out + A_ARG_TYPE_TransferTotal + + + + + DeleteResource + + + ResourceURI + in + A_ARG_TYPE_URI + + + + + CreateReference + + + ContainerID + in + A_ARG_TYPE_ObjectID + + + ObjectID + in + A_ARG_TYPE_ObjectID + + + NewID + out + A_ARG_TYPE_ObjectID + + + + + + + diff --git a/docs/xml data files/service/RenderingControl1.xml b/docs/xml data files/service/RenderingControl1.xml new file mode 100644 index 0000000..b2c66ce --- /dev/null +++ b/docs/xml data files/service/RenderingControl1.xml @@ -0,0 +1,718 @@ + + + + PresetNameList no + string + + + LastChange yes + string + + + Brightness no + ui2 + + 0 + 1 + + + + Contrast no + ui2 + + 0 + 1 + + + + Sharpness no + ui2 + + 0 + 1 + + + + RedVideoGain no + ui2 + + + GreenVideoGain no + ui2 + + 0 + 1 + + + + BlueVideoGain no + ui2 + + 0 + 1 + + + + RedVideoBlackLevel no + ui2 + + 0 + 1 + + + + GreenVideoBlackLevel no + ui2 + + 0 + 1 + + + + BlueVideoBlackLevel no + ui2 + + 0 + 1 + + + + ColorTemperature no + ui2 + + 0 + 1 + + + + HorizontalKeystone no + i2 + + 1 + + + + VerticalKeystone no + i2 + + 1 + + + + Mute no + boolean + + + Volume no + ui2 + + 0 + 1 + + + + VolumeDB no + i2 + + + Loudness no + boolean + + + A_ARG_TYPE_Channel no + string + + Master + + + + A_ARG_TYPE_InstanceID no + ui4 + + + A_ARG_TYPE_PresetName no + string + + FactoryDefaults + + + + + + ListPresets + + + InstanceID + in + A_ARG_TYPE_InstanceID + + + CurrentPresetNameList + out + PresetNameList + + + + + SelectPreset + + + InstanceID + in + A_ARG_TYPE_InstanceID + + + PresetName + in + A_ARG_TYPE_PresetName + + + + + GetBrightness + + + InstanceID + in + A_ARG_TYPE_InstanceID + + + CurrentBrightness + out + Brightness + + + + + SetBrightness + + + InstanceID + in + A_ARG_TYPE_InstanceID + + + DesiredBrightness + in + Brightness + + + + + GetContrast + + + InstanceID + in + A_ARG_TYPE_InstanceID + + + CurrentContrast + out + Contrast + + + + + SetContrast + + + InstanceID + in + A_ARG_TYPE_InstanceID + + + DesiredContrast + in + Contrast + + + + + GetSharpness + + + InstanceID + in + A_ARG_TYPE_InstanceID + + + CurrentSharpness + out + Sharpness + + + + + SetSharpness + + + InstanceID + in + A_ARG_TYPE_InstanceID + + + DesiredSharpness + in + Sharpness + + + + + GetRedVideoGain + + + InstanceID + in + A_ARG_TYPE_InstanceID + + + CurrentRedVideoGain + out + RedVideoGain + + + + + SetRedVideoGain + + + InstanceID + in + A_ARG_TYPE_InstanceID + + + DesiredRedVideoGain + in + RedVideoGain + + + + + GetGreenVideoGain + + + InstanceID + in + A_ARG_TYPE_InstanceID + + + CurrentGreenVideoGain + out + GreenVideoGain + + + + + SetGreenVideoGain + + + InstanceID + in + A_ARG_TYPE_InstanceID + + + DesiredGreenVideoGain + in + GreenVideoGain + + + + + GetBlueVideoGain + + + InstanceID + in + A_ARG_TYPE_InstanceID + + + CurrentBlueVideoGain + out + BlueVideoGain + + + + + SetBlueVideoGain + + + InstanceID + in + A_ARG_TYPE_InstanceID + + + DesiredBlueVideoGain + in + BlueVideoGain + + + + + GetRedVideoBlackLevel + + + InstanceID + in + A_ARG_TYPE_InstanceID + + + CurrentRedVideoBlackLevel + out + RedVideoBlackLevel + + + + + SetRedVideoBlackLevel + + + InstanceID + in + A_ARG_TYPE_InstanceID + + + DesiredRedVideoBlackLevel + in + RedVideoBlackLevel + + + + + GetGreenVideoBlackLevel + + + InstanceID + in + A_ARG_TYPE_InstanceID + + + CurrentGreenVideoBlackLevel + out + GreenVideoBlackLevel + + + + + SetGreenVideoBlackLevel + + + InstanceID + in + A_ARG_TYPE_InstanceID + + + DesiredGreenVideoBlackLevel + in + GreenVideoBlackLevel + + + + + GetBlueVideoBlackLevel + + + InstanceID + in + A_ARG_TYPE_InstanceID + + + CurrentBlueVideoBlackLevel + out + BlueVideoBlackLevel + + + + + SetBlueVideoBlackLevel + + + InstanceID + in + A_ARG_TYPE_InstanceID + + + DesiredBlueVideoBlackLevel + in + BlueVideoBlackLevel + + + + + GetColorTemperature + + + InstanceID + in + A_ARG_TYPE_InstanceID + + + CurrentColorTemperature + out + ColorTemperature + + + + + SetColorTemperature + + + InstanceID + in + A_ARG_TYPE_InstanceID + + + DesiredColorTemperature + in + ColorTemperature + + + + + GetHorizontalKeystone + + + InstanceID + in + A_ARG_TYPE_InstanceID + + + CurrentHorizontalKeystone + out + HorizontalKeystone + + + + + SetHorizontalKeystone + + + InstanceID + in + A_ARG_TYPE_InstanceID + + + DesiredHorizontalKeystone + in + HorizontalKeystone + + + + + GetVerticalKeystone + + + InstanceID + in + A_ARG_TYPE_InstanceID + + + CurrentVerticalKeystone + out + VerticalKeystone + + + + + SetVerticalKeystone + + + InstanceID + in + A_ARG_TYPE_InstanceID + + + DesiredVerticalKeystone + in + VerticalKeystone + + + + + GetMute + + + InstanceID + in + A_ARG_TYPE_InstanceID + + + Channel + in + A_ARG_TYPE_Channel + + + CurrentMute + out + Mute + + + + + SetMute + + + InstanceID + in + A_ARG_TYPE_InstanceID + + + Channel + in + A_ARG_TYPE_Channel + + + DesiredMute + in + Mute + + + + + GetVolume + + + InstanceID + in + A_ARG_TYPE_InstanceID + + + Channel + in + A_ARG_TYPE_Channel + + + CurrentVolume + out + Volume + + + + + SetVolume + + + InstanceID + in + A_ARG_TYPE_InstanceID + + + Channel + in + A_ARG_TYPE_Channel + + + DesiredVolume + in + Volume + + + + + GetVolumeDB + + + InstanceID + in + A_ARG_TYPE_InstanceID + + + Channel + in + A_ARG_TYPE_Channel + + + CurrentVolume + out + VolumeDB + + + + + SetVolumeDB + + + InstanceID + in + A_ARG_TYPE_InstanceID + + + Channel + in + A_ARG_TYPE_Channel + + + DesiredVolume + in + VolumeDB + + + + + GetVolumeDBRange + + + InstanceID + in + A_ARG_TYPE_InstanceID + + + Channel + in + A_ARG_TYPE_Channel + + + MinValue + out + VolumeDB + + + MaxValue + out + VolumeDB + + + + + GetLoudness + + + InstanceID + in + A_ARG_TYPE_InstanceID + + + Channel + in + A_ARG_TYPE_Channel + + + CurrentLoudness + out + Loudness + + + + + SetLoudness + + + InstanceID + in + A_ARG_TYPE_InstanceID + + + Channel + in + A_ARG_TYPE_Channel + + + DesiredLoudness + in + Loudness + + + + + + diff --git a/docs/xml data files/service/test cases/syntax/AVTransport1.SyntaxTests.xml b/docs/xml data files/service/test cases/syntax/AVTransport1.SyntaxTests.xml new file mode 100644 index 0000000..2f146b4 --- /dev/null +++ b/docs/xml data files/service/test cases/syntax/AVTransport1.SyntaxTests.xml @@ -0,0 +1,168 @@ + + AVTransport + 1 + + + 1 + Valid Action And Valid InArgs + SetAVTransportURI + + 0 + any-string + any-string + + ACTION_AND_INARGS_ARE_VALID + + + 2 + Valid Action And Valid InArgs + SetNextAVTransportURI + + 0 + any-string + any-string + + ACTION_AND_INARGS_ARE_VALID + + + 3 + Valid Action And Valid InArgs + GetMediaInfo + + 0 + + ACTION_AND_INARGS_ARE_VALID + + + 4 + Valid Action And Valid InArgs + GetTransportInfo + + 0 + + ACTION_AND_INARGS_ARE_VALID + + + 5 + Valid Action And Valid InArgs + GetPositionInfo + + 0 + + ACTION_AND_INARGS_ARE_VALID + + + 6 + Valid Action And Valid InArgs + GetDeviceCapabilities + + 0 + + ACTION_AND_INARGS_ARE_VALID + + + 7 + Valid Action And Valid InArgs + GetTransportSettings + + 0 + + ACTION_AND_INARGS_ARE_VALID + + + 8 + Valid Action And Valid InArgs + Stop + + 0 + + ACTION_AND_INARGS_ARE_VALID + + + 9 + Valid Action And Valid InArgs + Play + + 0 + 1 + + ACTION_AND_INARGS_ARE_VALID + + + 10 + Valid Action And Valid InArgs + Pause + + 0 + + ACTION_AND_INARGS_ARE_VALID + + + 11 + Valid Action And Valid InArgs + Record + + 0 + + ACTION_AND_INARGS_ARE_VALID + + + 12 + Valid Action And Valid InArgs + Seek + + 0 + TRACK_NR + 1 + + ACTION_AND_INARGS_ARE_VALID + + + 13 + Valid Action And Valid InArgs + Next + + 0 + + ACTION_AND_INARGS_ARE_VALID + + + 14 + Valid Action And Valid InArgs + Previous + + 0 + + ACTION_AND_INARGS_ARE_VALID + + + 15 + Valid Action And Valid InArgs + SetPlayMode + + 0 + NORMAL + + ACTION_AND_INARGS_ARE_VALID + + + 16 + Valid Action And Valid InArgs + SetRecordQualityMode + + 0 + any-string + + ACTION_AND_INARGS_ARE_VALID + + + 17 + Valid Action And Valid InArgs + GetCurrentTransportActions + + 0 + + ACTION_AND_INARGS_ARE_VALID + + + \ No newline at end of file diff --git a/docs/xml data files/service/test cases/syntax/ConnectionManager1.SyntaxTests.xml b/docs/xml data files/service/test cases/syntax/ConnectionManager1.SyntaxTests.xml new file mode 100644 index 0000000..9bab408 --- /dev/null +++ b/docs/xml data files/service/test cases/syntax/ConnectionManager1.SyntaxTests.xml @@ -0,0 +1,48 @@ + + ConnectionManager + 1 + + + 1 + Valid Action And Valid InArgs + GetProtocolInfo + ACTION_AND_INARGS_ARE_VALID + + + 2 + Valid Action And Valid InArgs + PrepareForConnection + + any-string + any-string + -1 + Input + + ACTION_AND_INARGS_ARE_VALID + + + 3 + Valid Action And Valid InArgs + ConnectionComplete + + 0 + + ACTION_AND_INARGS_ARE_VALID + + + 4 + Valid Action And Valid InArgs + GetCurrentConnectionIDs + ACTION_AND_INARGS_ARE_VALID + + + 5 + Valid Action And Valid InArgs + GetCurrentConnectionInfo + + 0 + + ACTION_AND_INARGS_ARE_VALID + + + \ No newline at end of file diff --git a/docs/xml data files/service/test cases/syntax/ContentDirectory1.SyntaxTests.xml b/docs/xml data files/service/test cases/syntax/ContentDirectory1.SyntaxTests.xml new file mode 100644 index 0000000..b2b52bc --- /dev/null +++ b/docs/xml data files/service/test cases/syntax/ContentDirectory1.SyntaxTests.xml @@ -0,0 +1,146 @@ + + ContentDirectory + 1 + + + 1 + Valid Action And Valid InArgs + GetSearchCapabilities + ACTION_AND_INARGS_ARE_VALID + + + 2 + Valid Action And Valid InArgs + GetSortCapabilities + ACTION_AND_INARGS_ARE_VALID + + + 3 + Valid Action And Valid InArgs + GetSystemUpdateID + ACTION_AND_INARGS_ARE_VALID + + + 4 + Valid Action And Valid InArgs + Browse + + 0 + BrowseMetadata + dc:title + 0 + 0 + + + ACTION_AND_INARGS_ARE_VALID + + + 5 + Valid Action And Valid InArgs + Search + + 0 + dc:title contains "Rock" + dc:title + 0 + 0 + + + ACTION_AND_INARGS_ARE_VALID + + + 6 + Valid Action And Valid InArgs + CreateObject + + 0 + + <DIDL-Lite xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:upnp="urn:schemas-upnp-org:metadata-1-0/upnp/" xmlns="urn:schemas-upnp-org:metadata-1-0/DIDL-Lite/"> + <item id="" parentID="0" restricted="false"> + <dc:title>Test Object - CDS Syntax Text Case #6</dc:title> + <upnp:class>object.item</upnp:class> + </item> + </DIDL-Lite> + + + ACTION_AND_INARGS_ARE_VALID + + + 7 + Valid Action And Valid InArgs + DestroyObject + + 0 + + ACTION_AND_INARGS_ARE_VALID + + + 8 + Valid Action And Valid InArgs + UpdateObject + + 0 + any-string + any-string + + ACTION_AND_INARGS_ARE_VALID + + + 9 + Valid Action And Valid InArgs + ImportResource + + http://host/path/file + http://host/path/file + + ACTION_AND_INARGS_ARE_VALID + + + 10 + Valid Action And Valid InArgs + ExportResource + + http://host/path/file + http://host/path/file + + ACTION_AND_INARGS_ARE_VALID + + + 11 + Valid Action And Valid InArgs + StopTransferResource + + 0 + + ACTION_AND_INARGS_ARE_VALID + + + 12 + Valid Action And Valid InArgs + GetTransferProgress + + 0 + + ACTION_AND_INARGS_ARE_VALID + + + 13 + Valid Action And Valid InArgs + DeleteResource + + http://host/path/file + + ACTION_AND_INARGS_ARE_VALID + + + 14 + Valid Action And Valid InArgs + CreateReference + + 0 + 0 + + ACTION_AND_INARGS_ARE_VALID + + + diff --git a/docs/xml data files/service/test cases/syntax/RenderingControl1.SyntaxTests.xml b/docs/xml data files/service/test cases/syntax/RenderingControl1.SyntaxTests.xml new file mode 100644 index 0000000..531005e --- /dev/null +++ b/docs/xml data files/service/test cases/syntax/RenderingControl1.SyntaxTests.xml @@ -0,0 +1,347 @@ + + RenderingControl + 1 + + + 1 + Valid Action And Valid InArgs + ListPresets + + 0 + + ACTION_AND_INARGS_ARE_VALID + + + 2 + Valid Action And Valid InArgs + SelectPreset + + 0 + FactoryDefaults + + ACTION_AND_INARGS_ARE_VALID + + + 3 + Valid Action And Valid InArgs + GetBrightness + + 0 + + ACTION_AND_INARGS_ARE_VALID + + + 4 + Valid Action And Valid InArgs + SetBrightness + + 0 + 0 + + ACTION_AND_INARGS_ARE_VALID + + + 5 + Valid Action And Valid InArgs + GetContrast + + 0 + + ACTION_AND_INARGS_ARE_VALID + + + 6 + Valid Action And Valid InArgs + SetContrast + + 0 + 0 + + ACTION_AND_INARGS_ARE_VALID + + + 7 + Valid Action And Valid InArgs + GetRedVideoGain + + 0 + + ACTION_AND_INARGS_ARE_VALID + + + 8 + Valid Action And Valid InArgs + SetRedVideoGain + + 0 + 0 + + ACTION_AND_INARGS_ARE_VALID + + + 9 + Valid Action And Valid InArgs + GetGreenVideoGain + + 0 + + ACTION_AND_INARGS_ARE_VALID + + + 10 + Valid Action And Valid InArgs + SetGreenVideoGain + + 0 + 0 + + ACTION_AND_INARGS_ARE_VALID + + + 11 + Valid Action And Valid InArgs + GetBlueVideoGain + + 0 + + ACTION_AND_INARGS_ARE_VALID + + + 12 + Valid Action And Valid InArgs + SetBlueVideoGain + + 0 + 0 + + ACTION_AND_INARGS_ARE_VALID + + + 13 + Valid Action And Valid InArgs + GetRedVideoBlackLevel + + 0 + + ACTION_AND_INARGS_ARE_VALID + + + 14 + Valid Action And Valid InArgs + SetRedVideoBlackLevel + + 0 + 0 + + ACTION_AND_INARGS_ARE_VALID + + + 15 + Valid Action And Valid InArgs + GetGreenVideoBlackLevel + + 0 + + ACTION_AND_INARGS_ARE_VALID + + + 16 + Valid Action And Valid InArgs + SetGreenVideoBlackLevel + + 0 + 0 + + ACTION_AND_INARGS_ARE_VALID + + + 17 + Valid Action And Valid InArgs + GetBlueVideoBlackLevel + + 0 + + ACTION_AND_INARGS_ARE_VALID + + + 18 + Valid Action And Valid InArgs + SetBlueVideoBlackLevel + + 0 + 0 + + ACTION_AND_INARGS_ARE_VALID + + + 19 + Valid Action And Valid InArgs + GetColorTemperature + + 0 + + ACTION_AND_INARGS_ARE_VALID + + + 20 + Valid Action And Valid InArgs + SetColorTemperature + + 0 + 0 + + ACTION_AND_INARGS_ARE_VALID + + + 21 + Valid Action And Valid InArgs + GetHorizontalKeystone + + 0 + + ACTION_AND_INARGS_ARE_VALID + + + 22 + Valid Action And Valid InArgs + SetHorizontalKeystone + + 0 + 0 + + ACTION_AND_INARGS_ARE_VALID + + + 23 + Valid Action And Valid InArgs + GetVerticalKeystone + + 0 + + ACTION_AND_INARGS_ARE_VALID + + + 24 + Valid Action And Valid InArgs + SetVerticalKeystone + + 0 + 0 + + ACTION_AND_INARGS_ARE_VALID + + + 25 + Valid Action And Valid InArgs + GetSharpness + + 0 + + ACTION_AND_INARGS_ARE_VALID + + + 26 + Valid Action And Valid InArgs + SetSharpness + + 0 + 0 + + ACTION_AND_INARGS_ARE_VALID + + + 27 + Valid Action And Valid InArgs + GetMute + + 0 + Master + + ACTION_AND_INARGS_ARE_VALID + + + 28 + Valid Action And Valid InArgs + SetMute + + 0 + Master + 1 + + ACTION_AND_INARGS_ARE_VALID + + + 29 + Valid Action And Valid InArgs + GetVolume + + 0 + Master + + ACTION_AND_INARGS_ARE_VALID + + + 30 + Valid Action And Valid InArgs + SetVolume + + 0 + Master + 0 + + ACTION_AND_INARGS_ARE_VALID + + + 31 + Valid Action And Valid InArgs + GetVolumeDB + + 0 + Master + + ACTION_AND_INARGS_ARE_VALID + + + 32 + Valid Action And Valid InArgs + SetVolumeDB + + 0 + Master + 0 + + ACTION_AND_INARGS_ARE_VALID + + + 33 + Valid Action And Valid InArgs + GetVolumeDBRange + + 0 + Master + + ACTION_AND_INARGS_ARE_VALID + + + 34 + Valid Action And Valid InArgs + GetLoudness + + 0 + Master + + ACTION_AND_INARGS_ARE_VALID + + + 35 + Valid Action And Valid InArgs + SetLoudness + + 0 + Master + 1 + + ACTION_AND_INARGS_ARE_VALID + + +