Directories Pubsub

From OnSIP Developer Wiki

Contents 1 Overview 1.1 JID 1.2 Subscription Request/Response Examples 1.2.1 Subscribe to /me/jid level 1.2.1.1 Request to PubSub 1.2.1.2 Pending Response from PubSub 1.2.1.3 Subscription Notification from PubSub 1.2.1.4 Subscription Failure Notification from PubSub 1.2.2 Subscribe to /sip-domain level 1.2.2.1 Request to PubSub 1.3 Pubsub Events 1.3.1 Directory entry notification 1.3.2 Directory deletion notification

Overview

The directories pubsub service allows subscribed users to receive updates regarding their organization's directory.

JID

pubsub.directories.xmpp.onsip.com

Subscription Request/Response Examples

There are two node levels that a user can subscribe to:

• /me/jid
• /sip-domain

Different results may be generated depending upon which node is subscribed to.

Please note that subscribing to '/' will redirect your subscribtion request to '/me/jid'.

Subscribe to /me/jid level

Subscription requests to the /me/jid level will subscribe you to all the directories you are authorized for, across all domains.

For example, assume that your jid is foo@example.com. Further, assume that foo@example.com is auth'd for 2 SIP addresses, foo@example.com and manager@acme.com. If you make a subscription request to the node /me/foo@example.com, you will be subscribed to the directories of both of these SIP domains; the corresponding leaf nodes will be /example.com and /acme.com.

Request to PubSub

<iq type='set' id='sub1'
    from='foo@example.com' to='pubsub.directories.xmpp.onsip.com'
    xmlns='jabber:client'>
  <pubsub xmlns='http://jabber.org/protocol/pubsub'>
    <subscribe node='/me/foo@example.com' jid='foo@example.com'/>
    <options>
      <x xmlns='jabber:x:data' type='submit'>
        <field var='FORM_TYPE' type='hidden'>
          <value>http://jabber.org/protocol/pubsub#subscribe_options</value>
        </field>
        <field var='pubsub#subscription_type'>
          <value>items</value>
        </field>
        <field var='pubsub#subscription_depth'>
          <value>all</value>
        </field>
        <field var='pubsub#expire'>
          <value>2010-11-02T22:00:00.0000000Z</value>
        </field>
      </x>
    </options>
  </pubsub>
</iq>

Pending Response from PubSub

The immediate response from pubsub.directories.xmpp.onsip.com will always be a subscription "pending":

<iq from="pubsub.directories.xmpp.onsip.com" type="result" to="foo@example.com/bar-resource" id="sub1" >
  <pubsub xmlns="http://jabber.org/protocol/pubsub">
    <subscription node="/me/foo@example.com" subscription="pending" jid="foo@example.com" />
  </pubsub>
</iq>

Subscription Notification from PubSub

Upon successful subscription to a node, you will receive a subscription "subscribed" response:

<message from="pubsub.directories.xmpp.onsip.com" to="foo@example.com" >
  <event xmlns="http://jabber.org/protocol/pubsub#event">
    <subscription node="/me/foo@example.com" subscription="subscribed" jid="foo@example.com" />
  </event>
</message>

Subscription Failure Notification from PubSub

Upon failure to subscribe to a node, you will receive a subscription "none" response. Subscription failure notifications are generated when you try to subscribe to nodes that you are not auth'd for. IMPORTANT REMINDER: you must first authenticate with pubsub.auth.xmpp.onsip.com before you can subscribe to a node.

<message from="pubsub.directories.xmpp.onsip.com" to="foo@example.com" >
  <event xmlns="http://jabber.org/protocol/pubsub#event">
    <subscription node="/me/foo@example.com" subscription="none" jid="foo@example.com" />
  </event>
</message>

Subscribe to /sip-domain level

Subscription requests to the /sip-domain will subscribe you to one particular organization's directory.

For this example, assume that your jid is foo@example.com. Further, assume that foo@example.com is auth'd for 2 SIP addresses, foo@example.com and manager@acme.com. If you make a subscription request to the node /example.com, you will be subscribed to only /example.com.

Request to PubSub

<iq type='set' id='sub1'
    from='foo@example.com' to='pubsub.directories.xmpp.onsip.com'
    xmlns='jabber:client'>
  <pubsub xmlns='http://jabber.org/protocol/pubsub'>
    <subscribe node='/example.com' jid='foo@example.com'/>
    <options>
      <x xmlns='jabber:x:data' type='submit'>
        <field var='FORM_TYPE' type='hidden'>
          <value>http://jabber.org/protocol/pubsub#subscribe_options</value>
        </field>
        <field var='pubsub#subscription_type'>
          <value>items</value>
        </field>
        <field var='pubsub#subscription_depth'>
          <value>all</value>
        </field>
      </x>
    </options>
  </pubsub>
</iq>

The responses from pubsub.directories.xmpp.onsip.com for "pending", "subscribed", and "none" will be very similar to the responses documented above for the '/me/foo@example.com' node.

Pubsub Events

Pubsub returns event messages to the client when the status of a directory changes.

Directory entry notification

The following is a sample message that might be received when a directory entry is added or modified:

To do:  Add message here

Directory deletion notification

The following is a sample message that might be received when a directory entry is deleted:

To do:  Add message here