SIPPING J. Rosenberg Internet-Draft Cisco Systems Expires: August 24, 2005 H. Schulzrinne Columbia University O. Levin, Ed. Microsoft Corporation February 20, 2005 A Session Initiation Protocol (SIP) Event Package for Conference State draft-ietf-sipping-conference-package-09 Status of this Memo This document is an Internet-Draft and is subject to all provisions of Section 3 of RFC 3667. By submitting this Internet-Draft, each author represents that any applicable patent or other IPR claims of which he or she is aware have been or will be disclosed, and any of which he or she become aware will be disclosed, in accordance with RFC 3668. 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. This Internet-Draft will expire on August 24, 2005. Copyright Notice Copyright (C) The Internet Society (2005). Abstract This document defines a conference event package for the Session Initiation Protocol (SIP) Events framework, along with a data format Rosenberg, et al. Expires August 24, 2005 [Page 1] Internet-Draft Conference Package February 2005 used in notifications for this package. The conference package allows users to subscribe to a conference URI. Notifications are sent about changes in the membership of this conference and optionally about changes in the state of additional conference components. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 5 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . 5 3. Conference Event Package . . . . . . . . . . . . . . . . . . 5 3.1 Event Package Name . . . . . . . . . . . . . . . . . . . . 5 3.2 SUBSCRIBE Bodies . . . . . . . . . . . . . . . . . . . . . 6 3.3 Subscription Duration . . . . . . . . . . . . . . . . . . 6 3.4 NOTIFY Bodies . . . . . . . . . . . . . . . . . . . . . . 6 3.5 Notifier Processing of SUBSCRIBE Requests . . . . . . . . 7 3.6 Notifier Generation of NOTIFY Requests . . . . . . . . . . 7 3.7 Subscriber Processing of NOTIFY Requests . . . . . . . . . 7 3.8 Handling of Forked Requests . . . . . . . . . . . . . . . 8 3.9 Rate of Notifications . . . . . . . . . . . . . . . . . . 8 3.10 State Agents . . . . . . . . . . . . . . . . . . . . . . 8 4. Conference Document . . . . . . . . . . . . . . . . . . . . 8 4.1 Format . . . . . . . . . . . . . . . . . . . . . . . . . . 8 4.2 Namespace . . . . . . . . . . . . . . . . . . . . . . . . 8 4.3 Versioning . . . . . . . . . . . . . . . . . . . . . . . . 8 4.4 State and Partial Notifications . . . . . . . . . . . . . 9 4.5 Element Keys . . . . . . . . . . . . . . . . . . . . . . . 9 4.6 Constructing Coherent State Procedure . . . . . . . . . . 10 5. Conference Data . . . . . . . . . . . . . . . . . . . . . . 11 5.1 conference-type . . . . . . . . . . . . . . . . . . . . . 11 5.1.1 conference-description of conference-description-type . . . . . . . . . . . . . 12 5.1.2 host-info of host-type . . . . . . . . . . . . . . . . 12 5.1.3 conference-state of conference-state-type . . . . . . 12 5.1.4 users of users-type . . . . . . . . . . . . . . . . . 12 5.1.5 sidebars-by-ref of uris-type . . . . . . . . . . . . . 12 5.1.6 sidebar-by-val of conference-type . . . . . . . . . . 12 5.2 conference-description-type . . . . . . . . . . . . . . . 13 5.2.1 display-text of string type . . . . . . . . . . . . . 13 5.2.2 subject of string type . . . . . . . . . . . . . . . . 13 5.2.3 free-text of string type . . . . . . . . . . . . . . . 13 5.2.4 keywords of keywords-type . . . . . . . . . . . . . . 13 5.2.5 conf-uris of uris-type . . . . . . . . . . . . . . . . 13 5.2.6 service-uris of uris-type . . . . . . . . . . . . . . 14 5.2.7 maximum-user-count of user-count-type . . . . . . . . 14 5.2.8 available-media of conference-media-type . . . . . . . 14 5.3 host-type . . . . . . . . . . . . . . . . . . . . . . . . 14 5.3.1 display-text of string type . . . . . . . . . . . . . 15 Rosenberg, et al. Expires August 24, 2005 [Page 2] Internet-Draft Conference Package February 2005 5.3.2 web-page of anyURI type . . . . . . . . . . . . . . . 15 5.3.3 uris of uris-type . . . . . . . . . . . . . . . . . . 15 5.4 conference-state-type . . . . . . . . . . . . . . . . . . 15 5.4.1 user-count of user-count-type . . . . . . . . . . . . 15 5.4.2 active of Boolean type . . . . . . . . . . . . . . . . 15 5.4.3 locked of Boolean type . . . . . . . . . . . . . . . . 15 5.4.4 active-media of conference-media-type . . . . . . . . 15 5.5 conference-media-type . . . . . . . . . . . . . . . . . . 16 5.5.1 conference-medium-type . . . . . . . . . . . . . . . . 16 5.5.1.1 display-text of string type . . . . . . . . . . . 16 5.5.1.2 type of string type . . . . . . . . . . . . . . . 16 5.5.1.3 label of string type . . . . . . . . . . . . . . . 17 5.6 user-type . . . . . . . . . . . . . . . . . . . . . . . . 17 5.6.1 display-text of string type . . . . . . . . . . . . . 17 5.6.2 associated-aors of anyURI type . . . . . . . . . . . . 17 5.6.3 roles of user-roles-type . . . . . . . . . . . . . . . 17 5.6.4 language of language type . . . . . . . . . . . . . . 18 5.6.5 cascaded-focus of anyURI type . . . . . . . . . . . . 18 5.6.6 endpoint of endpoint-type . . . . . . . . . . . . . . 18 5.7 endpoint-type . . . . . . . . . . . . . . . . . . . . . . 19 5.7.1 display-text of string type . . . . . . . . . . . . . 19 5.7.2 referred of execution-type . . . . . . . . . . . . . . 19 5.7.3 status of endpoint-status-type . . . . . . . . . . . . 20 5.7.4 joining-method of joining-type . . . . . . . . . . . . 21 5.7.5 joining-info of execution-type . . . . . . . . . . . . 21 5.7.6 disconnection-method of disconnection-type . . . . . . 21 5.7.7 disconnection-info of execution-type . . . . . . . . . 22 5.7.8 media of media-type . . . . . . . . . . . . . . . . . 22 5.7.9 call-info of call-type . . . . . . . . . . . . . . . . 22 5.7.10 media-type . . . . . . . . . . . . . . . . . . . . . 23 5.7.10.1 display-text of string type . . . . . . . . . . 23 5.7.10.2 type of string type . . . . . . . . . . . . . . 23 5.7.10.3 label of string type . . . . . . . . . . . . . . 23 5.7.10.4 src-id of string type . . . . . . . . . . . . . 24 5.7.10.5 status of media-status-type . . . . . . . . . . 24 6. XML Schema . . . . . . . . . . . . . . . . . . . . . . . . . 24 7. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 32 7.1 Basic Example . . . . . . . . . . . . . . . . . . . . . . 32 7.2 Rich Example . . . . . . . . . . . . . . . . . . . . . . . 34 8. Security Considerations . . . . . . . . . . . . . . . . . . 38 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . 38 9.1 conference Event Package Registration . . . . . . . . . . 38 9.2 application/conference-info+xml MIME Registration . . . . 39 9.3 URN Sub-Namespace Registration for urn:ietf:params:xml:ns:conference-info . . . . . . . . . . 39 9.4 XML Schema Registration . . . . . . . . . . . . . . . . . 40 9.5 URI Purposes Sub-registry Establishment . . . . . . . . . 40 10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 41 Rosenberg, et al. Expires August 24, 2005 [Page 3] Internet-Draft Conference Package February 2005 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 41 11.1 Normative References . . . . . . . . . . . . . . . . . . 41 11.2 Informative References . . . . . . . . . . . . . . . . . 42 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . 43 Intellectual Property and Copyright Statements . . . . . . . 45 Rosenberg, et al. Expires August 24, 2005 [Page 4] Internet-Draft Conference Package February 2005 1. Introduction The Session Initiation Protocol (SIP) [7]Events Framework [8] defines general mechanisms for subscribing to, and receiving notifications of, events within SIP networks. It introduces the notion of a package, which is a specific "instantiation" of the events framework for a well-defined set of events. Here, we define an event package for SIP conferences. This package provides the conference notification service as outlined in the SIP conferencing framework [18]. As described there, subscriptions to a conference URI are routed to the focus that is handling the conference. It acts as the notifier, and provides clients with updates on conference state. The information provided by this package is comprised of conference identifier(s), conference participants (optionally with their statuses and media description), conference sidebars, conference service URIs, etc. 2. Terminology In this document, the key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" are to be interpreted as described in RFC 2119 [1] and indicate requirement levels for compliant implementations. 3. Conference Event Package The conference event package allows a user to subscribe to a conference. In SIP, conferences are represented by URIs. These URIs route to a SIP user agent, called a focus, that is responsible for ensuring that all users in the conference can communicate with each other, as described in Conferencing Framework [18]. The focus has sufficient information about the state of the conference to inform subscribers about it. It is possible that a participant in the conference may in fact be another focus. In order to provide a more complete participant list, the focus MAY subscribe to the conference package of the other focus to discover the participant list in the cascaded conference. This information can then be included in notifications by use of the element as specified by this package. This section provides the details for defining a SIP-specific event notification package, as specified by RFC 3265 [8]. 3.1 Event Package Name The name of this event package is "conference". This package name is Rosenberg, et al. Expires August 24, 2005 [Page 5] Internet-Draft Conference Package February 2005 carried in the Event and Allow-Events header, as defined in RFC 3265 [8]. 3.2 SUBSCRIBE Bodies A SUBSCRIBE for a conference package MAY contain a body. This body defines a filter to apply to the subscription. Filter documents are not specified in this document, and at the time of writing, are expected to be the subject of future standardization activity. A SUBSCRIBE for a conference package MAY be sent without a body. This implies the default subscription filtering policy. The default policy is: o Notifications are generated every time there is any change in the state of the conference. o Notifications do not normally contain full state; rather, they only indicate the state that has changed. The exception is a NOTIFY sent in response to a SUBSCRIBE. These NOTIFYs contain the full state of the information requested by the subscriber. 3.3 Subscription Duration The default expiration time for a subscription to a conference is one hour. Once the conference ends, all subscriptions to that particular conference are terminated, with a reason of "noresource" as defined in RFC 3265 [8]. 3.4 NOTIFY Bodies As described in RFC 3265 [8], the NOTIFY message will contain bodies that describe the state of the subscribed resource. This body is in a format listed in the Accept header field of the SUBSCRIBE, or a package-specific default if the Accept header field was omitted from the SUBSCRIBE. In this event package, the body of the notification contains a conference information document. This document describes the state of a conference. All subscribers and notifiers MUST support the "application/conference-info+xml" data format described in Section 5. The subscribe request MAY contain an Accept header field. If no such header field is present, it has a default value of "application/conference-info+xml". If the header field is present, it MUST include "application/conference-info+xml", and MAY include any other types. Of course, the notifications generated by the server MUST be in one of the formats specified in the Accept header field in the SUBSCRIBE request. Rosenberg, et al. Expires August 24, 2005 [Page 6] Internet-Draft Conference Package February 2005 3.5 Notifier Processing of SUBSCRIBE Requests The conference information contains very sensitive information. Therefore, all subscriptions SHOULD be authenticated and then authorized before approval. Authorization policy is at the discretion of the administrator, as always. However, a few recommendations can be made. It is RECOMMENDED that all users in the conference be allowed to subscribe to the conference event package. 3.6 Notifier Generation of NOTIFY Requests Notifications SHOULD be generated for the conference state when a new participant joins (i.e. gets "connected" to) or a participant leaves (i.e. gets "disconnected" from) the conference. Subject to a local focus policy, additional changes in participants' status, changes in their media types, and other optional information MAY be reported by the focus. Changes in sidebar rosters SHOULD be reported by the focus to their participants and MAY be reported to others, subject to local policy. Changes in conference identifiers and service URIs SHOULD be reported by the focus to the Conference package subscribers. Changes in other conference state information MAY be reported by the focus to the Conference package subscribers. 3.7 Subscriber Processing of NOTIFY Requests The SIP Events framework expects packages to specify how a subscriber processes NOTIFY requests in any package specific ways, and in particular, how it uses the NOTIFY requests to construct a coherent view of the state of the subscribed resource. Typically, the NOTIFY for the conference package will only contain information about those users whose state in the conference has changed. To construct a coherent view of the total state of all users, a subscriber to the conference package will need to combine NOTIFYs received over time. Notifications within this package can convey partial information; that is, they can indicate information about a subset of the state associated with the subscription. This means that an explicit algorithm needs to be defined in order to construct coherent and consistent state. The details of this mechanism are specific to the Rosenberg, et al. Expires August 24, 2005 [Page 7] Internet-Draft Conference Package February 2005 particular document type. See Section 4.6 for information on constructing coherent information from an application/conference-info+xml document. 3.8 Handling of Forked Requests By their nature, the conferences supported by this package are centralized. Therefore, SUBSCRIBE requests for a conference should not generally fork. Users of this package MUST NOT install more than a single subscription as a result of a single SUBSCRIBE request. 3.9 Rate of Notifications For reasons of congestion control, it is important that the rate of notifications not become excessive. As a result, it is RECOMMENDED that the server doesn't generate notifications for a single subscriber at a rate faster than once every 5 seconds. 3.10 State Agents Conference state is ideally maintained in the element in which the conference resides. Therefore, the elements that maintain the conference are the ones best suited to handle subscriptions to it. Therefore, the usage of state agents is NOT RECOMMENDED for this package. 4. Conference Document 4.1 Format Conference information is an XML document that MUST be well-formed and valid. It MUST be based on Extensible Markup Language (XML) 1.0 and MUST be encoded using UTF-8 [13]. 4.2 Namespace This specification makes use of XML namespaces for identifying conference information documents and document fragments. The namespace URI for elements defined by this specification is a URN [2], using the namespace identifier 'ietf' defined by [5] and extended by RFC 3688 [14]. This URN is: urn:ietf:params:xml:ns:conference-info 4.3 Versioning The conference information is described by a hierarchal XML structure with the root element . The root element is the Rosenberg, et al. Expires August 24, 2005 [Page 8] Internet-Draft Conference Package February 2005 only element in the schema that carries meaningful version number for all the elements in the document. The whole conference information is associated with this version number. The 'version' attribute MUST be included in the root element. 4.4 State and Partial Notifications All sub-elements in the hierarchal XML structure can be classified in two groups: those that carry relatively small amount of data and those that can potentially carry a lot of data. During partial notifications, the light elements are updated as atomic pieces of data. On the other hand, elements that can carry a substantial amount of data have the general 'state' attribute attached to them. That is in order to support partial notifications for their content. The 'state' attribute indicates whether the reported information about the element is "full", "partial" or the element is "deleted" from the conference state document. The default value of any 'state' attribute is "full". A 'state' attribute of a child element in the document MUST adhere to its parent 'state'. It means that if the parent's 'state' is "full", the state of its children MUST be "full". If the parent's 'state' is "partial", the state of its children MAY be either "partial", "full", or "deleted". 4.5 Element Keys In the context of this specification, the element key is the set of mandatory attributes or sub-elements of the element. The key value MUST be unique for the element among its siblings of the same type. In a partial notification event it must be possible to uniquely identify each sub-element among others of the same type under a common parent element. In order to achieve this property, all sub-elements, with possible multiple appearances under a common parent (which has the attribute 'state') have keys defined to them. Below is the list of the elements with their keys as defined by this specification: o Elements and use as the key 'entity' o Element uses as the key 'entity' and optionally 'call-id' Rosenberg, et al. Expires August 24, 2005 [Page 9] Internet-Draft Conference Package February 2005 o Element uses as the key 'id' o Sub-element of uris-type contained in elements and uses as the key o Elements and of conference-media-type use as the key 'id' o Elements and of count-type use as the key 'role' o Sub-element of conference-type contained in element uses as the key 'entity' o Elements and of uris-type use as the key 4.6 Constructing Coherent State Procedure A conference package subscriber locally maintains a local version number, a local element for each element in the schema, and a table for each element with key(s) in the schema. For first time a NOTIFY with a "full" document is received (as indicated by the value of the 'state' attribute in the element), the conference package subscriber MUST set the local 'version' number to the value of the 'version' attribute from the received and populate local data with the received information. Each time a new NOTIFY is received, the value of the local version number and the value of the 'version' attribute in the new received document are compared. If the value in the document is equal or less than the local version, the document is discarded without processing. Otherwise, if the received NOTIFY contains a "full" or "deleted" state, the conference package subscriber MUST set the local 'version' number to the value of the 'version' attribute from the received and replace the local information with the received document. Receiving "deleted" state means that the conference ceased to exist and the subscriber SHOULD terminate the subscription by sending the SUBSCRIBE with Expires = 0. Otherwise (i.e. if the received NOTIFY contains "partial" state), if the 'version' number in the received document is more than one number higher than the previous local version number, the subscriber MUST generate a refresh request to trigger a full state notification. If the 'version' number in the document is one higher than the local version number, the local version number is increased by one and the document is used to update the local content as described below. For each sub-element of the element in the received document, Rosenberg, et al. Expires August 24, 2005 [Page 10] Internet-Draft Conference Package February 2005 1. If the element contains "full" state, the whole local element content is flushed and repopulated from the document. 2. Otherwise, if the element contains "deleted" state, the whole element MUST be removed from the local content. 3. Otherwise, if the element contains "partial" state: 3.1 For elements with keys, the subscriber compares the keys received in the update with the keys in the local tables. 3.1.1 If a key does not exist in the local table, a row is added, and its content is set to the element information from the update. 3.1.2 Otherwise, if a key of the same value does exist, for each sub-element in the row the algorithm is applied from step 3.2. 3.2 For each atomic element received in the schema, the element is replaced with the new information as a whole. Also, for each non-atomic element received in the schema with either no 'state' attribute included or the state attribute is set to "full", the element is replaced with the new information as a whole. 3.3 For each non-atomic element with the state attribute set to "partial", the algorithm is applied recursively starting from step 3.1. 5. Conference Data A conference information document begins with the root element tag of conference-type. Sections below describe the complex types composing the hierarchal conference-type. The full XML schema is defined in Section 6. 5.1 conference-type This type defines the following attributes: entity: This attribute contains the conference URI that identifies the conference being described in the document. state: This attribute indicates whether the document contains the whole conference information ("full"), only the information that has changed since the previous document ("partial"), or the conference ceased to exist ("deleted"). For more details see Section 4. Rosenberg, et al. Expires August 24, 2005 [Page 11] Internet-Draft Conference Package February 2005 version: This attribute allows the recipient of conference information documents to properly order them and it MUST be included when used in the root element. Version number is a 32 bit monotonically increasing integer scoped within a subscription. A server MUST increment the version number by one for each new partial notification being sent to a subscriber. The conference-type defines an extendable sequence of child elements. A "full" conference document MUST at least include the following sub-elements: , , and . The child elements are described in details below: 5.1.1 conference-description of conference-description-type This element contains conference information that is derived from system conference policies, is set before the conference activation, and is rarely changed during the conference lifetime. 5.1.2 host-info of host-type This element contains information about the entity that hosts the conference. This information is set before the conference activation, and is rarely changed during the conference lifetime, unless the whole conference is moved to be hosted by another entity. 5.1.3 conference-state of conference-state-type This element contains the dynamic information about the current state of the conference. 5.1.4 users of users-type This element can contain an unbounded number of sub-elements of user-type each containing the information about a participant in the conference. 5.1.5 sidebars-by-ref of uris-type This element contains sub-elements of uri-type which provide pointers to sidebar information through sidebar URIs. The recipient of the information can then subscribe to sidebar information independently from the main conference package subscription. 5.1.6 sidebar-by-val of conference-type This element provides sidebar information as a part of the main Rosenberg, et al. Expires August 24, 2005 [Page 12] Internet-Draft Conference Package February 2005 conference package information. 5.2 conference-description-type This type defines the 'state' attribute which can contain the values "full", "partial", or "deleted". This type defines an extendable sequence of the following child elements: 5.2.1 display-text of string type This element contains text description of the conference. 5.2.2 subject of string type This element contains the subject of the conference. 5.2.3 free-text of string type This element contains free form text about the conference. 5.2.4 keywords of keywords-type This element contains a list of words that can be used by automatic search engines to better classify the conference. 5.2.5 conf-uris of uris-type This element contains a set of sub-elements - each containing the information about an additional conference URI that this conference can be accessed by. The value of the URI is included in the sub-element and its description MAY be included in the sub-element. The purpose of the URI SHOULD be included in the sub-element. The currently defined values to be used with the are: participation: Indicates that dialing into this URI will bring the party into the conference streaming: Indicates that "listening" to this URI will provide the conference live content Future extensions to this schema may define new values and register them with IANA under the registry established by this specification. Examples of such URIs include sip: / sips: [7], h323: [17], and tel: Rosenberg, et al. Expires August 24, 2005 [Page 13] Internet-Draft Conference Package February 2005 [16] URIs. 5.2.6 service-uris of uris-type This element contains a set of sub-elements - each containing the URI to be used in order to access different services available for the particular conference. The value of the URI is included in the sub-element and its description MAY be included in the sub-element. The purpose of the URI SHOULD be included in the sub-element. The currently defined values to be used with the are: web-page: Indicates the web page containing the additional information about the conference recording: Indicates the link at which the recorded conference context can be retrieved event: Indicates the URI to which the subscription to the conference event package needs to be performed Future extensions to this schema may define new values and register them with IANA under the registry established by this specification. 5.2.7 maximum-user-count of user-count-type This element, if used, specifies the maximum number of users permitted in the conference and SHOULD include the counter for all participants in the conference in total by populating the attribute 'role' with value "any". Counters for users with specific roles MAY be additionally provided. 5.2.8 available-media of conference-media-type This element contains information about the media streams with their types available to the participants in the conference. The entries in the container are of conference-medium-type and are indexed by attribute 'id'. 5.3 host-type This type defines the 'state' attribute which can contain the values "full", "partial", or "deleted". This type defines an extendable sequence of the following child elements: Rosenberg, et al. Expires August 24, 2005 [Page 14] Internet-Draft Conference Package February 2005 5.3.1 display-text of string type This element contains display text information about the entity hosting the conference. 5.3.2 web-page of anyURI type This element contains a web page URI about the user hosting the conference. 5.3.3 uris of uris-type The sub-element contains additional URIs pointing to the conference host. 5.4 conference-state-type This type defines the 'state' attribute which can contain the values "full", "partial", or "deleted". This type defines an extendable sequence of the following child elements. 5.4.1 user-count of user-count-type This element is used to specify the current number of users in the conference. The number SHOULD be provided for all participants in total by populating the sub-element with value "any". Additionally counters for users with certain roles in the conference MAY be separately provided. 5.4.2 active of Boolean type This element says whether the conference is currently active or not. A conference is active if dialing into one of the results in successful establishment of a call signaling session between the dialed user and the conference focus. 5.4.3 locked of Boolean type This element contains information about whether the conference is currently locked. In this context, "locked" means that the conference roster can not be added to (although participants may leave or be removed from the conference). 5.4.4 active-media of conference-media-type This element contains information about the media streams being Rosenberg, et al. Expires August 24, 2005 [Page 15] Internet-Draft Conference Package February 2005 currently active in the conference, which is a subset of those listed in the container. The entries in the container are of conference-medium-type and are indexed by attribute 'id'. Note, that correlation between media streams in both containers is achieved by matching the values of