User-Agent Pubsub

From OnSIP Developer Wiki

Jump to: navigation, search


Note: Please review the First XMPP API client notes page before beginning any PubSub integration for important notes on configuring and managing subscriptions.


Contents

Overview

Active Calls pubsub allows for subscribing to evented data regarding the current status of user agents in an OnSIP domain.

PubSub Service JID

pubsub.user-agents.xmpp.onsip.com

User Agents PubSub

JID

pubsub.user-agents.xmpp.onsip.com

Subscription Request/Response Examples

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

  • /me/jid
  • /me/jid/sip-domain
  • /sip-domain/sip-user

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', while subscribing to '/sip-doman' will similarly redirect your subscribtion request to '/me/jid/sip-domain'.

Subscribe to /me/jid level

Subscription requests to the /me/jid level will subscribe you to all the user-agents 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 for user-agents registered to both of these SIP addresses; the corresponding leaf nodes will be /example.com/foo and /acme.com/manager.

Request to PubSub 
<iq type='set' id='sub1'
    from='foo@example.com' to='pubsub.user-agents.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.user-agents.xmpp.onsip.com will always be a subscription "pending": 

<iq from="pubsub.user-agents.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.user-agents.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.user-agents.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 /me/jid/sip-domain level

Subscription requests to the /me/jid/sipo-domain level will subscribe you to all the user-agents you are authorized for on that particular domain.

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 bar@example.com. If you make a subscription request to the node /me/foo@example.com/example.com, you will be subscribed to both /example.com/foo and /example.com/bar.

Request to PubSub 
<iq type='set' id='sub1'
    from='foo@example.com' to='pubsub.user-agents.xmpp.onsip.com'
    xmlns='jabber:client'>
  <pubsub xmlns='http://jabber.org/protocol/pubsub'>
    <subscribe node='/me/foo@example.com/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.user-agents.xmpp.onsip.com for "pending", "subscribed", and "none" will be very similar to the responses documented above for the '/me/foo@example.com' node.

Subscribe to /sip-domain/sip-user level

Subscription requests to the /sip-domain/sip-user level will subscribe you to one particular user-agent.

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 bar@example.com. If you make a subscription request to the node /example.com/foo, you will be subscribed to only /example.com/foo.

Request to PubSub 
<iq type='set' id='sub1'
    from='foo@example.com' to='pubsub.user-agents.xmpp.onsip.com'
    xmlns='jabber:client'>
  <pubsub xmlns='http://jabber.org/protocol/pubsub'>
    <subscribe node='/example.com/foo' 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.user-agents.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 user-agent changes.

New user-agent notification

The following is a sample message that might be received when a user-agent is activated (ie, comes online): 

<message from="pubsub.user-agents.xmpp.onsip.com" to="foo@example.com" >
  <event xmlns="http://jabber.org/protocol/pubsub#event">
    <items node="/example.com/foo" >
      <item id="4e536ee0246ccf0224154a9e72be7a9c" >
        <user-agent xmlns="onsip:user-agents">
          <contact>sip:foo@192.168.0.125:5060;rinstance=d6e716e0dcf01b1b</contact>
          <received>sip:X.Y.W.Z:34873</received>
          <device>SIP User Agent String</device>
          <expires>2009-03-05T12:30:34-05:00</expires>
        </user-agent>
      </item>
    </items>
  </event>
</message>

User-agent offline notification

The following is a sample message that might be received when a user-agent is de-activated (ie, is no longer online): 

<message from="pubsub.user-agents.xmpp.onsip.com" to="foo@example.com" >
  <event xmlns="http://jabber.org/protocol/pubsub#event">
    <items node="/example.com/foo" >
      <retract id="4e536ee0246ccf0224154a9e72be7a9c" />
    </items>
  </event>
</message>
Retrieved from "http://wiki.onsip.com/docs/User-Agent_Pubsub"
Personal tools