</xs:sequence>
<xs:attribute name="uri" type="xs:anyURI" use="required" />
<xs:attribute name="version" type="xs:unsignedInt"
use="required" />
<xs:attribute name="fullState" type="xs:boolean"
use="required" />
<xs:attribute name="cid" type="xs:string" use="optional" />
<xs:anyAttribute processContents="lax" />
</xs:complexType>
</xs:element>
<xs:element name="resource">
<xs:complexType>
<xs:sequence>
<xs:element ref="name" minOccurs="0"
maxOccurs="unbounded" />
<xs:element ref="instance" minOccurs="0"
maxOccurs="unbounded" />
</xs:sequence>
<xs:attribute name="uri" type="xs:anyURI" use="required" />
<xs:anyAttribute processContents="lax" />
</xs:complexType>
</xs:element>
<xs:element name="instance">
<xs:complexType>
<xs:sequence>
<xs:any minOccurs="0" maxOccurs="unbounded"
processContents="lax" />
</xs:sequence>
<xs:attribute name="id" type="xs:string" use="required" />
<xs:attribute name="state" use="required">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:enumeration value="active" />
<xs:enumeration value="pending" />
<xs:enumeration value="terminated" />
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name="reason" type="xs:string"
use="optional" />
<xs:attribute name="cid" type="xs:string" use="optional" />
<xs:anyAttribute processContents="lax" />
</xs:complexType>
</xs:element>
<xs:element name="name">
<xs:complexType>
<xs:simpleContent>
<xs:extension base="xs:string">
<xs:attribute ref="xml:lang" use="optional"/>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
</xs:element>
</xs:schema>
An example of a document formatted using this schema follows.
<?xml version="1.0"?>
<list xmlns="urn:ietf:params:xml:ns:rlmi"
uri="sip:adam-friends@lists.vancouver.example.com"
version="7" fullState="true">
<name xml:lang="en">Buddy List</name>
<name xml:lang="fr">Liste d’amis</name>
<resource uri="sip:bob@vancouver.example.com">
<name>Bob Smith</name>
<instance id="juwigmtboe" state="active"
cid="12345.aaa@vancouver.example.com"/>
</resource>
<resource uri="sip:dave@vancouver.example.com">
<name>Dave Jones</name>
<instance id="hqzsuxtfyq" state="active"
cid="12345.aab@vancouver.example.com"/>
</resource>
<resource uri="sip:jim@vancouver.example.com">
<name>Jim</name>
<instance id="oflzxqzuvg" state="terminated"
reason="rejected" />
</resource>
<resource uri="sip:ed@vancouver.example.com">
<name>Ed</name>
<instance id="grqhzsppxb" state="pending"/>
</resource>
</list>
5.2. List Attributes
The <list> element present in a list notification MUST contain three
attributes.
The first mandatory <list> attribute is "uri", which contains the uri
that corresponds to the list. Typically, this is the URI to which
the SUBSCRIBE request was sent.
The second mandatory <list> attribute is "version", which contains a
number from 0 to 2^32-1. This version number MUST be 0 for the first
NOTIFY message sent within a subscription, and MUST increase by
exactly one for each subsequent NOTIFY sent within a subscription.
The third mandatory attribute is "fullState". The "fullState"
attribute indicates whether the NOTIFY message contains information
for every resource in the list. If it does, the value of the
attribute is "true" (or "1"); otherwise, it is "false" (or "0"). The
first NOTIFY sent in a subscription MUST contain full state, as must
the first NOTIFY sent after receipt of a SUBSCRIBE request for the
subscription.
Finally, <list> elements MAY contain a "cid" attribute. If present,
the "cid" attribute identifies a section within the multipart/related
body that contains aggregate state information for the resources
contained in the list. The definition of such aggregate information
is outside the scope of this document and will be defined on a per-
package basis, as needed. The cid attribute is the Content-ID for
the corresponding section in the multipart body.
The cid attribute MUST refer only to top-level parts of the
multipart/related document for which the RLMI document in which it
appears is the root. See Section 5.5 for an example.
5.3. Resource Attributes
The resource list contains one <resource> element for each resource
being reported in the notification. These resource elements contain
attributes that identify meta-data associated with each resource.
The "uri" attribute identifies the resource to which the <resource>
element corresponds. Typically, this will be a SIP URI that, if
subscribed to, would return the state of the resource. This
attribute MUST be present.
5.4. Name Attributes
Each list and resource element contains zero or more name elements.
These name elements contain human-readable descriptions or names for
the resource list or resource. The contents of these elements are
somewhat analogous to the "Display Name" present in the SIP name-addr
element.
Name elements optionally contain the standard XML "xml:lang"
attribute. The "xml:lang" attribute, if present, specifies the
language of the human-readable name. If this attribute is present,
it MUST contain a valid language tag. Language tags are defined in
RFC 3066 [6]. The language tag assists applications in determining
which of potentially several name elements should be rendered to the
user.
5.5. Instance Attributes
Each resource element contains zero or more instance elements. These
instance elements are used to represent a single notifier for the
resource. For event packages that allow forking, multiple virtual
subscriptions may exist for a given resource. Multiple virtual
subscriptions are represented as multiple instance elements in the
corresponding resource element. For subscriptions in which forking
does not occur, at most one instance will be present for a given
resource.
The "id" attribute contains an opaque string used to uniquely
identify the instance of the resource. The "id" attribute is unique
only within the context of a resource. Construction of this string
is an implementation decision. Any mechanism for generating this
string is valid, as long as uniqueness within the resource is
assured.
The "state" attribute contains the subscription state for the
identified instance of the resource. This attribute contains one of
the values "active", "pending", or "terminated". The meanings for
these values are as defined for the "Subscription-State" header field
in RFC 3265 [2].
If the "state" attribute indicates "terminated", then a "reason"
attribute MUST also be present. This "reason" attribute has the same
values and meanings as those given for the "reason" parameter on the
"Subscription-State" header field in RFC 3265 [2]. Note that the
"reason" attribute is included for informational purposes; the list
subscriber is not expected to take any automated actions based on the
reason value.
Finally, the "cid" attribute, which MUST be present if the "state"
attribute is "active", identifies the section within the
multipart/related body that contains the actual resource state. This
state is expressed in the content type defined by the event package
for conveying state. The cid attribute is the Content-ID for the
corresponding section in the multipart body.
The cid attribute MUST refer only to top-level parts of the
multipart/related document for which the RLMI document in which it
appears is the root.
For example, consider a multipart/related document containing
three parts; we’ll label these parts A, B, and C. Part A is type
application/rlmi+xml, part B is type multipart/related, and part C
is type application/pidf+xml. Part B is in turn a document
containing three parts: D, E, and F. Part D is of type
application/rlmi+xml, and parts E and F are of type
application/pidf+xml.
+-------------------------------------------+
| Top Level Document: multipart/related |
| |
| +---------------------------------------+ |
| | Part A: application/rlmi+xml | |
| +---------------------------------------+ |
| | Part B: multipart/related | |
| | | |
| | +-----------------------------------+ | |
| | | Part D: application/rlmi+xml | | |
| | +-----------------------------------+ | |
| | | Part E: application/pidf+xml | | |
| | +-----------------------------------+ | |
| | | Part F: application/pidf+xml | | |
| | +-----------------------------------+ | |
| | | |
| +---------------------------------------+ |
| | Part C: application/pidf+xml | |
| +---------------------------------------+ |
| |
+-------------------------------------------+
Any "cid" attributes in document A must refer only to parts B or
C. Referring to parts D, E, or F would be illegal. Similarly,
any "cid" attributes in document D must refer only to parts E or
F. Referring to any other parts would be illegal.
Also note that the subscription durations of any back-end
subscriptions are not propagated into the meta-information state
in any way.
5.6. Constructing Coherent Resource State
The resource list subscriber maintains a table for each resource
list. The table contains a row for each resource in the resource
list. Each row is indexed by the URI for that resource. That URI is
obtained from the "uri" attribute on each <resource> element. The
contents of each row contain the state of that resource as conveyed
in the resource document.
For resources that provide versioning information (which is mandated
by [2] for any formats that allow partial notification), each row
also contains a resource state version number. The version number of
the row is initialized with the version specified in the first
document received, as defined by the corresponding event package.
This value is used when comparing versions of partial notifications
for a resource.
The processing of the resource list notification depends on whether
it contains full or partial state.
5.6.1. Processing Full State Notifications
If a notification contains full state, indicated by the <list>
attribute "fullState" set to "true", the notification is used to
update the table. A check is first made to ensure that the "version"
attribute of the <list> attribute in the received message is greater
than the local version number. If not, the received document is
discarded without any further processing. Otherwise, the contents of
the resource-list table are flushed and repopulated from the contents
of the document. A new row in the table is created for each
"resource" element.
5.6.2. Processing Partial State Notifications
If a notification contains partial state, indicated by the <list>
attribute "fullState" set to "false", a check is made to ensure that
no list notifications have been lost. The value of the local version
number (the "version" attribute of the <list> element) is compared to
the version number of the new document.
o If the value in the new document is exactly one higher than the
local version number, the local version number is increased by
one, and the document is processed as described below.
o If the version in the document is more than one higher than the
local version number, the local version number is set to the value
in the new document, and the document is processed as described
below. The list subscriber SHOULD also generate a refresh request
to trigger a full state notification.
o If the version in the document is less than or equal to the local
version, the document is discarded without any further processing.
For each resource listed in the document, the subscriber checks to
see whether a row exists for that resource. This check is done by
comparing the Resource-URI value with the URI associated with the
row. If the resource doesn’t exist in the table, a row is added, and
its state is set to the information from that "resource" element. If
the resource does exist, its state is updated to be the information
from that "resource" element, as described in the definition of the
event package. If a row is updated or created such that its state is
now "terminated," that entry MAY be removed from the table at any
time.
6. Example
This section gives an example call flow. It is not normative. If a
conflict arises between this call flow and the normative behavior
described in this or any other document, the normative descriptions
are to be followed.
In this particular example, we request a subscription to a nested
presence list. The subscriber’s address-of-record is
"sip:adam@vancouver.example.com", and the name of the nested list
resource that we are subscribing to is called
"sip:adam-buddies@pres.vancouver.example.com". The underlying event
package is "presence", described by [8].
In this example, the RLS has information to service some of the
resources on the list, but must consult other servers to retrieve
information for others. The implementation of the RLS in this
example uses the SIP SUBSCRIBE/NOTIFY mechanism to retrieve such
information.
Terminal pres.vancouver.example.com pres.stockholm.example.org
| | pres.dallas.example.net |
1 |---SUBSCRIBE--->| | |
2 |<-----200-------| | |
3 |<----NOTIFY-----| | |
4 |------200------>| | |
5 | |---SUBSCRIBE--->| |
6 | |<-----200-------| |
7 | |<----NOTIFY-----| |
8 | |------200------>| |
9 | |------------SUBSCRIBE----------->|
10| |<--------------200---------------|
11| |<-------------NOTIFY-------------|
12| |---------------200-------------->|
13|<----NOTIFY-----| | |
14|------200------>| | |
1. We initiate the subscription by sending a SUBSCRIBE message to
our local RLS. (There is no reason that the RLS we contact has
to be in our domain, of course). Note that we must advertise
support for application/rlmi+xml and multipart/related because
we support the eventlist extension, and that we must advertise
application/pidf+xml because we are requesting a subscription to
presence.
Terminal -> Local RLS
SUBSCRIBE sip:adam-buddies@pres.vancouver.example.com SIP/2.0
Via: SIP/2.0/TCP terminal.vancouver.example.com;
branch=z9hG4bKwYb6QREiCL
Max-Forwards: 70
To: <sip:adam-buddies@pres.vancouver.example.com>
From: <sip:adam@vancouver.example.com>;tag=ie4hbb8t
Call-ID: cdB34qLToC@terminal.vancouver.example.com
CSeq: 322723822 SUBSCRIBE
Contact: <sip:terminal.vancouver.example.com>
Event: presence
Expires: 7200
Supported: eventlist
Accept: application/pidf+xml
Accept: application/rlmi+xml
Accept: multipart/related
Accept: multipart/signed
Accept: application/pkcs7-mime
Content-Length: 0
2. The Local RLS completes the SUBSCRIBE transaction. Note that
authentication and authorization would normally take place at
this point in the call flow. Those steps are omitted for
brevity.
Local RLS -> Terminal
SIP/2.0 200 OK
Via: SIP/2.0/TCP terminal.vancouver.example.com;
branch=z9hG4bKwYb6QREiCL
To: <sip:adam-buddies@pres.vancouver.example.com>;tag=zpNctbZq
From: <sip:adam@vancouver.example.com>;tag=ie4hbb8t
Call-ID: cdB34qLToC@terminal.vancouver.example.com
CSeq: 322723822 SUBSCRIBE
Contact: <sip:pres.vancouver.example.com>
Expires: 7200
Require: eventlist
Content-Length: 0
3. As is required by RFC 3265 [2], the RLS sends a NOTIFY
immediately upon accepting the subscription. In this example,
we are assuming that the local RLS is also an authority for
presence information for the users in the
"vancouver.example.com" domain. The NOTIFY contains an RLMI
document describing the entire buddy list (initial notifies
require full state), as well as presence information for the
users about which it already knows. Note that, since the RLS
has not yet retrieved information for some of the entries on the
list, those <resource> elements contain no <instance> elements.
Local RLS -> Terminal
NOTIFY sip:terminal.vancouver.example.com SIP/2.0
Via: SIP/2.0/TCP pres.vancouver.example.com;
branch=z9hG4bKMgRenTETmm
Max-Forwards: 70
From: <sip:adam-buddies@pres.vancouver.example.com>;tag=zpNctbZq
To: <sip:adam@vancouver.example.com>;tag=ie4hbb8t
Call-ID: cdB34qLToC@terminal.vancouver.example.com
CSeq: 997935768 NOTIFY
Contact: <sip:pres.vancouver.example.com>
Event: presence
Subscription-State: active;expires=7200
Require: eventlist
Content-Type: multipart/related;type="application/rlmi+xml";
start="<nXYxAE@pres.vancouver.example.com>";
boundary="50UBfW7LSCVLtggUPe5z"
Content-Length: 1560
--50UBfW7LSCVLtggUPe5z
Content-Transfer-Encoding: binary
Content-ID: <nXYxAE@pres.vancouver.example.com>
Content-Type: application/rlmi+xml;charset="UTF-8"
<?xml version="1.0" encoding="UTF-8"?>
<list xmlns="urn:ietf:params:xml:ns:rlmi"
uri="sip:adam-friends@pres.vancouver.example.com"
version="1" fullState="true">
<name xml:lang="en">Buddy List at COM</name>
<name xml:lang="de">Liste der Freunde an COM</name>
<resource uri="sip:bob@vancouver.example.com"">
<name>Bob Smith</name>
<instance id="juwigmtboe" state="active"
cid="bUZBsM@pres.vancouver.example.com"/>
</resource>
<resource uri="sip:dave@vancouver.example.com">
<name>Dave Jones</name>
<instance id="hqzsuxtfyq" state="active"
cid="ZvSvkz@pres.vancouver.example.com"/>
</resource>
<resource uri="sip:ed@dallas.example.net">
<name>Ed at NET</name>
</resource>
<resource uri="sip:adam-friends@stockholm.example.org">
<name xml:lang="en">My Friends at ORG</name>
<name xml:lang="de">Meine Freunde an ORG</name>
</resource>
</list>
--50UBfW7LSCVLtggUPe5z
Content-Transfer-Encoding: binary
Content-ID: <bUZBsM@pres.vancouver.example.com>
Content-Type: application/pidf+xml;charset="UTF-8"
<?xml version="1.0" encoding="UTF-8"?>
<presence xmlns="urn:ietf:params:xml:ns:pidf"
entity="sip:bob@vancouver.example.com">
<tuple id="sg89ae">
<status>
<basic>open</basic>
</status>
<contact priority="1.0">sip:bob@vancouver.example.com</contact>
</tuple>
</presence>
--50UBfW7LSCVLtggUPe5z
Content-Transfer-Encoding: binary
Content-ID: <ZvSvkz@pres.vancouver.example.com>
Content-Type: application/pidf+xml;charset="UTF-8"
<?xml version="1.0" encoding="UTF-8"?>
<presence xmlns="urn:ietf:params:xml:ns:pidf"
entity="sip:dave@vancouver.example.com">
<tuple id="slie74">
<status>
<basic>closed</basic>
</status>
</tuple>
</presence>
--50UBfW7LSCVLtggUPe5z--
4. The terminal completes the transaction.
Terminal -> Local RLS
SIP/2.0 200 OK
Via: SIP/2.0/TCP pres.vancouver.example.com;
branch=z9hG4bKMgRenTETmm
From: <sip:adam-buddies@pres.vancouver.example.com>;tag=zpNctbZq
To: <sip:adam@vancouver.example.com>;tag=ie4hbb8t
Call-ID: cdB34qLToC@terminal.vancouver.example.com
CSeq: 997935768 NOTIFY
Contact: <sip:terminal.vancouver.example.com>
Content-Length: 0
5. In order to service the subscription, the local RLS subscribes
to the state of the resources. In this step, the RLS attempts
to subscribe to the presence state of the resource
"sip:ed@dallas.example.net". Since the local RLS knows how to
receive notifications for list subscriptions, it includes the
"Supported: eventlist" header field in its request. Although
the linkage between this subscription and the one sent by the
terminal is left up to the application, this message
demonstrates some reasonable behavior by including "Accept"
header fields for all the body types it knows the subscriber
(Terminal) supports. This is safe to do, since the local RLS
will only pass these formats through to the subscriber and does
not need to actually understand them.
Local RLS -> Presence Server in dallas.example.net
SUBSCRIBE sip:ed@dallas.example.net SIP/2.0
Via: SIP/2.0/TCP pres.vancouver.example.com;
branch=z9hG4bKMEyGjdG1LH
Max-Forwards: 70
To: <sip:ed@dallas.example.net>
From: <sip:adam@vancouver.example.com>;tag=aM5icQu9
Call-ID: Ugwz5ARxNw@pres.vancouver.example.com
CSeq: 870936068 SUBSCRIBE
Contact: <sip:pres.vancouver.example.com>
Identity: Tm8sIHRoaXMgaXNuJ3QgYSByZWFsIGNlcnQuIFlvdSBvn
Zpb3VzbHkgaGF2ZSB0aW1lIHRvIGtpbGwuIEkKc3VnZ2V
zdCBodHRwOi8vd3d3LmhvbWVzdGFycnVubmVyLmNvbS8K
Identity-Info: https://vancouver.example.com/cert
Event: presence
Expires: 3600
Supported: eventlist
Accept: application/pidf+xml
Accept: application/rlmi+xml
Accept: multipart/related
Accept: multipart/signed
Accept: application/pkcs7-mime
Content-Length: 0
6. The Presence Server in dallas.example.net completes the
SUBSCRIBE transaction. Note that authentication would normally
take place at this point in the call flow. This step is omitted