### Home Classes Methods

### In Files

- lib/xmpp4r/roster/helper/roster.rb

### Parent

Object

### Namespace

- CLASS Jabber::Roster::Helper::RosterItem

### Methods

- ::new
- #[]
- #accept_subscription
- #add
- #add_presence_callback
- #add_query_callback
- #add_subscription_callback
- #add_subscription_request_callback
- #add_update_callback
- #decline_subscription
- #find
- #find_by_group
- #get_roster
- #groups
- #wait_for_roster

### Files

- CHANGELOG
- COPYING
- LICENSE
- README.rdoc
- README_ruby19.txt

### Class/Module Index

Quicksearch

- Jabber
- Jabber::ArgumentError
- Jabber::Bytestreams
- Jabber::Bytestreams::IBB
- Jabber::Bytestreams::IBBInitiator
- Jabber::Bytestreams::IBBQueueItem
- Jabber::Bytestreams::IBBTarget
- Jabber::Bytestreams::IqQueryBytestreams
- Jabber::Bytestreams::IqSi
- Jabber::Bytestreams::IqSiFile
- Jabber::Bytestreams::IqSiFileRange
- Jabber::Bytestreams::SOCKS5Bytestreams
- Jabber::Bytestreams::SOCKS5BytestreamsInitiator
- Jabber::Bytestreams::SOCKS5BytestreamsPeer
- Jabber::Bytestreams::SOCKS5BytestreamsServer
- Jabber::Bytestreams::SOCKS5BytestreamsServerStreamHost
- Jabber::Bytestreams::SOCKS5BytestreamsTarget
- Jabber::Bytestreams::SOCKS5Socket
- Jabber::Bytestreams::StreamHost
- Jabber::Bytestreams::StreamHostUsed
- Jabber::Callback
- Jabber::CallbackList
- Jabber::Caps
- Jabber::Caps::C
- Jabber::Caps::Helper
- Jabber::Client
- Jabber::ClientAuthenticationFailure
- Jabber::Command
- Jabber::Command::IqCommand
- Jabber::Command::Responder
- Jabber::Component
- Jabber::ComponentAuthenticationFailure
- Jabber::Connection
- Jabber::Connection::SSLSocketUTF8
- Jabber::Dataforms
- Jabber::Dataforms::XData
- Jabber::Dataforms::XDataField
- Jabber::Dataforms::XDataInstructions
- Jabber::Dataforms::XDataReported
- Jabber::Dataforms::XDataTitle
- Jabber::Delay
- Jabber::Delay::XDelay
- Jabber::Discovery
- Jabber::Discovery::Feature
- Jabber::Discovery::Helper
- Jabber::Discovery::Identity
- Jabber::Discovery::IqQueryDiscoInfo
- Jabber::Discovery::IqQueryDiscoItems
- Jabber::Discovery::Item
- Jabber::Discovery::Responder
- Jabber::EntityTime
- Jabber::EntityTime::IqTime
- Jabber::EntityTime::Responder
- Jabber::ErrorResponse
- Jabber::FeatureNegotiation
- Jabber::FeatureNegotiation::IqFeature
- Jabber::FileTransfer
- Jabber::FileTransfer::FileSource
- Jabber::FileTransfer::Helper
- Jabber::FileTransfer::TransferSource
- Jabber::Framework
- Jabber::Framework::Base
- Jabber::Framework::Bot
- Jabber::HTTPBinding
- Jabber::HTTPBinding::Client
- Jabber::IdGenerator
- Jabber::InvalidChatState
- Jabber::Iq
- Jabber::IqQuery
- Jabber::JID
- Jabber::JabberError
- Jabber::LastActivity
- Jabber::LastActivity::Helper
- Jabber::LastActivity::IqQueryLastActivity
- Jabber::MUC
- Jabber::MUC::IqQueryMUCAdmin
- Jabber::MUC::IqQueryMUCAdminItem
- Jabber::MUC::IqQueryMUCOwner
- Jabber::MUC::MUCBrowser
- Jabber::MUC::MUCClient
- Jabber::MUC::SimpleMUCClient
- Jabber::MUC::UserItem
- Jabber::MUC::XMUC
- Jabber::MUC::XMUCUser
- Jabber::MUC::XMUCUserInvite
- Jabber::MUC::XMUCUserItem
- Jabber::Message
- Jabber::NoNameXmlnsRegistered
- Jabber::NotConnected
- Jabber::Observable
- Jabber::Observable::Contact
- Jabber::Observable::PubSub
- Jabber::Observable::PubSub::AlreadySet
- Jabber::Observable::PubSub::NoService
- Jabber::Observable::Subscriptions
- Jabber::Presence
- Jabber::PubSub
- Jabber::PubSub::Configuration
- Jabber::PubSub::Event
- Jabber::PubSub::EventItem
- Jabber::PubSub::EventItems
- Jabber::PubSub::IqPubSub
- Jabber::PubSub::IqPubSubOwner
- Jabber::PubSub::Item
- Jabber::PubSub::Items
- Jabber::PubSub::NodeBrowser
- Jabber::PubSub::NodeConfig
- Jabber::PubSub::NodeHelper
- Jabber::PubSub::OAuthPubSubStreamHelper
- Jabber::PubSub::OAuthServiceHelper
- Jabber::PubSub::OwnerNodeConfig
- Jabber::PubSub::Publish
- Jabber::PubSub::Retract
- Jabber::PubSub::ServiceHelper
- Jabber::PubSub::Subscription
- Jabber::PubSub::SubscriptionConfig
- Jabber::PubSub::Unsubscribe
- Jabber::RPC
- Jabber::RPC::Client
- Jabber::RPC::IqQueryRPC
- Jabber::RPC::Server
- Jabber::Reliable
- Jabber::Reliable::Connection
- Jabber::Reliable::Listener
- Jabber::Roster
- Jabber::Roster::Helper
- Jabber::Roster::Helper::RosterItem
- Jabber::Roster::IqQueryRoster
- Jabber::Roster::RosterItem
- Jabber::Roster::RosterX
- Jabber::Roster::RosterXItem
- Jabber::Roster::XRoster
- Jabber::Roster::XRosterItem
- Jabber::SASL
- Jabber::SASL::Anonymous
- Jabber::SASL::Base
- Jabber::SASL::DigestMD5
- Jabber::SASL::Plain
- Jabber::SOCKS5Error
- Jabber::Semaphore
- Jabber::ServerDisconnected
- Jabber::Stream
- Jabber::Stream::ThreadBlock
- Jabber::StreamParser
- Jabber::Test
- Jabber::Test::ListenerMocker
- Jabber::UserLocation
- Jabber::UserLocation::Helper
- Jabber::UserLocation::Location
- Jabber::UserTune
- Jabber::UserTune::Helper
- Jabber::UserTune::Tune
- Jabber::Vcard
- Jabber::Vcard::Helper
- Jabber::Vcard::IqVcard
- Jabber::Version
- Jabber::Version::IqQueryVersion
- Jabber::Version::Responder
- Jabber::Version::SimpleResponder
- Jabber::X
- Jabber::XHTML
- Jabber::XHTML::Body
- Jabber::XHTML::HTML
- Jabber::XMPPElement
- Jabber::XMPPStanza
- Jabber::XParent
- REXML
- REXML::Element
- REXML::IOSource
- XMLRPC
- XMLRPC::Create
- Base64
- ObservableThing
- QObserver
- ThreadStore

No matching classes.

# Jabber::Roster::Helper

The Roster helper intercepts `<iq/>` stanzas with Jabber::IqQueryRoster and `<presence/>` stanzas, but provides cbs which allow the programmer to keep track of updates.

A thread for any received stanza is spawned, so the user can invoke accept_subscription et al in the callback blocks, without stopping the current (= parser) thread when waiting for a reply.

### Attributes

items[R]

All items in your roster

items

Hash

  ([JID] => [Roster::Helper::RosterItem])

### Public Class Methods

new(stream, startnow = true) click to toggle source

Initialize a new Roster helper

Registers its cbs (prio = 120, ref = self)

Request a roster (Remember to send initial presence afterwards!)

The initialization will not wait for the roster being received, use wait_for_roster.

Attention: If you send presence and receive presences before the roster has arrived, the Roster helper will let them pass through and does not keep them!

    # File lib/xmpp4r/roster/helper/roster.rb, line 39
    def initialize(stream, startnow = true)
      @stream = stream
      @items = {}
      @items_lock = Mutex.new
      @roster_wait = Semaphore.new
      @query_cbs = CallbackList.new
      @update_cbs = CallbackList.new
      @presence_cbs = CallbackList.new
      @subscription_cbs = CallbackList.new
      @subscription_request_cbs = CallbackList.new

      # Register cbs
      stream.add_iq_callback(120, self) { |iq|
        if iq.query.kind_of?(IqQueryRoster)
          Thread.new do
            Thread.current.abort_on_exception = true
            handle_iq_query_roster(iq)
          end

          true
        else
          false
        end
      }
      stream.add_presence_callback(120, self) { |pres|
        Thread.new do
          Thread.current.abort_on_exception = true
          handle_presence(pres)
        end
      }
      get_roster if startnow
    end

### Public Instance Methods

[](jid) click to toggle source

Get an item by jid

If not available tries to look for it with the resource stripped

    # File lib/xmpp4r/roster/helper/roster.rb, line 247
    def [](jid)
      jid = JID.new(jid) unless jid.kind_of? JID

      @items_lock.synchronize {
        if @items.has_key?(jid)
          @items[jid]
        elsif @items.has_key?(jid.strip)
          @items[jid.strip]
        else
          nil
        end
      }
    end

accept_subscription(jid, iname=nil) click to toggle source

Accept a subscription request

- Sends a <presence type='subscribed'/> stanza

- Adds the contact to your roster

jid

JID

  of contact

iname

String

  Optional roster item name

    # File lib/xmpp4r/roster/helper/roster.rb, line 350
    def accept_subscription(jid, iname=nil)
      pres = Presence.new.set_type(:subscribed).set_to(jid.strip)
      @stream.send(pres)

      unless self[jid.strip]
        request = Iq.new_rosterset
        request.query.add(Jabber::Roster::RosterItem.new(jid.strip, iname))
        @stream.send_with_id(request)
      end
    end

add(jid, iname=nil, subscribe=false) click to toggle source

Add a user to your roster

Threading is encouraged as the function waits for a result. ServerError is thrown upon error.

See Jabber::Roster::Helper::RosterItem#subscribe for details about subscribing. (This method isn't used here but the same functionality applies.)

If the item is already in the local roster it will simply send itself

jid

JID

  to add

iname

String

  Optional item name

subscribe

Boolean

  Whether to subscribe to this jid

    # File lib/xmpp4r/roster/helper/roster.rb, line 326
    def add(jid, iname=nil, subscribe=false)
      if self[jid]
        self[jid].send
      else
        request = Iq.new_rosterset
        request.query.add(Jabber::Roster::RosterItem.new(jid, iname))
        @stream.send_with_id(request)
        # Adding to list is handled by handle_iq_query_roster
      end

      if subscribe
        # Actually the item *should* already be known now,
        # but we do it manually to exclude conditions.
        pres = Presence.new.set_type(:subscribe).set_to(jid.strip)
        @stream.send(pres)
      end
    end

add_presence_callback(prio = 0, ref = nil, &block) click to toggle source

Add a callback for Jabber::Presence updates

This will be called for `<presence/>` stanzas for known RosterItems. Unknown JIDs may still pass and can be caught via Jabber::Stream#add_presence_callback.

The block receives three objects:

- the Jabber::Roster::Helper::RosterItem

- the old Jabber::Presence (or nil)

- the new Jabber::Presence (or nil)

    # File lib/xmpp4r/roster/helper/roster.rb, line 119
    def add_presence_callback(prio = 0, ref = nil, &block)
      @presence_cbs.add(prio, ref, block)
    end

add_query_callback(prio = 0, ref = nil, &block) click to toggle source

Add a callback to be called when a query has been processed

Because update callbacks are called for each roster item, this may be appropriate to notify that anything has updated.

Arguments for callback block: The received `<iq/>` stanza

    # File lib/xmpp4r/roster/helper/roster.rb, line 92
    def add_query_callback(prio = 0, ref = nil, &block)
      @query_cbs.add(prio, ref, block)
    end

add_subscription_callback(prio = 0, ref = nil, &block) click to toggle source

Add a callback for subscription updates, which will be called upon receiving a `<presence/>` stanza with type:

- :subscribed

- :unsubscribe

- :unsubscribed

The block receives two objects:

- the Jabber::Roster::Helper::RosterItem (or nil)

- the `<presence/>` stanza

    # File lib/xmpp4r/roster/helper/roster.rb, line 134
    def add_subscription_callback(prio = 0, ref = nil, &block)
      @subscription_cbs.add(prio, ref, block)
    end

add_subscription_request_callback(prio = 0, ref = nil, &block) click to toggle source

Add a callback for subscription requests, which will be called upon receiving a `<presence type='subscribe'/>` stanza

The block receives two objects:

- the Jabber::Roster::Helper::RosterItem (or nil)

- the `<presence/>` stanza

Response to this event can be taken with accept_subscription and decline_subscription.

Example usage:

    my_roster.add_subscription_request_callback do |item,presence|
      if accept_subscription_requests
        my_roster.accept_subscription(presence.from)
      else
        my_roster.decline_subscription(presence.from)
      end
    end

    # File lib/xmpp4r/roster/helper/roster.rb, line 157
    def add_subscription_request_callback(prio = 0, ref = nil, &block)
      @subscription_request_cbs.add(prio, ref, block)
    end

add_update_callback(prio = 0, ref = nil, &block) click to toggle source

Add a callback for Jabber::Roster::Helper::RosterItem updates

Note that this will be called much after initialization for the answer of the initial roster request

The block receives two objects:

- the old Jabber::Roster::Helper::RosterItem

- the new Jabber::Roster::Helper::RosterItem

    # File lib/xmpp4r/roster/helper/roster.rb, line 105
    def add_update_callback(prio = 0, ref = nil, &block)
      @update_cbs.add(prio, ref, block)
    end

decline_subscription(jid) click to toggle source

Decline a subscription request

- Sends a <presence type='unsubscribed'/> stanza

    # File lib/xmpp4r/roster/helper/roster.rb, line 364
    def decline_subscription(jid)
      pres = Presence.new.set_type(:unsubscribed).set_to(jid.strip)
      @stream.send(pres)
    end

find(jid) click to toggle source

Returns the list of RosterItems which, stripped, are equal to the one you are looking for.

    # File lib/xmpp4r/roster/helper/roster.rb, line 264
    def find(jid)
      jid = JID.new(jid) unless jid.kind_of? JID

      j = jid.strip
      l = {}
      @items_lock.synchronize {
        @items.each_pair do |k, v|
          l[k] = v if k.strip == j
        end
      }
      l
    end

find_by_group(group) click to toggle source

Get items in a group

When group is nil, return ungrouped items

group

String

  Group name

result | Array of [RosterItem]

    # File lib/xmpp4r/roster/helper/roster.rb, line 300
    def find_by_group(group)
      res = []
      @items_lock.synchronize {
        @items.each_pair do |jid,item|
          res.push(item) if item.groups.include?(group)
          res.push(item) if item.groups == [] and group.nil?
        end
      }
      res
    end

get_roster() click to toggle source

    # File lib/xmpp4r/roster/helper/roster.rb, line 72
    def get_roster
      # Request the roster
      rosterget = Iq.new_rosterget
      @stream.send(rosterget)
    end

groups() click to toggle source

Groups in this Roster, sorted by name

Contains `nil` if there are ungrouped items

result

Array

  containing group names (String)

    # File lib/xmpp4r/roster/helper/roster.rb, line 283
    def groups
      res = []
      @items_lock.synchronize {
        @items.each_pair do |jid,item|
          res += item.groups
          res += [nil] if item.groups == []
        end
      }
      res.uniq.sort { |a,b| a.to_s <=> b.to_s }
    end

wait_for_roster() click to toggle source

Wait for first roster query result to arrive

    # File lib/xmpp4r/roster/helper/roster.rb, line 80
    def wait_for_roster
      @roster_wait.wait
      @roster_wait.run
    end

[Validate]

Generated with the Darkfish Rdoc Generator 2.