diff --git a/docs/218762_218762.pdf b/docs/218762_218762.pdf deleted file mode 100644 index ce34c98..0000000 Binary files a/docs/218762_218762.pdf and /dev/null differ diff --git a/docs/AVTransport1.0.pdf b/docs/AVTransport1.0.pdf deleted file mode 100644 index 922caee..0000000 Binary files a/docs/AVTransport1.0.pdf and /dev/null differ diff --git a/docs/ConnectionManager1.0.pdf b/docs/ConnectionManager1.0.pdf deleted file mode 100644 index e9789ee..0000000 Binary files a/docs/ConnectionManager1.0.pdf and /dev/null differ diff --git a/docs/ContentDirectory1.0.pdf b/docs/ContentDirectory1.0.pdf deleted file mode 100644 index a281ed3..0000000 Binary files a/docs/ContentDirectory1.0.pdf and /dev/null differ diff --git a/docs/MediaRenderer1.0_000.pdf b/docs/MediaRenderer1.0_000.pdf deleted file mode 100644 index 0fb0c7f..0000000 Binary files a/docs/MediaRenderer1.0_000.pdf and /dev/null differ diff --git a/docs/MediaServer1.0.pdf b/docs/MediaServer1.0.pdf deleted file mode 100644 index b45bee7..0000000 Binary files a/docs/MediaServer1.0.pdf and /dev/null differ diff --git a/docs/RenderingControl1.0.pdf b/docs/RenderingControl1.0.pdf deleted file mode 100644 index bbd17b6..0000000 Binary files a/docs/RenderingControl1.0.pdf and /dev/null differ diff --git a/docs/UPnPAvArchtiecture0.83.pdf b/docs/UPnPAvArchtiecture0.83.pdf deleted file mode 100644 index 262845b..0000000 Binary files a/docs/UPnPAvArchtiecture0.83.pdf and /dev/null differ diff --git a/docs/draft-cohen-gena-client-01.txt b/docs/draft-cohen-gena-client-01.txt deleted file mode 100644 index 057de1d..0000000 --- a/docs/draft-cohen-gena-client-01.txt +++ /dev/null @@ -1,812 +0,0 @@ - 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 deleted file mode 100644 index 78f194b..0000000 --- a/docs/draft-goland-fxpp-01.txt +++ /dev/null @@ -1,348 +0,0 @@ - - -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 deleted file mode 100644 index 6296a05..0000000 --- a/docs/draft-goland-http-udp-04.txt +++ /dev/null @@ -1,928 +0,0 @@ - - -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 deleted file mode 100644 index 854285a..0000000 --- a/docs/draft-leach-uuids-guids-00.txt +++ /dev/null @@ -1,1040 +0,0 @@ - -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 deleted file mode 100644 index f58b491..0000000 --- a/docs/draft_cai_ssdp_v1_03.txt +++ /dev/null @@ -1,1044 +0,0 @@ -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 deleted file mode 100644 index 9362e07..0000000 --- a/docs/xml data files/device/MediaRenderer1.xml +++ /dev/null @@ -1,17 +0,0 @@ - - - - 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 deleted file mode 100644 index 87f82a9..0000000 --- a/docs/xml data files/device/MediaServer1.xml +++ /dev/null @@ -1,17 +0,0 @@ - - - - - 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 deleted file mode 100644 index e6a0a49..0000000 --- a/docs/xml data files/service/AVTransport1.xml +++ /dev/null @@ -1,477 +0,0 @@ - - - - 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 deleted file mode 100644 index 72d2114..0000000 --- a/docs/xml data files/service/ConnectionManager1.xml +++ /dev/null @@ -1,170 +0,0 @@ - - - - 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 deleted file mode 100644 index 9ad8157..0000000 --- a/docs/xml data files/service/ContentDirectory1.xml +++ /dev/null @@ -1,405 +0,0 @@ - - - - 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 deleted file mode 100644 index b2c66ce..0000000 --- a/docs/xml data files/service/RenderingControl1.xml +++ /dev/null @@ -1,718 +0,0 @@ - - - - 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 deleted file mode 100644 index 2f146b4..0000000 --- a/docs/xml data files/service/test cases/syntax/AVTransport1.SyntaxTests.xml +++ /dev/null @@ -1,168 +0,0 @@ - - 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 deleted file mode 100644 index 9bab408..0000000 --- a/docs/xml data files/service/test cases/syntax/ConnectionManager1.SyntaxTests.xml +++ /dev/null @@ -1,48 +0,0 @@ - - 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 deleted file mode 100644 index b2b52bc..0000000 --- a/docs/xml data files/service/test cases/syntax/ContentDirectory1.SyntaxTests.xml +++ /dev/null @@ -1,146 +0,0 @@ - - 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 deleted file mode 100644 index 531005e..0000000 --- a/docs/xml data files/service/test cases/syntax/RenderingControl1.SyntaxTests.xml +++ /dev/null @@ -1,347 +0,0 @@ - - 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 - - - diff --git a/pydvdread/__init__.py b/pydvdread/__init__.py new file mode 100644 index 0000000..cfe02e3 --- /dev/null +++ b/pydvdread/__init__.py @@ -0,0 +1,376 @@ +#!/usr/bin/env python + +from cdvdread import * +import itertools +import sys + +class DVDReadError(Exception): + pass + +__all__ = [ 'DVD', + ] + +dvd_domain_valid = [ DVD_READ_INFO_FILE, DVD_READ_INFO_BACKUP_FILE, + DVD_READ_MENU_VOBS, DVD_READ_TITLE_VOBS, ] +dvd_domain_valid_names = [ 'DVD_READ_INFO_FILE', 'DVD_READ_INFO_BACKUP_FILE', + 'DVD_READ_MENU_VOBS', 'DVD_READ_TITLE_VOBS', ] +try: + dvd_domain_valid = set(dvd_domain_valid) +except NameError: + pass + +# Make sure the library matches what we are compiled for +assert DVDREAD_VERSION == DVDVersion() + +DVDInit() + +def attribreprlist(obj, attrs): + return map(lambda x, y = obj: '%s: %s' % (x, repr(getattr(y, x))), itertools.ifilter(lambda x, y = obj: hasattr(y, x), attrs)) + +def bcdtoint(bcd): + base = 1 + ret = 0 + while bcd: + assert bcd % 16 < 10, 'invalid bcd digit in: %#x' % bcd + ret += bcd % 16 * base + base *= 10 + bcd /= 16 + return ret + +class DVDTime: + '''Should be able to perform math, though until I get the frame rate bit info, I really can't do anything about it.''' + __slots__ = [ '_hour', '_minute', '_second', '_frame_u', '_rate', '_seconds', '_frames' ] + hour = property(lambda x: x._hour) + minute = property(lambda x: x._minute) + second = property(lambda x: x._second) + frame = property(lambda x: x._frame) + rate = property(lambda x: x._rate) + ratestr = property(lambda x: x._ratestr) + seconds = property(lambda x: x._seconds) + frames = property(lambda x: x._frames) + + def __init__(self, dt): + '''Take a dvd time object that has the attributes hour, minute, second and frame_u (bits 6-7 are frame rate, bits 0-5 is frame.''' + self._hour = bcdtoint(dt.hour) + self._minute = bcdtoint(dt.minute) + self._second = bcdtoint(dt.second) + self._frame = bcdtoint(dt.frame_u & 0x3f) + fr = (dt.frame_u & 0xc0) >> 6 + assert fr in (1, 3), 'Unknown frame rate: %d' % fr + self._rate = [-1, 25.0, -1, 29.97 ][fr] + self._ratestr = [-1, '25.0', -1, '29.97' ][fr] + self._seconds = (self._hour * 60 + self._minute) * 60 + self._second + self._frame / self._rate + self._frames = self._seconds * self._rate + + def __int__(self): + return int(self._seconds) + + def __float__(self): + return self._seconds + + def __repr__(self): + return '%s@%s' % (str(self), self.ratestr) + + def hhmmss(self): + return '%02d:%02d:%02d' % (self._hour, self._minute, self._second) + + def __str__(self): + return '%02d:%02d:%02d.%02d' % (self._hour, self._minute, self._second, self._frame) + +class audio_attr: + pos = property(lambda x: x._pos) + lang = property(lambda x: x._lang) + audio_format = property(lambda x: x._audio_format) + lang_type = property(lambda x: x._lang_type) + application_mode = property(lambda x: x._application_mode) + quantization = property(lambda x: x._quantization) + sample_frequency = property(lambda x: x._sample_frequency) + channels = property(lambda x: x._channels) + + def __init__(self, audioattr, pos): + self._pos = pos + lc = audioattr.lang_code + self._lang = chr(lc>>8) + chr(lc & 255) + self._audio_format = audioattr.audio_format + self._lang_type = audioattr.lang_type + self._application_mode = audioattr.application_mode + self._quantization = audioattr.quantization + self._sample_frequency = audioattr.sample_frequency + self._channels = audioattr.channels + + def __repr__(self): + v = [ 'pos', 'lang', 'sample_frequency', 'channels' ] + return '' % ', '.join(attribreprlist(self, v)) + +class IFO: + ifodata = None # __del__ + + # VMGI + vmgi_mat = property(lambda x: x.ifodata.vmgi_mat) + tt_srpt = property(lambda x: x.ifodata.tt_srpt) + first_play_pgc = property(lambda x: x.ifodata.first_play_pgc) + ptl_mait = property(lambda x: x.ifodata.ptl_mait) + vts_atrt = property(lambda x: x.ifodata.vts_atrt) + txtdt_mgi = property(lambda x: x.ifodata.txtdt_mgi) + + # Common + pgci_ut = property(lambda x: x.ifodata.pgci_ut) + menu_c_adt = property(lambda x: x.ifodata.menu_c_adt) + menu_vobu_admap = property(lambda x: x.ifodata.menu_vobu_admap) + + # VTSI + vtsi_mat = property(lambda x: x.ifodata.vtsi_mat) + vts_ptt_srpt = property(lambda x: x.ifodata.vts_ptt_srpt) + vts_pgcit = property(lambda x: x.ifodata.vts_pgcit) + vts_tmapt = property(lambda x: x.ifodata.vts_tmapt) + vts_c_adt = property(lambda x: x.ifodata.vts_c_adt) + vts_vobu_admap = property(lambda x: x.ifodata.vts_vobu_admap) + + def __init__(self, dvd, i): + self.ifodata = ifoOpen(dvd.dvdreader, i) + self.dvd = dvd + self.audio = {} + + if i: + # we are a VTS, populate some data + for i in xrange(self.vtsi_mat.nr_of_vts_audio_streams): + j = audio_attr(audio_attr_getitem( + self.vtsi_mat.vts_audio_attr, i), i) + self.audio[j.lang] = j + + def __del__(self): + if self.ifodata: + ifoClose(self.ifodata) + self.ifodata = None + +class DVDProgram: + '''This represents a chapter in a title.''' + + time = property(lambda x: x._time) + size = property(lambda x: x._size) + + def __init__(self, dvdtitle, cpb): + self.dvdtitle = dvdtitle + self.cpb = cpb + self._time = DVDTime(self.cpb.playback_time) + self._size = (self.cpb.last_sector - self.cpb.first_sector + + 1) * self.dvdtitle.dvd.blocksize + + def blockiter(self, blkcnt = 16): + # last isn't inclusive + last = self.cpb.last_sector + 1 + for i in xrange(self.cpb.first_sector, last, blkcnt): + yield self.dvdtitle.vob.pread(min(blkcnt, last - i), i) + + def __iter__(self): + blklen = self.dvdtitle.dvd.blocksize + for i in self.blockiter(): + for j in xrange(0, len(i), blklen): + yield i[j:j + blklen] + + def __repr__(self): + return '' % \ + DVDTime(self.cpb.playback_time) + +class DVDFile: + dvdfile = None # __del__ + + def __init__(self, dvd, vts, dom): + assert dom in dvd_domain_valid, 'Must be one of: %s' % `dvd_domain_valid_names` + + self.dvdfile = DVDOpenFile(dvd.dvdreader, vts, dom) + if self.dvdfile is None: + raise ValueError, 'DVD file (%d, %d) does not exist' % (vts, dom) + self.vts = vts + self.dom = dom + self.dvd = dvd + + def __del__(self): + if self.dvdfile: + DVDCloseFile(self.dvdfile) + self.dvdfile = None + + def pread(self, nblocks, blkoff): + assert self.dom in (DVD_READ_MENU_VOBS, DVD_READ_TITLE_VOBS), \ + 'Must be of type DVD_READ_MENU_VOBS or DVD_READ_TITLE_VOBS.' + + buf = malloc_void(nblocks * self.dvd.blocksize) + assert buf, 'buf allocation failed' + try: + b = DVDReadBlocks(self.dvdfile, blkoff, nblocks, + voidptr_to_ucharptr(buf)) + ret = cdata(buf, b * self.dvd.blocksize) + return ret + finally: + free_void(buf) + + def seek(self, pos, whence = 0): + assert whence == 0, 'Only SEEK_SET is supported' + return DVDFileSeek(self.dvdfile, pos) + + def read(self, *args): + if len(args) == 0: + #read it all + res = [] + data = 1 + while data: + data = self.read(65536) + res.append(data) + return ''.join(res) + + assert len(args) == 1, 'Only takes one argument: count' + buf = malloc_void(*args) + assert buf, 'buf allocation failed' + try: + b = DVDReadBytes(self.dvdfile, buf, *args) + ret = cdata(buf, b) + return ret + finally: + free_void(buf) + + def __len__(self): + return DVDFileSize(self.dvdfile) * self.dvd.blocksize + +class DVDTitle: + '''This is a title.''' + + time = property(lambda x: x._time) + audio = property(lambda x: x.vts.audio) + + def selectaudio(self, lang): + if isinstance(lang, basestring): + lang = [ lang ] + + for l in lang: + try: + return self.audio[l] + except KeyError: + pass + + for l in self.lang: + if l.pos == 0: + return l + + def __init__(self, dvd, vts, ttu): + '''dvd is of class DVD, vts is the vts number one based, and ttu is the sub-vts one based.''' + + self.dvd = dvd + self.vts = dvd.getifo(vts) + assert ttu > 0 and ttu <= self.vts.vts_pgcit.nr_of_pgci_srp + self.pgci = pgci_srp_getitem(self.vts.vts_pgcit.pgci_srp, ttu - 1).pgc + self.ttu = ttu + self.vob = DVDFile(dvd, vts, DVD_READ_TITLE_VOBS) + self._time = DVDTime(self.pgci.playback_time) + + def __len__(self): + return self.pgci.nr_of_programs + + def __getitem__(self, key): + if key < 0 or key >= len(self): + raise IndexError + assert key < self.pgci.nr_of_cells, \ + 'key cannot be mapped from program to cell(%d)' % \ + (self.pgci.nr_of_programs, self.pgci.nr_of_cells) + # cell is stored starting at 1, adjust to 0 + cell = uchar_getitem(self.pgci.program_map, key) - 1 + cell_playback = cell_playback_getitem(self.pgci.cell_playback, + cell) + return DVDProgram(self, cell_playback) + + def __repr__(self): + return '' % (len(self), self.time) + + def data(self): + '''Returns the data in blocks for the title.''' + for i in self: + for j in i: + yield j + +class discid: + __slots__ = [ '_discid' ] + discid = property(lambda x: x._discid) + + def __init__(self, discid): + self._discid = discid + + def __str__(self): + return ''.join(map(lambda x: '%02x' % ord(x), self.discid)) + + def __repr__(self): + return '' % ''.join(map(lambda x: '%02x' % ord(x), self.discid)) + +class DVD: + '''Children must keep a reference to this object so that we don't close + the dvd before all the files are closed. This does mean children will + need to know the insides of this class, but that is fine since it's all + internal to this implementation anyways.''' + + dvdreader = None # __del__ + + blocksize = property(lambda x: x._blocksize) + volid = property(lambda x: x._volid) + volsetid = property(lambda x: x._volsetid) + cache = property(lambda x: DVDUDFCacheLevel(x.dvdreader, -1), lambda x, y: DVDUDFCacheLevel(x.dvdreader, bool(y))) + + def __init__(self, path): + self.dvdreader = DVDOpen(path) + if self.dvdreader is None: + raise ValueError, 'path is not a DVD' + + self._discidval = None + # XXX - this may need to be dynamicly probed + self._blocksize = 2048 + + # pull in the volid and volsetid + r, volid, volsetid = DVDUDFVolumeInfo(self.dvdreader, 32, 128) + if r != 0: + self._volid = volid[:volid.index('\x00')].decode('latin-1') + self._volsetid = volsetid + else: + # Fall back to ISO, shouldn't happen as all + # DVD's are UDF + r, volid, voldsetid = DVDISOVolumeInfo(self.dvdreader, 33, 128) + assert r == 0 + # Techinically more restrictive [A-Z0-9_] + self._volid = volid[:volid.index('\x00')].decode('ascii') + self._volsetid = volsetid + + self.vmg = self.getifo(0) + self._len = self.vmg.tt_srpt.nr_of_srpts + + def __del__(self): + if self.dvdreader: + DVDClose(self.dvdreader) + self.dvdreader = None + + def getifo(self, i): + return IFO(self, i) + + def _discid(self): + if self._discidval is not None: + return self._discidval + + buf = malloc_void(16) + assert buf, 'buf allocation failed' + try: + r = DVDDiscID(self.dvdreader, voidptr_to_ucharptr(buf)) + if r == -1: + raise DVDReadError, "failed to compute disc id" + self._discidval = discid(cdata(buf, 16)) + return self._discidval + finally: + free_void(buf) + discid = property(_discid) + + def __len__(self): + return self._len + + def __getitem__(self, key): + if key < 0 or key >= len(self): + raise IndexError + title = title_info_getitem(self.vmg.tt_srpt.title, key) + + return DVDTitle(self, title.title_set_nr, title.vts_ttn) + + def __repr__(self): + return '' % (self._volid, self.discid, len(self)) diff --git a/pydvdread/dvdread.i b/pydvdread/dvdread.i new file mode 100644 index 0000000..f3b1347 --- /dev/null +++ b/pydvdread/dvdread.i @@ -0,0 +1,84 @@ +// File : dvdread.i +%module cdvdread +%include "typemaps.i" +%include "stdint.i" + +%include "cmalloc.i" +%include "carrays.i" +%include "cdata.i" +%allocators(void); + +%include "cpointer.i" +%pointer_cast(void *, unsigned char *, voidptr_to_ucharptr); + +typedef long ssize_t; +typedef long long off_t; + +%{ +#include "dvdread/dvd_reader.h" +#include "dvdread/ifo_read.h" +#include "dvdread/nav_read.h" +%} + +%typemap (in,numinputs=1) (unsigned char *uc128, unsigned int uc128) (unsigned char tempa[128], int tempb) { + $1 = tempa; + $2 = tempb = PyInt_AsLong($input); + if (tempb <= 0 || tempb > 128) { + PyErr_SetString(PyExc_ValueError, "int out of range (0,128]"); + return NULL; + } +} + +%typemap (argout) (unsigned char *uc128, unsigned int uc128) { + $result = SWIG_Python_AppendOutput($result, PyString_FromStringAndSize(tempa$argnum, tempb$argnum)); +} + +%typemap (in,numinputs=1) (char *c33, unsigned int c33) (char tempa[33], int tempb) { + $1 = tempa; + $2 = tempb = PyInt_AsLong($input); + if (tempb <= 0 || tempb > 33) { + PyErr_SetString(PyExc_ValueError, "int out of range (0,33]"); + return NULL; + } +} + +%typemap (argout) (char *c33, unsigned int c33) { + $result = SWIG_Python_AppendOutput($result, PyString_FromStringAndSize(tempa$argnum, tempb$argnum)); +} + +int DVDUDFVolumeInfo( dvd_reader_t *, char *c33, unsigned int c33, + unsigned char *uc128, unsigned int uc128); +int DVDISOVolumeInfo( dvd_reader_t *, char *c33, unsigned int c33, + unsigned char *uc128, unsigned int uc128); + +/* Clear them */ +%typemap (in,numinputs=1) (unsigned char *uc128, unsigned int uc128) (unsigned char tempa[128], int tempb); +%typemap (argout) (unsigned char *uc128, unsigned int uc128); +%typemap (in,numinputs=1) (char *c33, unsigned int c33) (char tempa[33], int tempb); +%typemap (argout) (char *c33, unsigned int c33); + +%include dvdread/dvd_reader.h + +%include dvdread/ifo_read.h + +%include +%include dvdread/ifo_types.h + +%array_functions(audio_attr_t, audio_attr) +%array_functions(cell_playback_t, cell_playback) +%array_functions(cell_position_t, cell_position) +%array_functions(map_ent_t, map_ent) +%array_functions(pgc_program_map_t, pgc_program_map) +%array_functions(pgci_lu_t, pgci_lu) +%array_functions(pgci_srp_t, pgci_srp) +%array_functions(ptt_info_t, ptt_info) +%array_functions(subp_attr_t, subp_attr) +%array_functions(title_info_t, title_info) +%array_functions(ttu_t, ttu) +%array_functions(txtdt_lu_t, txtdt_lu) +%array_functions(unsigned char, uchar) +%array_functions(vm_cmd_t, vm_cmd) +%array_functions(vts_attributes_t, vts_attributes) +%array_functions(vts_tmap_t, vts_tmap) + +%include dvdread/nav_read.h diff --git a/pydvdread/setup.py b/pydvdread/setup.py new file mode 100644 index 0000000..e81c647 --- /dev/null +++ b/pydvdread/setup.py @@ -0,0 +1,23 @@ +#!/usr/bin/env python + +from distutils.core import setup, Extension +import os.path + +dvdreaddir = '/opt/local' +dvdreaddirinc = os.path.join(dvdreaddir, 'include') +dvdreaddirlib = os.path.join(dvdreaddir, 'lib') + +setup(name = "pydvdread", version = "0.1", + description = "Python libdvdread interface", + author = "John-Mark Gurney", + author_email = "gurney_j@resnet.uoregon.edu", + packages = [ 'pydvdread' ], + package_dir = { 'pydvdread': '.' }, + ext_package = "pydvdread", + ext_modules = [ Extension("_cdvdread", [ "dvdread.i" ], + swig_opts = [ '-I/usr/include', '-I%s' % dvdreaddirinc ], + include_dirs = [ dvdreaddirinc, '/usr/include' ], + library_dirs = [ dvdreaddirlib, ], + libraries = [ 'dvdread' ]), + ] +) diff --git a/pydvdread/test.data/sg1_v3 b/pydvdread/test.data/sg1_v3 new file mode 100644 index 0000000..cbddf8d --- /dev/null +++ b/pydvdread/test.data/sg1_v3 @@ -0,0 +1,235 @@ + +volid: u'SG1_V3' volsetid: '\x082a55bf68\x00\x00\x00\x00\x00\x00\x00\x00SG1_V3\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x17' cache: 1 discid: 'y\xb93\xea\xb9\x85bxS\x94\x98\xd1\x11\x88.2' + +0 +'DVDVIDEO-VMG\x00\x00\x05d\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x06\x00\x11\x00\xfe\x00\x00\x00\x01\x00\x01\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x03' +14336 +vmg +ifo: +ident: 'DVDVIDEO-VMG' +# vts: 3 +provider: '' +nr_of_srpts: 7 + > +playbacktype: 0 0 1 0 1 0 0 +# angles: 1 +# ptts: 5 +parental id: 0 +title set #: 1 +vts ttn: 1 + > +playbacktype: 0 0 1 0 1 0 0 +# angles: 1 +# ptts: 5 +parental id: 0 +title set #: 1 +vts ttn: 2 + > +playbacktype: 0 0 1 0 1 0 0 +# angles: 1 +# ptts: 5 +parental id: 0 +title set #: 1 +vts ttn: 3 + > +playbacktype: 0 0 1 0 1 0 0 +# angles: 1 +# ptts: 5 +parental id: 0 +title set #: 1 +vts ttn: 4 + > +playbacktype: 0 0 1 0 1 0 0 +# angles: 1 +# ptts: 5 +parental id: 0 +title set #: 1 +vts ttn: 5 + > +playbacktype: 0 0 1 0 1 0 0 +# angles: 1 +# ptts: 5 +parental id: 0 +title set #: 2 +vts ttn: 1 + > +playbacktype: 0 0 1 0 1 0 0 +# angles: 1 +# ptts: 1 +parental id: 0 +title set #: 3 +vts ttn: 1 +vts +ifo: +['__del__', '__doc__', '__init__', '__module__', 'dvd', 'first_play_pgc', 'ifodata', 'menu_c_adt', 'menu_vobu_admap', 'pgci_ut', 'ptl_mait', 'tt_srpt', 'txtdt_mgi', 'vmgi_mat', 'vts_atrt', 'vts_c_adt', 'vts_pgcit', 'vts_ptt_srpt', 'vts_tmapt', 'vts_vobu_admap', 'vtsi_mat'] +# of srpts: 5 +title #: 0 +# of ptts: 5 +pgcn: 1 +pgn: 1 +pgcn: 1 +pgn: 2 +pgcn: 1 +pgn: 3 +pgcn: 1 +pgn: 4 +pgcn: 1 +pgn: 5 +title #: 1 +# of ptts: 5 +pgcn: 2 +pgn: 1 +pgcn: 2 +pgn: 2 +pgcn: 2 +pgn: 3 +pgcn: 2 +pgn: 4 +pgcn: 2 +pgn: 5 +title #: 2 +# of ptts: 5 +pgcn: 3 +pgn: 1 +pgcn: 3 +pgn: 2 +pgcn: 3 +pgn: 3 +pgcn: 3 +pgn: 4 +pgcn: 3 +pgn: 5 +title #: 3 +# of ptts: 5 +pgcn: 4 +pgn: 1 +pgcn: 4 +pgn: 2 +pgcn: 4 +pgn: 3 +pgcn: 4 +pgn: 4 +pgcn: 4 +pgn: 5 +title #: 4 +# of ptts: 5 +pgcn: 5 +pgn: 1 +pgcn: 5 +pgn: 2 +pgcn: 5 +pgn: 3 +pgcn: 5 +pgn: 4 +pgcn: 5 +pgn: 5 +pgc: 5 +nr_of_progs: 5 +nr_of_cells: 5 +time: 0:44:10.00 +program_map[0]: 1 +program_map[1]: 2 +program_map[2]: 3 +program_map[3]: 4 +program_map[4]: 5 +cell_playback[0]: 0-199844 0:11:48.18 +cell_playback[1]: 199845-327632 0:06:57.08 +cell_playback[2]: 327633-444493 0:07:21.19 +cell_playback[3]: 444494-577181 0:07:54.25 +cell_playback[4]: 577182-734711 0:10:07.20 +nr_of_progs: 5 +nr_of_cells: 5 +time: 0:44:10.00 +program_map[0]: 1 +program_map[1]: 2 +program_map[2]: 3 +program_map[3]: 4 +program_map[4]: 5 +cell_playback[0]: 734712-936408 0:12:20.08 +cell_playback[1]: 936409-1064831 0:08:23.20 +cell_playback[2]: 1064832-1215444 0:09:32.23 +cell_playback[3]: 1215445-1332766 0:06:33.10 +cell_playback[4]: 1332767-1443075 0:07:19.29 +nr_of_progs: 5 +nr_of_cells: 5 +time: 0:44:10.00 +program_map[0]: 1 +program_map[1]: 2 +program_map[2]: 3 +program_map[3]: 4 +program_map[4]: 5 +cell_playback[0]: 1443076-1661816 0:12:44.27 +cell_playback[1]: 1661817-1768975 0:06:17.19 +cell_playback[2]: 1768976-1937529 0:09:58.04 +cell_playback[3]: 1937530-2090623 0:08:52.13 +cell_playback[4]: 2090624-2177682 0:06:16.27 +nr_of_progs: 5 +nr_of_cells: 5 +time: 0:44:10.00 +program_map[0]: 1 +program_map[1]: 2 +program_map[2]: 3 +program_map[3]: 4 +program_map[4]: 5 +cell_playback[0]: 2177683-2267107 0:05:41.20 +cell_playback[1]: 2267108-2432141 0:10:18.17 +cell_playback[2]: 2432142-2682901 0:13:44.00 +cell_playback[3]: 2682902-2873976 0:10:16.21 +cell_playback[4]: 2873977-2911807 0:04:09.02 +nr_of_progs: 5 +nr_of_cells: 5 +time: 0:44:10.00 +program_map[0]: 1 +program_map[1]: 2 +program_map[2]: 3 +program_map[3]: 4 +program_map[4]: 5 +cell_playback[0]: 2911808-3088276 0:10:21.10 +cell_playback[1]: 3088277-3229786 0:08:30.26 +cell_playback[2]: 3229787-3393508 0:09:15.13 +cell_playback[3]: 3393509-3558306 0:10:01.01 +cell_playback[4]: 3558307-3646643 0:06:01.10 +vts +ifo: +['__del__', '__doc__', '__init__', '__module__', 'dvd', 'first_play_pgc', 'ifodata', 'menu_c_adt', 'menu_vobu_admap', 'pgci_ut', 'ptl_mait', 'tt_srpt', 'txtdt_mgi', 'vmgi_mat', 'vts_atrt', 'vts_c_adt', 'vts_pgcit', 'vts_ptt_srpt', 'vts_tmapt', 'vts_vobu_admap', 'vtsi_mat'] +# of srpts: 1 +title #: 0 +# of ptts: 5 +pgcn: 1 +pgn: 1 +pgcn: 1 +pgn: 2 +pgcn: 1 +pgn: 3 +pgcn: 1 +pgn: 4 +pgcn: 1 +pgn: 5 +pgc: 1 +nr_of_progs: 5 +nr_of_cells: 5 +time: 0:00:30.16 +program_map[0]: 1 +program_map[1]: 2 +program_map[2]: 3 +program_map[3]: 4 +program_map[4]: 5 +cell_playback[0]: 0-6449 0:00:11.28 +cell_playback[1]: 6450-6524 0:00:05.00 +cell_playback[2]: 6525-6603 0:00:07.00 +cell_playback[3]: 6604-7475 0:00:06.03 +cell_playback[4]: 7476-7479 0:00:00.15 +vts +ifo: +['__del__', '__doc__', '__init__', '__module__', 'dvd', 'first_play_pgc', 'ifodata', 'menu_c_adt', 'menu_vobu_admap', 'pgci_ut', 'ptl_mait', 'tt_srpt', 'txtdt_mgi', 'vmgi_mat', 'vts_atrt', 'vts_c_adt', 'vts_pgcit', 'vts_ptt_srpt', 'vts_tmapt', 'vts_vobu_admap', 'vtsi_mat'] +# of srpts: 1 +title #: 0 +# of ptts: 1 +pgcn: 1 +pgn: 1 +pgc: 1 +nr_of_progs: 1 +nr_of_cells: 1 +time: 0:06:20.28 +program_map[0]: 1 +cell_playback[0]: 23-96414 0:06:20.28 diff --git a/pydvdread/test.py b/pydvdread/test.py new file mode 100644 index 0000000..a6ac585 --- /dev/null +++ b/pydvdread/test.py @@ -0,0 +1,82 @@ +#!/usr/bin/env python + +import pydvdread +import sys + +def bcdtoint(bcd): + base = 1 + ret = 0 + while bcd: + assert bcd % 16 < 10, 'invalid bcd digit in: %#x' % bcd + ret += bcd % 16 * base + base *= 10 + bcd /= 16 + return ret + +def strdvdtime(tobj): + return '%x:%02x:%02x.%02x' % (tobj.hour, tobj.minute, tobj.second, + tobj.frame_u & 0x3f) + +def dumppgc(j): + print 'nr_of_progs:', j.nr_of_programs + print 'nr_of_cells:', j.nr_of_cells + print 'time:', strdvdtime(j.playback_time) + for k in range(j.nr_of_programs): + print 'program_map[%d]:' % k, pydvdread.uchar_getitem( + j.program_map, k) + for k in range(j.nr_of_cells): + l = pydvdread.cell_playback_getitem(j.cell_playback, k) + print 'cell_playback[%d]:' % k, '%d-%d' % (l.first_sector, + l.last_sector), strdvdtime(l.playback_time) + +try: + dvd = pydvdread.DVD('/dev/null') +except ValueError: + pass +except: + assert 0, 'Failed to fail.' + +dvd = pydvdread.DVD('/dev/rdisk1') +print dvd, ', '.join(map(repr, dvd)) +try: + print `dvd[(5, 5)]` +except IndexError: + pass +except: + assert 0, 'Failed to fail.' + +print 'vmg' +ifo = dvd.getifo(0) +assert ifo.txtdt_mgi is None +print 'ifo:', `ifo` +print '# vts:', ifo.vmgi_mat.vmg_nr_of_title_sets +print 'provider:', `ifo.vmgi_mat.provider_identifier` +print 'nr_of_srpts:', ifo.tt_srpt.nr_of_srpts +for i in range(ifo.tt_srpt.nr_of_srpts): + print `ifo.tt_srpt.title` + j = pydvdread.title_info_getitem(ifo.tt_srpt.title, i) + print 'playbacktype:', j.pb_ty.multi_or_random_pgc_title, j.pb_ty.jlc_exists_in_cell_cmd, j.pb_ty.jlc_exists_in_prepost_cmd, j.pb_ty.jlc_exists_in_button_cmd, j.pb_ty.jlc_exists_in_tt_dom, j.pb_ty.chapter_search_or_play, j.pb_ty.title_or_time_play + print '# angles:', j.nr_of_angles + print '# ptts:', j.nr_of_ptts + print 'parental id:', j.parental_id + print 'title set #:', j.title_set_nr + print 'vts ttn:', j.vts_ttn + +for ifonum in range(ifo.vmgi_mat.vmg_nr_of_title_sets): + print 'vts' + ifo = dvd.getifo(1 + ifonum) + print 'ifo:', `ifo` + print dir(ifo) + print '# of srpts:', ifo.vts_ptt_srpt.nr_of_srpts + for i in range(ifo.vts_ptt_srpt.nr_of_srpts): + print 'title #:', i + j = pydvdread.ttu_getitem(ifo.vts_ptt_srpt.title, i) + print '# of ptts:', j.nr_of_ptts + for i in range(j.nr_of_ptts): + k = pydvdread.ptt_info_getitem(j.ptt, i) + print 'pgcn:', k.pgcn + print 'pgn:', k.pgn + + print 'pgc:', `ifo.vts_pgcit.nr_of_pgci_srp` + for i in range(ifo.vts_pgcit.nr_of_pgci_srp): + dumppgc(pydvdread.pgci_srp_getitem(ifo.vts_pgcit.pgci_srp, i).pgc)