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

A Helper representing a PubSub Service

Methods

Public Class methods

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 61
61:       def initialize(stream, pubsubjid)
62:         @stream = stream
63:         @pubsubjid = pubsubjid
64:         @event_cbs = CallbackList.new
65:         @stream.add_message_callback(200,self) { |message|
66:           handle_message(message)
67:         }
68:       end

Public Instance methods

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

[Source]

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

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 257
257:       def create_collection_node(node = nil, configure = Jabber::PubSub::NodeConfig.new)
258:         if configure.options['pubsub#node_type'] && configure.options['pubsub#node_type'] != 'collection'
259:           raise Jabber::ArgumentError, "Invalid node_type specified in node configuration. Either do not specify one, or use 'collection'"
260:         end
261:         configure.options = configure.options.merge({'pubsub#node_type' => 'collection'})
262:         create_node(node, configure)
263:       end

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 233
233:       def create_node(node = nil, configure = Jabber::PubSub::NodeConfig.new)
234:         rnode = nil
235:         iq = basic_pubsub_query(:set)
236:         iq.pubsub.add(REXML::Element.new('create')).attributes['node'] = node
237:         if configure
238:           if configure.kind_of?(Jabber::PubSub::NodeConfig)
239:             iq.pubsub.add(configure)
240:           end
241:         end
242: 
243:         @stream.send_with_id(iq) do |reply|
244:           if reply.kind_of?(Jabber::Iq) and reply.type == :result
245:             rnode = node
246:           end
247:         end
248: 
249:         rnode
250:       end

deletes an item from a persistent node

node:[String]
item_id:[String] or [Array] of [String]
return:true

[Source]

     # File lib/xmpp4r/pubsub/helper/servicehelper.rb, line 195
195:       def delete_item_from(node, item_id)
196:         iq = basic_pubsub_query(:set)
197:         retract = iq.pubsub.add(Jabber::PubSub::Retract.new)
198:         retract.node = node
199: 
200:         if item_id.kind_of? Array
201:           item_id.each { |id|
202:             xmlitem = Jabber::PubSub::Item.new
203:             xmlitem.id = id
204:             retract.add(xmlitem)
205:           }
206:         else
207:           xmlitem = Jabber::PubSub::Item.new
208:           xmlitem.id = item_id
209:           retract.add(xmlitem)
210:         end
211: 
212:         @stream.send_with_id(iq)
213:       end

Delete a pubsub node

node:[String]
return:true

[Source]

     # File lib/xmpp4r/pubsub/helper/servicehelper.rb, line 294
294:       def delete_node(node)
295:         iq = basic_pubsub_query(:set,true)
296:         iq.pubsub.add(REXML::Element.new('delete')).attributes['node'] = node
297:         @stream.send_with_id(iq)
298:       end

shows the affiliations on a pubsub service

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

[Source]

     # File lib/xmpp4r/pubsub/helper/servicehelper.rb, line 318
318:       def get_affiliations(node = nil)
319:         iq = basic_pubsub_query(:get)
320:         affiliations = iq.pubsub.add(REXML::Element.new('affiliations'))
321:         affiliations.attributes['node'] = node
322:         res = nil
323:         @stream.send_with_id(iq) { |reply|
324:           if reply.pubsub.first_element('affiliations')
325:             res = {}
326:             reply.pubsub.first_element('affiliations').each_element('affiliation') do |affiliation|
327:               # TODO: This should be handled by an affiliation element class
328:               aff = case affiliation.attributes['affiliation']
329:                       when 'owner' then :owner
330:                       when 'publisher' then :publisher
331:                       when 'none' then :none
332:                       when 'outcast' then :outcast
333:                       else nil
334:                     end
335:               res[affiliation.attributes['node']] = aff
336:             end
337:           end
338:           true
339:         }
340:         res
341:       end

get configuration from a node

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

[Source]

     # File lib/xmpp4r/pubsub/helper/servicehelper.rb, line 269
269:       def get_config_from(node)
270:         iq = basic_pubsub_query(:get, true)
271:         iq.pubsub.add(Jabber::PubSub::OwnerNodeConfig.new(node))
272:         ret = nil
273:         @stream.send_with_id(iq) do |reply|
274:           ret = reply.pubsub.first_element('configure')
275:         end
276:         ret
277:       end

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 133
133:       def get_items_from(node, count=nil)
134:         iq = basic_pubsub_query(:get)
135:         items = Jabber::PubSub::Items.new
136:         items.max_items = count
137:         items.node = node
138:         iq.pubsub.add(items)
139:         res = nil
140:         @stream.send_with_id(iq) { |reply|
141:           if reply.kind_of?(Iq) and reply.pubsub and reply.pubsub.first_element('items')
142:             res = {}
143:             reply.pubsub.first_element('items').each_element('item') do |item|
144:               res[item.attributes['id']] = item.children.first if item.children.first
145:             end
146:           end
147:           true
148:         }
149:         res
150:       end

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 385
385:       def get_options_from(node, jid, subid = nil)
386:         iq = basic_pubsub_query(:get)
387:         iq.pubsub.add(Jabber::PubSub::SubscriptionConfig.new(node, jid.kind_of?(String) ? Jabber::JID.new(jid).strip: jid.strip, subid))
388:         ret = nil
389:         @stream.send_with_id(iq) do |reply|
390:           ret = reply.pubsub.first_element('options')
391:         end
392:         ret
393:       end

shows all jids of subscribers of a node

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

[Source]

     # File lib/xmpp4r/pubsub/helper/servicehelper.rb, line 370
370:       def get_subscribers_from(node)
371:         res = []
372:         get_subscriptions_from(node).each { |sub|
373:           res << sub.jid
374:         }
375:         res
376:       end

shows all subscriptions on the given node

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

[Source]

     # File lib/xmpp4r/pubsub/helper/servicehelper.rb, line 347
347:       def get_subscriptions_from(node)
348:         iq = basic_pubsub_query(:get)
349:         entities = iq.pubsub.add(REXML::Element.new('subscriptions'))
350:         entities.attributes['node'] = node
351:         res = nil
352:         @stream.send_with_id(iq) { |reply|
353:           if reply.pubsub.first_element('subscriptions')
354:             res = []
355:             if reply.pubsub.first_element('subscriptions').attributes['node'] == node
356:               reply.pubsub.first_element('subscriptions').each_element('subscription') { |subscription|
357:                 res << PubSub::Subscription.import(subscription)
358:               }
359:             end
360:           end
361:           true
362:         }
363:         res
364:       end

get all subscriptions on a pubsub component

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

[Source]

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

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

[Source]

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

purges all items on a persistent node

node:[String]
return:true

[Source]

     # File lib/xmpp4r/pubsub/helper/servicehelper.rb, line 220
220:       def purge_items_from(node)
221:         iq = basic_pubsub_query(:set)
222:         purge = REXML::Element.new('purge')
223:         purge.attributes['node'] = node
224:         iq.pubsub.add(purge)
225:         @stream.send_with_id(iq)
226:       end

[Source]

     # File lib/xmpp4r/pubsub/helper/servicehelper.rb, line 300
300:       def set_affiliations(node, jid, role = 'publisher')
301:         iq = basic_pubsub_query(:set, true)
302:         affiliations = iq.pubsub.add(REXML::Element.new('affiliations'))
303:         affiliations.attributes['node'] = node
304:         affiliation = affiliations.add(REXML::Element.new('affiliation'))
305:         affiliation.attributes['jid'] = jid.to_s
306:         affiliation.attributes['affiliation'] = role.to_s
307:         res = nil
308:         @stream.send_with_id(iq) { |reply|
309:           true
310:         }
311:         res
312:       end

set configuration for a node

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

[Source]

     # File lib/xmpp4r/pubsub/helper/servicehelper.rb, line 284
284:       def set_config_for(node, config)
285:         iq = basic_pubsub_query(:set, true)
286:         iq.pubsub.add(config)
287:         @stream.send_with_id(iq)
288:       end

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 402
402:       def set_options_for(node, jid, options, subid = nil)
403:         iq = basic_pubsub_query(:set)
404:         iq.pubsub.add(Jabber::PubSub::SubscriptionConfig.new(node, jid.kind_of?(String) ? Jabber::JID.new(jid).strip: jid.strip, options, subid))
405:         ret = false
406:         @stream.send_with_id(iq) do  |reply|
407:           ret = ( reply.type == :result )
408:         end
409: 
410:         ret
411:       end

subscribe to a node

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

[Source]

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

String representation

result:[String] The PubSub service‘s JID

[Source]

     # File lib/xmpp4r/pubsub/helper/servicehelper.rb, line 416
416:       def to_s
417:         @pubsubjid.to_s
418:       end

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 115
115:       def unsubscribe_from(node, subid=nil)
116:         iq = basic_pubsub_query(:set)
117:         unsub = PubSub::Unsubscribe.new
118:         unsub.node = node
119:         unsub.jid = @stream.jid.strip
120:         iq.pubsub.add(unsub)
121:         ret = false
122:         @stream.send_with_id(iq) { |reply|
123:           ret = reply.kind_of?(Jabber::Iq) and reply.type == :result
124:         } # @stream.send_with_id(iq)
125:         ret
126:       end

[Validate]