XMPP For The Web/Win ::: XMPP-FTW (1.18.0) Flattr this

XEP-0060 Publish-Subscribe (PubSub)

Create a node

        socket.send(
            'xmpp.pubsub.create',
            {
                "to": "pubsub.evilprofessor.co.uk",
                "node": "xmpp-ftw updates",
             /* "options": [] */
            },
            function(error, data) { console.log(error, data) }
        )
        

options should be formatted as a data form in order to add node configuration options at creation time.

If the node is successfully created `error` will be null and `data` will be true.

Delete a node

        socket.send(
            'xmpp.pubsub.delete',
            {
                "to": "pubsub.evilprofessor.co.uk",
                "node": "xmpp-ftw updates",
             /* "redirect": "xmpp:pubsub.evilprofessor.co.uk?;node=xmpp-ftw-news" */
            },
            function(error, data) { console.log(error, data) }
        )
        

Notification of a delete

On successful node delete notifications are sent out to all subscribed users.

        {
            from: "pubsub.evilprofessor.co.uk",
            node: "xmpp-ftw updates",
         /* redirect: "xmpp:pubsub.evilprofessor.co.uk?;node=xmpp-ftw-news" */
        }
        

Subscribe to a node

        socket.send(
            'xmpp.pubsub.subscribe',
            {
                "node": "xmpp-ftw updates",
                "to": "pubsub.evilprofessor.co.uk",
             /* "jid": "lloyd@evilprofessor.co.uk/sky" */
            },
            function(error, data) { console.log(error, data) }
        )
        

If no JID is provided this defaults to the jid used to log in to the server with.

If a subscription is successful then the response will look like the following:

        {
            "subscription": "subscribed",
         /* "id" : "subscription-id" */
        }
        

Alternatively if configuration options are available the `configuration` key will be present. If configuration is required then the `required` sub-key will be true:

        {
            "subscription": "unconfigured",
         /* "id": "subscription-id", */
            "configuration": { "required": true }
        }
        

Get subscription options

        socket.send(
            'xmpp.pubsub.subscription.config.get',
            {
                "to": "pubsub.evilprofessor.co.uk",
                "node": "xmpp-ftw updates",
             /* "jid": "lloyd@evilprofessor.co.uk/sky" */
            },
            function(error, data) { console.log(error, data) }
        )
        

The response should then contain a data form.

        {
            "description": "Subscription options",
            "title": "Node subscription",
            "fields": []
        }
        

Get default subscription configuration options

        socket.send(
            'xmpp.pubsub.subscription.config.default",
            {
                "to": "pubsub.evilprofessor.co.uk",
             /* "node": "xmpp-ftw updates" */
            },
            function(error, data) { console.log(error, data) }
        )

        

The response should then contain a data form.

        {
            "fields": []
        }
        

Update subscription options

        socket.send(
            'xmpp.pubsub.subscription.config.set',
            {
                "to": "pubsub.evilprofessor.co.uk",
                "node": "xmpp-ftw updates",
                "form": []
             /* "jid": "lloyd@evilprofessor.co.uk/sky" */
        )
        

See data forms for details about formatting the outgoing message.

Notification of subscription change

Changes to subscriptions are pushed out via the `xmpp.pubsub.push.subscription` event:

        {
            from: "pubsub.evilprofessor.co.uk",
            node: "xmpp-ftw updates",
            jid: {
                domain: "evilprofessor.co.uk",
                user: "megan"
            },
            subscription: "subscribed",
        }
        

Subscription authorisation request

If required, and if supported by the server, a node owner will receive a subscription authorisation request as follows:

        socket.on('xmpp.pubsub.push.authorisation', function(data, callback) {
            console.log(data)
            callback( /* see below */ )
        })
        

With the data in the following format:

        {
            from: "pubsub.evilprofessor.co.uk",
            id: "approve1",
            form: {}
        }
        

In order to reply to a subscription authorisation request the callback function should be used as follows (actual field data will depend on received data form):

        [
            { var: "pubsub#node", value: "xmpp-ftw updates" },
            { var: "pubsub#subscriber_jid": value: "megan@evilprofessor.co.uk" },
            { var: "pubsub#allow", value: "true" }
        ]
        

Updating a subscribers subscription

As a node owner it is also possible to update the subscription state of subscribers as follows:

        socket.send(
            'xmpp.pubsub.subscription',
            {
                "to":            "pubsub.evilprofessor.co.uk",
                "node":          "xmpp-ftw updates",
                "jid":           "bad-person@evilprofessor.co.uk",
                "subscription" : "none"
            },
            function(error, data) { console.log(error, data) }
        )
        

On success the data argument will simply be true.

Unsubscribe from a node

        socket.send(
            'xmpp.pubsub.unsubscribe',
            {
                "to": "pubsub.evilprofessor.co.uk",
                "node": "xmpp-ftw updates",
             /* "jid": "lloyd@evilprofessor.co.uk/sky", */
             /* "id": "subscription-id" */
            },
            function(error, data) { console.log(error, data) }
        )
        

If there is no error `data` will simply be true.

Publishing

For information on publishing formats see the page on publishing.

        socket.send(
            'xmpp.pubsub.publish',
            {
                "to": "pubsub.evilprofessor.co.uk",
                "node": "xmpp-ftw updates",
                "content": "We can now post to a pub-sub node!",
             /* "id": "1" */
             /* "options": [] */
            },
            function(error, data) { console.log(error, data) }
        )
        

Providing a 'id' attribute will allow you to set post ID# rather than accept a server auto-generated value.

options should be formatted as a data form and allows the user to set publish options.

A successful post will result in the following response:

        {
            "id": "1"
        }
        

Notification of new messages

When an item is published to a node that your user is subscribed to then a message will be received with item details.

        socket.on('xmpp.pubsub.push.item', function(data) {
            console.log(data)
        })
        

The item itself is parsed by `xmpp-ftw-item-parser` and is held in the item key if the payload is included.

        {
            from: 'pubsub.evilprofessor.co.uk',
            node: 'weather',
            id:   '201305301825',
         /* entry: ...as parsed by xmpp-ftw-item-parser... */
         /* headers: [ { name: 'SubID', value: '123-abc' } ], */
         /* publisher: "lloyd@evilprofessor.co.uk" */
        }
        

Delete an item

        socket.send(
            'xmpp.pubsub.item.delete',
            {
                "to": "pubsub.evilprofessor.co.uk",
                "node": "xmpp-ftw updates",
                "id": "1"
            },
            function(error, data) { console.log(error, data) }
        )
        

If deletion is sucessful then `data` will simply be true.

Item deletion notification

If an item is successfully deleted from a node then all subscribers will be notified of this event (configuration dependent).

        socket.on('xmpp.pubsub.push.retract', function(data) {
            console.log(data)
        })
        

With the payload as follows:

        {
            node: 'weather',
            from: 'pubsub.evilprofessor.co.uk',
            id: '201305301825'
        }
        

Purge node items

        socket.send(
            'xmpp.pubsub.purge',
            {
              "to": "pubsub.evilprofessor.co.uk",
              "node": "xmpp-ftw updates"
            },
            function(error, data) { console.log(error, data) }
        )
        

If purge is sucessful then `data` will be true.

Notification of purged node

        socket.on('xmpp.pubsub.purge', function(data) { console.log(data) }
        

With the payload as follows:

        {
            from: "pubsub.evilprofessor.co.uk",
            node: "xmpp-ftw updates"
        }
        

Node Configuration

Get node configuration

        socket.send(
            'xmpp.pubsub.config.get',
            {
                "to": "pubsub.evilprofessor.co.uk",
                "node": "xmpp-ftw updates"
            },
            function(error, data) { console.log(error, data) }
        )
        

Note: I can not currently test this as Prosody 0.9 does not support it. Once supported I will return and test.

Set node configuration

        socket.send(
            'xmpp.pubsub.config.set',
            {
                "to": "pubsub.evilprofessor.co.uk",
                "node": "xmpp-ftw updates",
                "form": []
            },
            function(error, data) { console.log(error, data) }
        )
        

If configuration update is sucessful then `data` will simply be true.

Note: I can not currently test this as Prosody 0.9 does not support it. Once supported I will return and test.

Node configuration update notification

On update of a node's configuration then a notification will be sent to all node subscribers.

        socket.on('xmpp.pubsub.push.configuration', function(data) {
            console.log(data)
        })
        

With data looking as follows:

        {
            from: 'pubsub.evilprofessor.co.uk',
            node: 'weather',
         /* configuration: {} */
        }
        

configuration if provided will match the parsing of other data forms.

Item Retrieval

Get item(s)

Item retrieval supports RSM see the manual page for more details on how this works.

        socket.send(
            'xmpp.pubsub.retrieve',
            {
                "to": "pubsub.evilprofessor.co.uk",
                "node": "xmpp-ftw updates",
             /* "id": "1" ...OR... [ "1", "3", "5" ], */
             /* "maxItems": 10, */
             /* "rsm": {
                     "max": 20,
                     "after": "item-id-4"
                 } */
            },
            function(error, data, rsm) { console.log(error, data, rsm) }
        )
        

If a single item is required then the 'id' attribute should be populated.

The response then appears as follows:

        [
            {
                id: 'item-123',
                entry: {},
             /* publisher: 'romeo@example.com' */
            }
        ]
        

Where entry is parsed by `xmpp-ftw-item-parser`.

Subscriptions

Get subscriptions

This method supports RSM.

        socket.send(
            'xmpp.pubsub.subscriptions',
            {
                "to": "pubsub.evilprofessor.co.uk",
             /* "node": "xmpp-ftw updates", */
             /* "owner": true */
            },
            function(error, data) { console.log(error, data) }
        )
        

Setting owner to true will return information about all subscriptions to that node. This is provided you are the owner of the node, otherwise an error will be returned.

A successful response will then be as follows:

        [
            { node: "xmpp-ftw updates", jid: "lloyd@evilprofessor.co.uk", subscription: "subscribed" }
            { node: "weather", jid: "lloyd@evilprofessor.co.uk", subscription: "pending", id: "123" }
        ]
        

Affiliations

Get node affiliations

This method supports RSM.

        socket.send(
            'xmpp.pubsub.affiliations',
            {
                "to": "pubsub.evilprofessor.co.uk",
             /* "node": "xmpp-ftw updates", */
             /* "owner": true" */
            },
            function(error, data) { console.log(error, data) }
        )
        

Setting owner to true allows the user to get a list of all node affiliations provided they are the owner of the node (otherwise an error is returned.

A successful response will then be as follows:

        [
            {
                jid: { user: "lloyd", domain: "evilprofessor.co.uk", resource: "laptop" },
                affiliation: 'owner'
           },
           {
                jid: { user: "dev-kitty-1", domain: "evilprofessor.co.uk", resource: "lap" },
                affiliation: 'member'
           }
       ]
        }
        

Set node affiliation

        socket.send(
            'xmpp.pubsub.affiliation',
            {
                "to": "pubsub.evilprofessor.co.uk",
                "node": "xmpp-ftw updates",
                "jid": "troll@underthebrid.ge",
                "affiliation": "outcast"
            },
            function(error, data) { console.log(error, data) }
        )
        

If the node is successfully created `error` will be null and `data` will be true.

Note: Whilst specification allows user to update several affiliation changes at once, only on per message is supported here. If required it can be added later.

Notification of affiliation changes

The event name for these changes is `xmpp.pubsub.push.affiliation`.

        {
            from: "pubsub.evilprofessor.co.uk",
            node: "xmpp-ftw updates",
            jid: {
                domain: "evilprofessor.co.uk",
                user: "bad-person"
            },
            affiliation: "none"
        }
        

Pages

Fork me on GitHub