| | |-- endpoint
| | |-- media
| |-- user
| |-- endpoint
| |-- media
|
|-- sidebars-by-ref
| |-- entry
| |-- entry
|
|-- sidebars-by-val
|-- entry
| |-- users
| |-- user
| |-- user
|-- entry
|-- users
|-- user
|-- user
|-- user
In most cases, this document does not mandate how the information,
presented through the conference document to the subscribers, is
obtained by the focus. In many cases, the information can be
dynamically learned from the call signaling and can also be manually
populated by an administrator - all subject to local policies. This
document specifies what the XML elements mean in order to allow the
subscribers to appropriately interpret it. Some portions of the
information are intended for processing by automata; others are for
human consumption only. For example, the <display-text> sub-elements
of elements <conf-uris>, <service-uris>, <available-media>,
<host-info>, <endpoint>, and <media> are intended for display to
human subscribers only.
Although in multiple places this document states that specific
information "SHOULD" be communicated to the subscribers, note that
particular conference package subscribers (e.g., representing a
moderator, an administrator, or a cascaded focus) rely on accuracy of
this information for their proper operation. Therefore, a
conferencing server MUST ensure that all critical changes (stated
as "SHOULD") are communicated to these specific subscribers;
otherwise, these changes MUST be communicated to all subscribers to
the conference information.
Following sections describe the XML schema in more detail.
5.2. <conference-info>
A conference information document begins with the root element tag
<conference-info> of conference-type.
The following attributes are defined for <conference-info>:
entity: This attribute contains the conference URI that identifies
the conference being described in the document. This is the SIP
URI that an interested entity needs to SUBSCRIBE to in order to
get the conference package information. Note that this URI can be
listed as one of the URIs to be used in order to access the
conference by SIP means and in accordance with Section 5.3.1
below.
state: This attribute indicates whether the document contains the
whole conference information ("full") or only the information that
has changed since the previous document ("partial"), or whether
the conference ceased to exist ("deleted"). For more detail, see
Section 4.
version: This attribute allows the recipient of conference
information documents to properly order the received
notifications, and it MUST be used with the root <conference-info>
element. Version number is a 32-bit monotonically increasing
integer scoped within a subscription. A server MUST increment the
version number for each notification (full, partial, and deleted)
being sent to a subscriber and reporting a change in the
conference document state. For each partial notification, the
version number MUST be increased by one. Note that a partial
notification and a subsequent full notification over the same
dialog MAY contain the same version number if no change in the
conference state occurred in between.
The <conference-info> element is comprised of <conference-
description>, <host-info>, <conference-state>, <users>,
<sidebars-by-ref> and <sidebars-by-val> child elements. A "full"
conference document MUST at least include the
<conference-description> and <users> child elements.
Following sections describe these elements in detail. The full XML
schema is provided in Section 6.
5.3. <conference-description>
The <conference-description> element describes the conference as a
whole.
The child elements <display-text>, <subject>, <free-text>, and
<keywords> are used to describe the conference content:
<display-text>: Contains descriptive text suitable for human
consumption, for example, listing in a directory
<subject>: Contains the subject of the conference
<free-text>: Contains an additional longer description of the
conference
<keywords>: Contains a list of space-separated string tokens that
can be used by search engines to better classify the conference
Additional child elements <conf-uris> and <service-uris> are used to
describe the conference-related URIs; <maximum-user-count> and
<available-media> are used to describe the overall characteristics.
This information is typically derived from the system conference
policies, is set before the conference activation, and is rarely
changed during the conference lifetime.
The following sections describe the remaining elements in more
detail. Other sub-elements can extend <conference-description> in
the future.
5.3.1. <conf-uris>
This element contains a sequence of <entry> child elements - each
containing the URI to be used in order to access the conference by
different signaling means. The value of the URI MUST be unique in
the conference context and is included in the <uri> sub-element.
Each <entry> MAY contain additional information useful to the
participant when accessing the conference.
An <entry> element MAY contain the <display-text> sub-element that
provides a textual description meant for human consumption.
Each <entry> element SHOULD contain a <purpose> sub-element that
describes what happens when accessing the URI. The currently defined
<purpose> values to be used with the <conf-uris> are the following:
participation: Accessing a URI with this <purpose> will bring the
party into the conference.
streaming: Accessing a URI with this <purpose> will commence
streaming the conference, but not allow active participation.
Examples of suitable URI schemes include sip: and sips: [8], xmpp:
[22], h323: [20], and tel: [19] URIs. The rtsp [18] URI is suitable
for streaming.
Future extensions to this schema may define new values and register
them with IANA under the registry established by this specification.
5.3.2. <service-uris>
This element describes auxiliary services available for the
conference. Like <conference-uris>, this element contains a set of
<entry> child elements - each containing the URI to be used in order
to access different services available for the particular conference.
The value of the URI MUST be unique in the conference context and is
included in the <uri> sub-element.
An <entry> element MAY contain the <display-text> sub-element that
provides a textual description meant for user consumption.
Each <entry> element SHOULD contain a <purpose> sub-element. The
currently defined <purpose> values to be used with the <service-uris>
are the following:
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 at which a subscription to the conference
event package may be requested. This would typically be the
conference URI of the main conference.
Future extensions to this schema may define new values and register
them with IANA under the registry established by this specification.
5.3.3. <maximum-user-count>
The value of this element provides a hint to the recipient of the
conference document about the number of users that can be invited to
the conference. Typically, this value represents the overall number
of users allowed to join the conference by different means as
published through the conference document in <conf-uris>. Note that
this value is set by an administrator and can reflect any local
policies combination such as network consumption, CPU processing
power, and licensing rules.
5.3.4. <available-media>
This element contains a sequence of <entry> child elements of
conference-medium-type, each being indexed by the attribute ’label’.
The ’label’ attribute is the media stream identifier assigned by the
conferencing server: its value will be unique in the
<conference-info> context. The value of this attribute will
typically correspond to the Session Description Protocol (SDP)
"label" media attribute defined in [17].
Each <entry> describes a single media stream available to the
participants in the conference and contains the following
information:
<display-text>: This element contains the display text for the media
stream.
<type>: This element contains the media type of the media stream.
The value of this element MUST be one of the values registered for
"media" of SDP [3] and its later revision(s), for example,
"audio", "video", "text", and "message".
<status>: This element indicates the available status of the media
stream available to the conference participants. For example,
this would be the status of the media stream, which would be
offered by the focus, in a ’dial-out’ scenario. Using normal SIP
offer/answer mechanisms (being defined in RFC 3264 [9]) in both
dial-in and dial-out scenarios, a participant can of course
establish only a subset of the available stream (i.e., request or
accept the stream in one direction only, if both directions are
available). The valid values are "sendrecv", "sendonly",
"recvonly", or "inactive" as defined in SDP [3] and its later
revision(s). (Note that the value specifies the direction from
the participants’ point of view.)
5.4. <host-info>
This element contains information about the entity hosting the
conference. This information is set before the conference
activation, and it is rarely changed during the conference lifetime,
unless the whole conference is moved to be hosted by another entity.
The host information is comprised of the following elements:
5.4.1. <display-text>
This element contains display text describing the entity hosting the
conference.
5.4.2. <web-page>
This element contains HTTP: or HTTPS: URI of a web page describing
either the conference service or the user hosting the conference.
5.4.3. <uris>
This element contains a set of <entry> child elements, each
containing the URI value and optionally its description.
5.5. <conference-state>
By including this element in the conference document, the server can
inform the subscribers about the changes in the overall conference
information. The <conference-state> child elements are described
below.
5.5.1. <user-count>
The value of this element tells the recipient of the conference
document the overall number of users participating in the conference
at a certain moment. Typically, this value represents the overall
number of users who joined the conference by different means as
published through the conference document in <conf-uris>. Note that
this number does not necessarily need to match and MAY exceed the
number of the entries in the <users> container. For example, in a
lecturing scenario, large conference notifications may not include
every participant in the <users> element, but instead report only the
panelists or the speakers.
5.5.2. <active>
This Boolean element indicates whether the conference is currently
active. A conference is active if calling one of the <conf-uris> by
an authorized client results in successful establishment of a
signaling session between the client and the focus and a successful
joining of the conference.
5.5.3. <locked>
This Boolean element says whether the conference is currently locked.
In this context, "locked" means that the conference roster cannot be
added to (although participants may leave or be removed from the
conference).
5.6. <users> and Its <user> Sub-elements
The <users> element is a container of <user> child elements, each
describing a single participant in the conference.
The following attributes are defined for <user> element:
entity: This attribute contains the URI for the user in the
conference. This is a logical identifier, which corresponds to
the call signaling authenticated identity of the participant. The
’entity’ value MUST be unique among all participants in the
conference. If, for some participants, the focus decides not to
reveal this information (e.g., due to local policies or security
reasons), the host portion of the user URI MUST use the .invalid
top level domain (TLD) according to definitions of RFC 2606 [5].
The focus also MUST construct the user portion of the URI so that
the URI is unique among all participants of the same domain. For
example, the convention
"AnonymousX" <sip:anonymousX@anonymous.invalid>
SHOULD be used for a participant requesting privacy in accordance
with the guidelines for generating anonymous URIs of RFC 3323 [11].
Note that in a different case, such as when used in conjunction with
Enhancements for Authenticated Identity Management in SIP [25], the
following convention can be used:
"AnonymousX" <sip:anonymousX@example.com>
state: This attribute indicates whether the document contains the
whole user information ("full") or only the information that has
changed since the previous document ("partial"), or whether the
user was removed from the conference ("deleted").
The following child elements are defined for <user> element:
5.6.1. <display-text>
This element is used to display the user-friendly name in the
conference.
5.6.2. <associated-aors>
This element contains additional (to the ’entity’) URIs being
associated with the <user>. Typically, this information will be
manually provided by an administrator showing the logical association
between signaling entities otherwise independent. For example, if
the ’entity’ of a <user> contains a Globally Routable User URI (GRUU)
[24] or tel: URI RFC 3966 [19], it would be useful to populate this
field with the Address of Record (AOR) of the person who uses these
devices, each represented as an independent <user>.
5.6.3. <roles>
This element MAY contain a set of human-readable strings describing
the roles of the user in the conference. Note that this information
is applicable for human consumption only. This specification does
not define the set of possible conferencing roles or the semantics
associated with each. It is expected that future conferencing
specifications will define these and the corresponding schema
extensions, as appropriate.
5.6.4. <languages>
This element contains a list of tokens, separated by spaces, each
containing a language understood by the user. This information can
be automatically learned via call signaling or be manually set per
participant.
5.6.5. <cascaded-focus>
This element contains a conference URI (different from the main
conference URI) for users that are connected to the main conference
as a result of focus cascading. In accordance with the SIP
Conferencing Framework [16], this package allows for representation
of peer-to-peer (i.e., "flat") focus cascading only. The actual
cascading graph cannot be deduced from the information provided in
the package alone. Advanced applications can construct the graph by
subscribing to both this package and the Dialog Package [23] of each
cascaded focus and correlating the relevant information.
5.6.6. <endpoint>
By including one or more <endpoint> elements under a parent <user>
element, the server can provide the desired level of detail
(including the state, media streams, and access information) about
the user’s devices and signaling sessions taking part in the
conference.
In a conferencing system where authentication is performed per
endpoint (rather than per user), the focus can be unaware of the
logical association of multiple endpoints under a common user. In
this case, each endpoint will appear as a separate <user> with its
own <endpoint> sub-element(s) in the conference document.
In a different case, the focus may choose to shield the information
about the participant’s multiple endpoints and signaling sessions
from other subscribers altogether (e.g., due to privacy policies).
To do so, the focus MAY aggregate the multiple signaling sessions’
information under a single <endpoint> element. Note that in this
case, the detailed call signaling information (represented by
<call-info> sub-element) will not be included.
5.7. <endpoint>
This section describes the <endpoint> element in more detail.
The following attributes are defined for the <endpoint> element:
entity: The server MUST generate the ’entity’ key for each
<endpoint> element included under the parent <user>, such that its
value is unique in the user context. In SIP terms, this can be
the Contact URI, GRUU, etc.
state: This attribute indicates whether the element contains the
whole endpoint information ("full") or only the information that
has changed since the previous document ("partial"), or whether
the endpoint has been removed from the conference ("deleted").
The following child elements are defined for the <endpoint> element:
5.7.1. <display-text>
This element contains the display text for the endpoint.
5.7.2. <referred>
This element contains information about the user whose action
resulted in this endpoint being brought into the conference (e.g.,
the SIP user identified by this URI sent a REFER to the focus). It
MAY contain the following sub-elements:
when: This element of the XML dateTime type contains the date and
time that the endpoint was referred to the conference and SHOULD
be expressed in Coordinated Universal Time (UTC) format. For
example,
<when>2005-03-04T20:00:00Z</when>
reason: This element contains the reason the endpoint was referred
to the conference. Including the information in the format
defined by RFC 3326 [12] is RECOMMENDED. For example,
<reason>Reason: SIP;text="Ad-hoc Invitation"</reason>
by: This element contains the URI of the entity that caused the
endpoint to be referred to the conference. In the case of SIP, it
will be populated from the Referred-By header defined in RFC 3892
[15].
5.7.3. <status>
This element contains the status of the endpoint and can assume the
following values:
connected: The endpoint is a participant in the conference.
Depending on the media policies, he/she can send and receive media
to and from other participants.
disconnected: The endpoint is not a participant in the conference,
and no active dialog exists between the endpoint and the focus.
on-hold: Active signaling dialog exists between an endpoint and a
focus, but endpoint is "on-hold" for this conference, i.e., he/she
is neither "hearing" the conference mix nor is his/her media being
mixed in the conference. As an example, the endpoint has asked to
join the conference using SIP, but his/her participation is
pending based on moderator approval. In the meantime, he/she is
hearing music-on-hold or some other kind of related content.
muted-via-focus: Active signaling dialog exists between an endpoint
and a focus and the endpoint can "listen" to the conference, but
the endpoint’s media is not being mixed into the conference. Note
that sometimes a subset of endpoint media streams can be muted by
focus (such as poor-quality video) while others (such as voice or
IM) can still be active. In this case, it is RECOMMENDED that the
"aggregated" endpoint connectivity <status> reflects the status of
the most active media.
pending: Endpoint is not yet in the session, but it is anticipated
that he/she will join in the near future.
alerting: A Public Switched Telephone Network (PSTN) ALERTING or SIP
180 Ringing was returned for the outbound call; endpoint is being
alerted.
dialing-in: Endpoint is dialing into the conference, not yet in the
roster (probably being authenticated).
dialing-out: Focus has dialed out to connect the endpoint to the
conference, but the endpoint is not yet in the roster (probably
being authenticated).
disconnecting: Focus is in the process of disconnecting the endpoint
(e.g., in SIP a DISCONNECT or BYE was sent to the endpoint).
Note that the defined transient statuses (e.g., disconnecting,
alerting, etc.) could generate a lot of traffic. Therefore,
implementations MAY choose to generate notifications on these
statuses to certain participants only or not generate them at all,
subject to local policy.
5.7.4. <joining-method>
This element contains the method by which the endpoint joined the
conference and can assume the following values:
dialed-in: The endpoint dialed into the conference (e.g., in a SIP
sent INVITE to the focus), which resulted in successful dialog
establishment.
dialed-out: The focus has brought the endpoint into the conference
(e.g., in SIP, the focus sent a successful INVITE to the
endpoint).
focus-owner: The endpoint is the focus for this conference. This
status is used only when a participant’s UA acts as a conference
focus.
5.7.5. <joining-info>
This element contains information about how the endpoint joined and
MAY contain the following sub-elements:
when: This element of the XML dateTime type contains the date and
time that the endpoint joined the conference and SHOULD be
expressed in Coordinated Universal Time (UTC).
reason: This element contains the reason the endpoint joined the
conference. Including the information in the format defined by
RFC 3326 [12] is RECOMMENDED. For example,
<reason>Reason: SIP;text="Ad-hoc Invitation"</reason>
by: This element contains the URI of the entity that caused the
endpoint to join the conference.
5.7.6. <disconnection-method>
This element contains the method by which the endpoint departed the
conference and can assume the following values:
departed: In SIP, the endpoint sent a BYE, thus leaving the
conference.
booted: In SIP, the endpoint was sent a BYE by the focus, ejecting
him/her out of the conference. Alternatively, the endpoint tried
to dial into the conference but was rejected by the focus due to
local policy.
failed: In SIP, the server tried to bring the endpoint into the
conference, but its attempt to contact the specific endpoint
resulted in a non-200 class final response. Alternatively, the
endpoint tried to dial into the conference without success due to
technical reasons.
busy: In SIP, the server tried to bring the endpoint into the
conference, but its attempt to contact the specific endpoint
resulted in a 486 "Busy Here" final response. Alternatively, the
endpoint tried to dial into the conference but the focus responded
with 486 response.
5.7.7. <disconnection-info>
This element contains information about the endpoint’s departure from
the conference and MAY contain the following sub-elements:
when: This element of the XML dateTime type contains the date and
time that the endpoint departed the conference and SHOULD be
expressed in Coordinated Universal Time (UTC).
reason: This element contains the reason the endpoint departed the