Request for Comments: 4575 Cisco Systems
Category: Standards Track H. Schulzrinne
Columbia University
O. Levin, Ed.
Microsoft Corporation
August 2006
A Session Initiation Protocol (SIP)
Event Package for Conference State
Status of This Memo
This document specifies an Internet standards track protocol for the
Internet community, and requests discussion and suggestions for
improvements. Please refer to the current edition of the "Internet
Official Protocol Standards" (STD 1) for the standardization state
and status of this protocol. Distribution of this memo is unlimited.
Copyright Notice
Copyright (C) The Internet Society (2006).
Abstract
This document defines a conference event package for tightly coupled
conferences using the Session Initiation Protocol (SIP) events
framework, along with a data format used in notifications for this
package. The conference package allows users to subscribe to a
conference Uniform Resource Identifier (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 ....................................................4
2. Terminology .....................................................4
3. Conference Event Package ........................................4
3.1. Event Package Name .........................................5
3.2. Filtering ..................................................5
3.3. Subscription Duration ......................................5
3.4. NOTIFY Bodies ..............................................5
3.5. Notifier Processing of SUBSCRIBE Requests ..................6
3.6. Notifier Generation of NOTIFY Requests .....................6
3.7. Subscriber Processing of NOTIFY Requests ...................6
3.8. Handling of Forked Requests ................................7
3.9. Rate of Notifications ......................................7
3.10. State Agents ..............................................7
4. Conference Document .............................................7
4.1. Format .....................................................7
4.2. Namespace ..................................................7
4.3. Versioning .................................................8
4.4. Partial Notifications Mechanism ............................8
4.5. Element Keys ...............................................9
4.6. Constructing Coherent State Procedure ......................9
5. Conference Data ................................................11
5.1. Overview ..................................................11
5.2. <conference-info> .........................................13
5.3. <conference-description> ..................................14
5.3.1. <conf-uris> ........................................14
5.3.2. <service-uris> .....................................15
5.3.3. <maximum-user-count> ...............................16
5.3.4. <available-media> ..................................16
5.4. <host-info> ...............................................17
5.4.1. <display-text> .....................................17
5.4.2. <web-page> .........................................17
5.4.3. <uris> .............................................17
5.5. <conference-state> ........................................17
5.5.1. <user-count> .......................................17
5.5.2. <active> ...........................................18
5.5.3. <locked> ...........................................18
5.6. <users> and Its <user> Sub-elements .......................18
5.6.1. <display-text> .....................................19
5.6.2. <associated-aors> ..................................19
5.6.3. <roles> ............................................19
5.6.4. <languages> ........................................19
5.6.5. <cascaded-focus> ...................................19
5.6.6. <endpoint> .........................................20
5.7. <endpoint> ................................................20
5.7.1. <display-text> .....................................20
5.7.2. <referred> .........................................21
5.7.3. <status> ...........................................21
5.7.4. <joining-method> ...................................22
5.7.5. <joining-info> .....................................23
5.7.6. <disconnection-method> .............................23
5.7.7. <disconnection-info> ...............................23
5.7.8. <media> ............................................24
5.7.9. <call-info> ........................................24
5.8. <media> ...................................................24
5.8.1. <display-text> .....................................25
5.8.2. <type> .............................................25
5.8.3. <label> ............................................25
5.8.4. <src-id> ...........................................25
5.8.5. <status> ...........................................26
5.9. Sidebars ..................................................26
5.9.1. <sidebars-by-ref> ..................................26
5.9.2. <sidebar-by-val> ...................................26
6. XML Schema .....................................................26
7. Examples .......................................................35
7.1. Basic Example .............................................35
7.2. Rich Example ..............................................36
8. Security Considerations ........................................40
8.1. Connection Security .......................................40
8.2. Authorization Considerations ..............................41
9. IANA Considerations ............................................41
9.1. conference Event Package Registration .....................41
9.2. application/conference-info+xml MIME Registration .........42
9.3. URN Sub-Namespace Registration for ........................43
9.4. XML Schema Registration ...................................43
9.5. URI Purposes Sub-registry Establishment ...................44
10. Acknowledgements ..............................................45
11. References ....................................................45
11.1. Normative References .....................................45
11.2. Informative References ...................................46
1. Introduction
The Session Initiation Protocol (SIP) events framework [10] 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 a SIP event
package for tightly coupled conferences. This package can be used by
the conference notification service as outlined in the SIP
conferencing framework [16]. 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.
This document uses the conferencing terminology defined in
Conferencing Framework [16]. In addition, the "roster" term is used
to collectively refer to participants in a conference or a sub-
conference.
3. Conference Event Package
The conference event package allows a user to subscribe to the
information relating to a conference. In SIP, conferences are
represented by URIs. These URIs identify a SIP user agent (UA),
called a focus, that is responsible for ensuring that all users in
the conference can communicate with each other, as described in
Conferencing Framework [16]. 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
<cascaded-focus> element as specified by this package.
This section provides the details for defining a SIP-specific event
notification package, as specified by RFC 3265 [10].
3.1. Event Package Name
The name of this event package is "conference". This package name is
carried in the Event and Allow-Events header, as defined in RFC 3265
[10].
3.2. Filtering
Filters, which can be applied to conference subscriptions, are a
desirable feature and can be considered as a subject of future
standardization activities. This document does not define the
filters for the conference package to be included in the SUBSCRIBE
body.
A SUBSCRIBE for a conference package, being sent without a body,
implies the default subscription filtering policy. The default
policy is as follows:
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 [10].
3.4. NOTIFY Bodies
According to RFC 3265 [10], 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 that describes the state of a
conference. All subscribers and notifiers MUST support the
"application/conference-info+xml" data format described in Sections 9
and 5. By default, i.e., if no Accept header is specified to a
SUBSCRIBE request, the NOTIFY will contain a body in the
"application/conference-info+xml" data format. If the Accept header
field is present, it MUST include "application/conference-info+xml"
and MAY include any other types.
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, 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
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. If forking happens in the network, subscribers
to this package MUST NOT establish more than a single SIP dialog as a
result of a single SUBSCRIBE request. In the foci cascading case,
detailed conference information can be retrieved by establishing an
individual SUBSCRIBE dialog with each participating focus.
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 does not 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, a conference focus is the best-suited
element to handle subscriptions to it. Cascaded foci MAY implement
state agents (as defined in RFC 3265 [10]) 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 [14].
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 Uniform
Resource Namespace (URN) [2], using the namespace identifier ’ietf’
defined by [6] and extended by RFC 3688 [21]. This URN is as
follows:
urn:ietf:params:xml:ns:conference-info
4.3. Versioning
The conference information is described by a hierarchical XML
structure with the root element <conference-info>. The root element
is the only element in the schema that carries a 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
<conference-info> element.
4.4. Partial Notifications Mechanism
This specification defines a basic partial notifications mechanism by
using a ’state’ attribute as described below. This mechanism MUST be
supported by all subscribing clients. Additional general partial
notifications mechanisms can be defined and applied to this package
in the future.
All sub-elements in the <conference-info> hierarchical XML structure
can be classified in two groups: permissible for partial
notifications or not. Elements that carry a substantial amount of
data that is subject to frequent changes are permissible for partial
notifications and have a ’state’ attribute attached to them. All
future extensions to this schema MUST define which extension elements
can also use this mechanism. All other elements can be updated as
atomic pieces of data only.
Below is the complete list of elements permissible to use the partial
notifications mechanism defined in this specification. (Note that
future partial notifications mechanisms can potentially be applicable
to additional elements.)
o Element <conference-info>
o Element <users>
o Element <user>
o Element <endpoint>
o Element <sidebars-by-val>
o Element <sidebars-by-ref>
The ’state’ attribute value indicates whether the reported
information about the element is "full" or "partial", or whether the
element has been "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 be
consistent with its parent ’state’. This 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". A parent element with
"deleted" ’state’ SHOULD NOT contain child elements. Any information
provided for child elements of a "deleted" parent MUST be ignored by
the package subscriber.
4.5. Element Keys
The defined XML schema has a property of unique identification among
sub-elements of a common parent, which makes it possible to use the
partial notifications mechanism defined in this document. This
property is achieved by defining a key to each sub-element that can
appear multiple times under the common parent.
In the context of this specification, the element key is the set of
mandatory attributes or sub-elements of an element. The key value
MUST be unique for the element among its siblings of the same type.
In the context of this specification, two keys of type xs:anyURI are
considered to be equal if the UTF-8 representations of the keys
(including all URI parameters that can be included with the URI) are
identical. Consequently, using relative URIs and lexical white space
in these keys is NOT RECOMMENDED.
Below is the list of elements (subject to partial notifications of
their parent elements) with their keys as defined by this
specification:
o Element <user> uses as the key ’entity’
o Element <endpoint> uses as the key ’entity’
o Element <media> uses as the key ’id’
o Element <entry> (child to <sidebars-by-val>) uses as the key
’entity’
o Element <sidebars-by-ref> uses as the key <uri>
4.6. Constructing Coherent State Procedure
This section describes the algorithm for constructing a coherent
conference state by a subscriber to the conference package. Using
software programming abstraction, the subscriber maintains a single
local version number for the whole conference document and a local
element instance for each element in the schema. Also, for each
element with keys (as defined above), the subscriber maintains a
virtual table with a row for each existing key value.
The first time a NOTIFY with a "full" document is received (as
indicated by the value of the ’state’ attribute in the
<conference-info> element), the conference package subscriber MUST
set the local ’version’ number to the value of the ’version’
attribute from the received <conference-info> 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 to 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
<conference-info> and replace the local information with the received
document. Receiving "deleted" state for the <conference-info>
element means that the conference has 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 subscription 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 updated
accordingly and the document is used to update the local content as
described below.
For each sub-element of the <conference-info> element in the received
document,
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. 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. Also, for each element with the state attribute set
to "deleted", the whole element is removed from the local
content.
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
5.1. Overview
The <conference-info> document format is designed to convey
information about the conference and about participation in the
conference. The following non-normative diagram gives an example of
the overall hierarchy used in this format. Conferences contain users
who can be represented by multiple endpoints, each of which can have
multiple media streams. Conferences can also include or reference
"sidebar conferences". When sidebar information is incorporated into
a conference information document in a <sidebars-by-val> element,
each <entry> element represents a sidebar and can include any
sub-elements permitted in the <conference-info> top-level element.
conference-info
|
|-- conference-description
|
|-- host-info
|
|-- conference-state
|
|-- users
| |-- user
| | |-- endpoint
| | | |-- media
| | | |-- media
| | | |-- call-info
| | |