[MS-PRES]: Category Subscribe Request

Article
08/17/2021

The following example shows a category subscription request.

SUBSCRIBE sip:bob@contoso.com SIP/2.0
Via: SIP/2.0/TCP 172.24.32.124:54059
Max-Forwards: 70
From: <sip:bob@contoso.com>;tag=26aef0a2a4;epid=84d3db8c23
To: <sip:bob@contoso.com>
Call-ID: 77a9ac0f3beb4a65b1d40cc0978eda56
CSeq: 1 SUBSCRIBE
Contact: <sip:bob@contoso.com;opaque=user:epid:fvceImg6cFWG7W6lvUt_-AAA;gruu>
User-Agent: UCCP/2.0.6362.0 OC/2.0.6362.0 (Microsoft Office Communicator)
Event: presence
Accept: application/msrtc-event-categories+xml, application/rlmi+xml, multipart/related
Supported: ms-benotify
Proxy-Require: ms-benotify
Supported: ms-piggyback-first-notify
Require: adhoclist, categoryList
Supported: eventlist
Proxy-Authorization: ...
Content-Type: application/msrtc-adrl-categorylist+xml
Content-Length: …

<batchSub xmlns="http://schemas.microsoft.com/2006/01/sip/batch-subscribe" uri="sip:bob@contoso.com" name="">
  <action name="subscribe" id="63792024">
    <adhocList>
      <resource uri="sip:alice@contoso.com"/>
      <resource uri="sip:john@contoso.com">
        <context>  
     <subscriptionContext xmlns="http://schemas.microsoft.com/2008/09/sip/SubscriptionContext" majorVersion="1" minorVersion="0">
            <watcher>
              <contactList />
            </watcher>
     </subscriptionContext>
   </context>
      </resource>
    </adhocList>
    <categoryList xmlns="http://schemas.microsoft.com/2006/09/sip/categorylist">
      <category name="calendarData"/>
      <category name="contactCard"/>
      <category name="note"/>
      <category name="services"/>
      <category name="state"/>
    </categoryList>
  </action>
</batchSub>

Category subscription uses the SUBSCRIBE request and response as defined in [RFC3265] section 3.1 and section 3.2, with the presence event package. The value of the Event header field MUST be "presence".

The Supported, Require, and Proxy-Require header fields indicate support for a variety of presence extensions that are described in [MS-SIP] section 3.2.

The Accept header field indicates that the SIP protocol client is capable of receiving, in response to SUBSCRIBE, a multipart MIME document that contains a list of users ("application/rlmi+xml") and their category data ("application/msrtc-event-categories+xml"). An Accept header field MUST include "application/msrtc-event-categories+xml, application/rlmi+xml, multipart/related".

The Require header field MUST be set to "adhoclist, categoryList".

The Supported header field MUST be set to "eventlist". This indicates support specifically for the enhanced presence batched SUBSCRIBE mechanism.

The Content-Type header field value of "application/msrtc-adrl-categorylist+xml" indicates that this SUBSCRIBE request carries an XML body that contains the list of contacts of interest, along with categories. Content-Type MUST be set to "application/msrtc-adrl-categorylist+xml".

The To-URI and the From-URI MUST contain the SIP URI of the subscriber. In the previous example, bob@contoso.com is the subscriber.

The SIP protocol client MUST add a valid Contact header field that can be used as a remote target URI of the SIP dialog route set as specified in [RFC3261] section 12.

Elements and attributes used in category SUBSCRIBE requests are defined as follows. For the full XML schema, see section 6.

The XML elements of a category SUBSCRIBE request document MUST conform to the schema defined in section 6.8.

batchSub: This element is a wrapper. It has two optional attributes. If present, these attributes MUST be ignored by the server.

uri: Subscriber's SIP URI
name: Subscriber's name

action: This element defines the subscription action. It has two attributes:

name: MUST be "subscribe" or "unsubscribe".
id: This attribute is ignored by the server if present in the request.

adhocList: This is the wrapper for the resource list.

resource: This element has a URI attribute that is the SIP URI to be subscribed to or unsubscribed from. It is possible to have more than one of these listed, as shown in the preceding example.

context: This is a child-level XML element of a resource element. If the subscriber intends to be added to the resource’s subscriber list, the subscriber SHOULD add this element. When the context element is included, it SHOULD contain a subscriptionContext element with a watcher element, which indicates that a contact has been added as a watcher.<2> If the contact has not previously subscribed to the list, this element triggers the server to notify the owner of the list that the contact is now a subscriber.

If the context element is empty, an implicit assumption is made that the contact specified by uri attribute in batchSub element has previously successfully subscribed to the corresponding resource.

In the preceding example, bob@contoso.com is requesting to be added to the subscriber list of john@contoso.com. Subscriber lists are specified in section 2.2.2.6 and section 3.6.

When the resource is a delegate of the subscriber, the context SHOULD additionally contain a delegation element to notify that the delegate relationship has been set up. This is the primary way to notify a delegate about the permission setting. The delegation node MUST be empty.

<context>
     <subscriptionContext xmlns="http://schemas.microsoft.com/2008/09/sip/SubscriptionContext" majorVersion="1" minorVersion="0">
            <watcher>
              <contactList />
            </watcher>
            <delegation />
     </subscriptionContext> 
</context>

More information about delegation is covered in the [MS-SIPRE] section 3.9.5.2.2.2. The SubscriptionContext schema is described in Section 6.13.

categoryList: This element is a wrapper for the list of category elements.

category: This element represents the category to be subscribed to. It has one required attribute, name, that holds the name of the category. There can be multiple category elements, as shown in the previous example.

2.2.2.4.1 Category Subscribe Request

Additional resources