First XMPP API client

From OnSIP Developer Wiki

Contents 1 Presence and Priority 1.1 Brief 1.2 Description 1.3 References 2 PubSub 2.1 Brief 2.2 Description 2.3 References 3 PubSub: Subscription Depth 3.1 Brief 3.2 Description 3.3 References 4 PubSub: Renewing and Reusing Subscriptions 4.1 Brief 4.2 Description 4.2.1 Retrieve Subscriptions Request 4.2.2 Response with no existing subscriptions 4.2.3 Response with existing subscriptions 4.2.4 Renew Node Subscription 4.2.5 Renew Subscription 4.2.6 Success Response To Subscription Renewal 4.3 References 5 PubSub: Access Model 5.1 Brief 5.2 Description 5.3 References

Presence and Priority

Brief

• Send <presence> stanzas with a priority greater than zero

Description

Please be sure that your client is sending a <presence> stanza as defined by the XMPP IM and Presence RFC section on Presence. In particular please be sure the the priority, of that presence stanza is set to a valid non-negative integer. A negative presence will tell your Jabber server NOT to send your client messages. That means any event coming from a PubSub service (or any other <message> stanza) will NOT be routed to your client. See Section 11 of the XMPP IM and Presence RFC for more information on priority based message routing.

References

1. RFC 3921: Exchanging Presence Information
2. RFC 3921: Server Rules for Handling XML Stanzas

PubSub

Brief

• PubSub is used to deliver real time API events, such as a new call.

Description

All asynchronous messaging in the XMPP API is handled by XMPP Publish Subscribe. When subscribing to a node it is recommended that the jid attribute on the subscription request includes the currently connected resource in order to ensure that notifications are delivered to appropriate clients. However, if the currently connected client is disconnected before unsubscribing then messages will be delivered to one of the other connected clients. Therefore clients should check the resource on the to attribute of any message stanzas (particularly those from PubSub services) to verify the resource is correct before processing messages.

References

1. XMPP Publish Subscribe

PubSub: Subscription Depth

Brief

• Our PubSub implementations are built using collection nodes. Any subscriptions made to a collection node must set the subscription option of pubsub#subscription_depth to the value "all" in order to receive all events published to any descendant leaf node of the current node

Description

References

1. XEP 248: Subscribe to a Collection Node

PubSub: Renewing and Reusing Subscriptions

Brief

• A hard limit of 10 subscriptions/node/JID is implemented in our pubsub service. Please cleanup your subscriptions when you're done and/or reuse subscriptions on your initial subscription attempt.

Description

The first step to subscribing to a node should be checking for any existing subscriptions on that node. If the response comes back indicating there are no existing subscriptions for the node you are trying to subscribe to, then continue with the normal subscription process. However if a response is returned that indicates there are existing subscriptions for your full JID then you should reconfigure the subscription with the appropriate configuration options.

Retrieve Subscriptions Request

<iq type='get' id='subman1'
 to='pubsub.active-calls.xmpp.onsip.com'
    xmlns='jabber:client'>
  <pubsub xmlns='http://jabber.org/protocol/pubsub'>
    <subscriptions node="/me/jgreen@example.onsip.com"/>
  </pubsub>
</iq>

Response with no existing subscriptions

Feel free to create a new subscription

<iq from="pubsub.active-calls.xmpp.onsip.com" 
    type="result" 
    id="subman1" 
    to="jgreen@example.onsip.com/newyorkcity" >
  <pubsub xmlns="http://jabber.org/protocol/pubsub">
    <subscriptions/>
  </pubsub>
</iq>

Response with existing subscriptions

Be sure to only reconfigure a subscription owned by your full JID on the node that you are interested in

<iq from="pubsub.active-calls.xmpp.onsip.com" 
    type="result" 
    id="subman1" 
    to="jgreen@example.onsip.com/newyorkcity" >
  <pubsub xmlns="http://jabber.org/protocol/pubsub">
    <subscriptions>
      <subscription subscription="subscribed" 
                    subid="508B107D93C38" 
                    jid="jgreen@example.onsip.com/newyorkcity" />
      <subscription subscription="subscribed" 
                    subid="508B188F98CF6" 
                    jid="jgreen@example.onsip.com/boston" />
    </subscriptions>
  </pubsub>
</iq>

Renew Node Subscription

After identifying an existing subscription that should be reused, you will need to update the subscription by reconfiguring the node. The node, jid, and subid attributes will need to be set on the options element of the configuration form. Also, the configuration option values should be the same as those sent in the initial subscription request, except for an update pubsub#expire value.

Renew Subscription

<iq type='set'
    to='pubsub.active-calls.xmpp.onsip.com'
    id='optionconfig1'>
  <pubsub xmlns='http://jabber.org/protocol/pubsub'>
    <options node="/me/jgreen@example.onsip.com" 
             subid="508B107D93C38" 
             jid="jgreen@example.onsip.com/newyorkcity" >
      <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-02T12:00:00.0000000Z</value>
        </field>
      </x>
    </options>
  </pubsub>
</iq>

Success Response To Subscription Renewal

<iq from="pubsub.active-calls.xmpp.onsip.com" 
    type="result" 
    id="optionconfig1" 
    to="jgreen@example.onsip.com/newyorkcity" />

References

1. XEP 60: Entity Subscriptions see example 24
2. XEP 60: Configuring Subscription Options
3. XEP 60: Time Based Subscriptions see example 221

PubSub: Access Model

Brief

• Our PubSub nodes implement the authorize access model. As such all subscription IQ requests will return an immediate response with state "pending", and then a message stanza sometime later with either subscription state "subscribed" or "none".

Description

There are several access models of pubsub, see http://xmpp.org/extensions/xep-0060.html#accessmodels. We happen to be using the "authorize" access model which is dependent on a series of asynchronous requests happening behind the scenes.

In the authorize model a third entity is contacted behind the scenes by the pubsub service to determine a requesters ability to subscribe to a node. Since an IQ needs an immediate response, the pending status is returned while the node owner (the third party entity) determines whether or not the requester is allowed to subscribe, see http://xmpp.org/extensions/xep-0060.html#subscriber-subscribe-approval. Sometime later, the third party (the node owner) determines whether or not the requester has the right to subscribe. At this point the node owner indicates this back to pubsub with either a positive or negative response. Upon the pubsub service receiving this answer it (the pubsub service) sends a message back to the requester, see http://xmpp.org/extensions/xep-0060.html#owner-subreq specifically example 158.

Any clients attempting to implement any PubSub features of our XMPP API MUST be able to deal with access model authorize.

References

1. XEP 60: Access Models
2. XEP 60: Approval Required
3. XEP 60: Manage Subscription Requests