Class: Jabber::PubSub::ServiceHelper

Class | Jabber::PubSub::ServiceHelper
In: | lib/xmpp4r/pubsub/helper/servicehelper.rb
Parent: | Object

A Helper representing a PubSub Service

### Methods

add_event_callback create_collection_node create_node delete_node get_affiliations get_config_from get_items_from get_options_from get_subscribers_from get_subscriptions_from get_subscriptions_from_all_nodes new publish_item_to publish_item_with_id_to purge_items_from set_config_for set_options_for subscribe_to to_s unsubscribe_from

### Public Class methods

new(stream, pubsubjid)

Creates a new representation of a pubsub service

stream: | [Jabber::Stream]
pubsubjid: | [String] or [Jabber::JID]

[Source]

        # File lib/xmpp4r/pubsub/helper/servicehelper.rb, line 60
    60:       def initialize(stream, pubsubjid)
    61:         @stream = stream
    62:         @pubsubjid = pubsubjid
    63:         @event_cbs = CallbackList.new
    64:         @stream.add_message_callback(200,self) { |message|
    65:           handle_message(message)
    66:         }
    67:       end

### Public Instance methods

add_event_callback(prio = 200, ref = nil, &block)

Register callbacks for incoming events (i.e. Message stanzas containing) PubSub notifications

[Source]

         # File lib/xmpp4r/pubsub/helper/servicehelper.rb, line 384
    384:       def add_event_callback(prio = 200, ref = nil, &block)
    385:         @event_cbs.add(prio, ref, block)
    386:       end

create_collection_node(node = nil, configure = Jabber::PubSub::NodeConfig.new)

Create a new collection node on the pubsub service

node: | [String] the node name - otherwise you get an automatically generated one (in most cases)
configure: | [Jabber::PubSub::NodeConfig] if you want to configure your node (default nil)
return: | [String]

[Source]

         # File lib/xmpp4r/pubsub/helper/servicehelper.rb, line 231
    231:       def create_collection_node(node = nil, configure = Jabber::PubSub::NodeConfig.new)
    232:         if configure.options['pubsub#node_type'] && configure.options['pubsub#node_type'] != 'collection'
    233:           raise Jabber::ArgumentError, "Invalid node_type specified in node configuration. Either do not specify one, or use 'collection'"
    234:         end
    235:         configure.options = configure.options.merge({'pubsub#node_type' => 'collection'})
    236:         create_node(node, configure)
    237:       end

create_node(node = nil, configure = Jabber::PubSub::NodeConfig.new)

Create a new node on the pubsub service

node: | [String] the node name - otherwise you get a automatically generated one (in most cases)
configure: | [Jabber::PubSub::NodeConfig] if you want to configure your node (default nil)
return: | [String]

[Source]

         # File lib/xmpp4r/pubsub/helper/servicehelper.rb, line 207
    207:       def create_node(node = nil, configure = Jabber::PubSub::NodeConfig.new)
    208:         rnode = nil
    209:         iq = basic_pubsub_query(:set)
    210:         iq.pubsub.add(REXML::Element.new('create')).attributes['node'] = node
    211:         if configure
    212:           if configure.kind_of?(Jabber::PubSub::NodeConfig)
    213:             iq.pubsub.add(configure)
    214:           end
    215:         end
    216:
    217:         @stream.send_with_id(iq) do |reply|
    218:           if reply.kind_of?(Jabber::Iq) and reply.type == :result
    219:             rnode = node
    220:           end
    221:         end
    222:
    223:         rnode
    224:       end

delete_node(node)

Delete a pubsub node

node: | [String]
return: | true

[Source]

         # File lib/xmpp4r/pubsub/helper/servicehelper.rb, line 268
    268:       def delete_node(node)
    269:         iq = basic_pubsub_query(:set,true)
    270:         iq.pubsub.add(REXML::Element.new('delete')).attributes['node'] = node
    271:         @stream.send_with_id(iq)
    272:       end

get_affiliations(node = nil)

shows the affiliations on a pubsub service

node: | [String]
return: | [Hash] of { node => symbol }

[Source]

         # File lib/xmpp4r/pubsub/helper/servicehelper.rb, line 279
    279:       def get_affiliations(node = nil)
    280:         iq = basic_pubsub_query(:get)
    281:         affiliations = iq.pubsub.add(REXML::Element.new('affiliations'))
    282:         affiliations.attributes['node'] = node
    283:         res = nil
    284:         @stream.send_with_id(iq) { |reply|
    285:           if reply.pubsub.first_element('affiliations')
    286:             res = {}
    287:             reply.pubsub.first_element('affiliations').each_element('affiliation') do |affiliation|
    288:               # TODO: This should be handled by an affiliation element class
    289:               aff = case affiliation.attributes['affiliation']
    290:                       when 'owner' then :owner
    291:                       when 'publisher' then :publisher
    292:                       when 'none' then :none
    293:                       when 'outcast' then :outcast
    294:                       else nil
    295:                     end
    296:               res[affiliation.attributes['node']] = aff
    297:             end
    298:           end
    299:           true
    300:         }
    301:         res
    302:       end

get_config_from(node)

get configuration from a node

node: | [String]
return: | [Jabber::PubSub::Configure]

[Source]

         # File lib/xmpp4r/pubsub/helper/servicehelper.rb, line 243
    243:       def get_config_from(node)
    244:         iq = basic_pubsub_query(:get, true)
    245:         iq.pubsub.add(Jabber::PubSub::OwnerNodeConfig.new(node))
    246:         ret = nil
    247:         @stream.send_with_id(iq) do |reply|
    248:           ret = reply.pubsub.first_element('configure')
    249:         end
    250:         ret
    251:       end

get_items_from(node, count=nil)

gets all items from a pubsub node

node: | [String]
count: | [Fixnum]
return: | [Hash] { id => [Jabber::PubSub::Item] }

[Source]

         # File lib/xmpp4r/pubsub/helper/servicehelper.rb, line 132
    132:       def get_items_from(node, count=nil)
    133:         iq = basic_pubsub_query(:get)
    134:         items = Jabber::PubSub::Items.new
    135:         items.node = node
    136:         iq.pubsub.add(items)
    137:         res = nil
    138:         @stream.send_with_id(iq) { |reply|
    139:           if reply.kind_of?(Iq) and reply.pubsub and reply.pubsub.first_element('items')
    140:             res = {}
    141:             reply.pubsub.first_element('items').each_element('item') do |item|
    142:               res[item.attributes['id']] = item.children.first if item.children.first
    143:             end
    144:           end
    145:           true
    146:         }
    147:         res
    148:       end

get_options_from(node, jid, subid = nil)

get options from a subscription

node: | [String]
jid: | [Jabber::JID] or [String]
subid: | [String] or nil
return: | [Jabber::PubSub::OwnerConfigure]

[Source]

         # File lib/xmpp4r/pubsub/helper/servicehelper.rb, line 346
    346:       def get_options_from(node, jid, subid = nil)
    347:         iq = basic_pubsub_query(:get)
    348:         iq.pubsub.add(Jabber::PubSub::SubscriptionConfig.new(node, jid.kind_of?(String) ? Jabber::JID.new(jid).strip: jid.strip, subid))
    349:         ret = nil
    350:         @stream.send_with_id(iq) do |reply|
    351:           ret = reply.pubsub.first_element('options')
    352:         end
    353:         ret
    354:       end

get_subscribers_from(node)

shows all jids of subscribers of a node

node: | [String]
return: | [Array] of [String]

[Source]

         # File lib/xmpp4r/pubsub/helper/servicehelper.rb, line 331
    331:       def get_subscribers_from(node)
    332:         res = []
    333:         get_subscriptions_from(node).each { |sub|
    334:           res << sub.jid
    335:         }
    336:         res
    337:       end

get_subscriptions_from(node)

shows all subscriptions on the given node

node: | [String]
return: | [Array] of [Jabber::Pubsub::Subscription]

[Source]

         # File lib/xmpp4r/pubsub/helper/servicehelper.rb, line 308
    308:       def get_subscriptions_from(node)
    309:         iq = basic_pubsub_query(:get)
    310:         entities = iq.pubsub.add(REXML::Element.new('subscriptions'))
    311:         entities.attributes['node'] = node
    312:         res = nil
    313:         @stream.send_with_id(iq) { |reply|
    314:           if reply.pubsub.first_element('subscriptions')
    315:             res = []
    316:             if reply.pubsub.first_element('subscriptions').attributes['node'] == node
    317:               reply.pubsub.first_element('subscriptions').each_element('subscription') { |subscription|
    318:                 res << PubSub::Subscription.import(subscription)
    319:               }
    320:             end
    321:           end
    322:           true
    323:         }
    324:         res
    325:       end

get_subscriptions_from_all_nodes()

get all subscriptions on a pubsub component

return: | [Hash] of [PubSub::Subscription]

[Source]

        # File lib/xmpp4r/pubsub/helper/servicehelper.rb, line 72
    72:       def get_subscriptions_from_all_nodes
    73:         iq = basic_pubsub_query(:get)
    74:         entities = iq.pubsub.add(REXML::Element.new('subscriptions'))
    75:         res = nil
    76:         @stream.send_with_id(iq) { |reply|
    77:           if reply.pubsub.first_element('subscriptions')
    78:             res = []
    79:             reply.pubsub.first_element('subscriptions').each_element('subscription') { |subscription|
    80:               res << Jabber::PubSub::Subscription.import(subscription)
    81:             }
    82:           end
    83:         }
    84:
    85:         res
    86:       end

publish_item_to(node,item)

NOTE: this method sends only one item per publish request because some services may not allow batch processing. Maybe this will changed in the future?

node: | [String]
item: | [Jabber::PubSub::Item]
return: | true

it automatically generates an id for the item

[Source]

         # File lib/xmpp4r/pubsub/helper/servicehelper.rb, line 157
    157:       def publish_item_to(node,item)
    158:         iq = basic_pubsub_query(:set)
    159:               publish = iq.pubsub.add(REXML::Element.new('publish'))
    160:         publish.attributes['node'] = node
    161:
    162:         if item.kind_of?(Jabber::PubSub::Item)
    163:           item.id = Jabber::IdGenerator.generate_id
    164:           publish.add(item)
    165:           @stream.send_with_id(iq)
    166:         end
    167:       end

publish_item_with_id_to(node,item,id)

node: | [String]
item: | [REXML::Element]
id: | [String]
return: | true

[Source]

         # File lib/xmpp4r/pubsub/helper/servicehelper.rb, line 174
    174:       def publish_item_with_id_to(node,item,id)
    175:         iq = basic_pubsub_query(:set)
    176:         publish = iq.pubsub.add(REXML::Element.new('publish'))
    177:         publish.attributes['node'] = node
    178:
    179:         if item.kind_of?(REXML::Element)
    180:           xmlitem = Jabber::PubSub::Item.new
    181:           xmlitem.id = id
    182:           xmlitem.import(item)
    183:           publish.add(xmlitem)
    184:         else
    185:           raise "given item is not a proper xml document or Jabber::PubSub::Item"
    186:         end
    187:         @stream.send_with_id(iq)
    188:       end

purge_items_from(node)

purges all items on a persistent node

node: | [String]
return: | true

[Source]

         # File lib/xmpp4r/pubsub/helper/servicehelper.rb, line 194
    194:       def purge_items_from(node)
    195:         iq = basic_pubsub_query(:set)
    196:         purge = REXML::Element.new('purge')
    197:         purge.attributes['node'] = node
    198:         iq.pubsub.add(purge)
    199:         @stream.send_with_id(iq)
    200:       end

set_config_for(node, config)

set configuration for a node

node: | [String]
options: | [Jabber::PubSub::NodeConfig]
return: | true on success

[Source]

         # File lib/xmpp4r/pubsub/helper/servicehelper.rb, line 258
    258:       def set_config_for(node, config)
    259:         iq = basic_pubsub_query( :set )
    260:         iq.pubsub.add(config.form)
    261:         @stream.send_with_id(iq)
    262:       end

set_options_for(node, jid, options, subid = nil)

set options for a subscription

node: | [String]
jid: | [Jabber::JID] or [String]
options: | [Jabber::PubSub::SubscriptionConfig} specifying configuration options
subid: | [String] or nil
return: | true

[Source]

         # File lib/xmpp4r/pubsub/helper/servicehelper.rb, line 363
    363:       def set_options_for(node, jid, options, subid = nil)
    364:         iq = basic_pubsub_query(:set)
    365:         iq.pubsub.add(Jabber::PubSub::SubscriptionConfig.new(node, jid.kind_of?(String) ? Jabber::JID.new(jid).strip: jid.strip, options, subid))
    366:         ret = false
    367:         @stream.send_with_id(iq) do  |reply|
    368:           ret = ( reply.type == :result )
    369:         end
    370:
    371:         ret
    372:       end

subscribe_to(node)

subscribe to a node

node: | [String]
return: | [Hash] of { attributename => value }

[Source]

         # File lib/xmpp4r/pubsub/helper/servicehelper.rb, line 91
     91:       def subscribe_to(node)
     92:         iq = basic_pubsub_query(:set)
     93:         sub = REXML::Element.new('subscribe')
     94:         sub.attributes['node'] = node
     95:         sub.attributes['jid'] = @stream.jid.strip.to_s
     96:         iq.pubsub.add(sub)
     97:         res = nil
     98:         @stream.send_with_id(iq) do |reply|
     99:           pubsubanswer = reply.pubsub
    100:           if pubsubanswer.first_element('subscription')
    101:             res = PubSub::Subscription.import(pubsubanswer.first_element('subscription'))
    102:           end
    103:         end # @stream.send_with_id(iq)
    104:         res
    105:       end

to_s()

String representation

result: | [String] The PubSub service‘s JID

[Source]

         # File lib/xmpp4r/pubsub/helper/servicehelper.rb, line 377
    377:       def to_s
    378:         @pubsubjid.to_s
    379:       end

unsubscribe_from(node, subid=nil)

Unsubscribe from a node with an optional subscription id

May raise ServerError

node: | [String]
subid: | [String] or nil (not supported)
return: | true

[Source]

         # File lib/xmpp4r/pubsub/helper/servicehelper.rb, line 114
    114:       def unsubscribe_from(node, subid=nil)
    115:         iq = basic_pubsub_query(:set)
    116:         unsub = PubSub::Unsubscribe.new
    117:         unsub.node = node
    118:         unsub.jid = @stream.jid.strip
    119:         iq.pubsub.add(unsub)
    120:         ret = false
    121:         @stream.send_with_id(iq) { |reply|
    122:           ret = reply.kind_of?(Jabber::Iq) and reply.type == :result
    123:         } # @stream.send_with_id(iq)
    124:         ret
    125:       end

[Validate]