Create a new Jabber::Simple client. You will be automatically connected to the Jabber server and your status message will be set to the string passed in as the status_message argument.
jabber = ::new("me@example.com", "password", "Chat with me - Please!")
# File lib/xmpp4r-simple.rb, line 86 def initialize(jid, password, status = nil, status_message = "Available") @jid = jid @password = password @disconnected = false status(status, status_message) start_deferred_delivery_thread end
Change whether or not subscriptions (friend requests) are automatically accepted.
# File lib/xmpp4r-simple.rb, line 310 def accept_subscriptions=(accept_status) @accept_subscriptions = accept_status end
Returns true if auto-accept subscriptions (friend requests) is enabled (default), false otherwise.
# File lib/xmpp4r-simple.rb, line 304 def accept_subscriptions? @accept_subscriptions = true if @accept_subscriptions.nil? @accept_subscriptions end
Ask the users specified by jids for authorization (i.e., ask them to add you to their contact list). If you are already in the user's contact list, add() will not attempt to re-request authorization. In order to force re-authorization, first remove() the user, then re-add them.
Example usage:
jabber_simple.add("friend@friendosaurus.com")
Because the authorization process might take a few seconds, or might never happen depending on when (and if) the user accepts your request, results are placed in the #new_subscriptions queue.
# File lib/xmpp4r-simple.rb, line 162 def add(*jids) contacts(*jids) do |friend| next if subscribed_to? friend friend.ask_for_authorization! end end
Direct access to the underlying Jabber client.
# File lib/xmpp4r-simple.rb, line 321 def client connect!() unless connected? @client end
If contacts is a single contact, returns a Jabber::Contact object representing that user; if contacts is an array, returns an array of Jabber::Contact objects.
When called with a block, contacts will yield each Jabber::Contact object in turn. This is mainly used internally, but exposed as an utility function.
# File lib/xmpp4r-simple.rb, line 191 def contacts(*contacts, &block) @contacts ||= {} contakts = [] contacts.each do |contact| jid = contact.to_s unless @contacts[jid] @contacts[jid] = contact.respond_to?(:ask_for_authorization!) ? contact : Contact.new(self, contact) end yield @contacts[jid] if block_given? contakts << @contacts[jid] end contakts.size > 1 ? contakts : contakts.first end
Send a message to jabber user jid.
Valid message types are:
* :normal (default): a normal message. * :chat: a one-to-one chat message. * :groupchat: a group-chat message. * :headline: a "headline" message. * :error: an error message.
If the recipient is not in your contacts list, the message will be queued for later delivery, and the Contact will be automatically asked for authorization (see #add).
message should be a string or a valid Jabber::Message object. In either case, the message recipient will be set to jid.
# File lib/xmpp4r-simple.rb, line 114 def deliver(jid, message, type=:chat) contacts(jid) do |friend| unless subscribed_to? friend add(friend.jid) return deliver_deferred(friend.jid, message, type) end if message.kind_of?(Jabber::Message) msg = message msg.to = friend.jid else msg = Message.new(friend.jid) msg.type = type msg.body = message end send!(msg) end end
Queue messages for delivery once a user has accepted our authorization request. Works in conjunction with the deferred delivery thread.
You can use this method if you want to manually add friends and still have the message queued for later delivery.
# File lib/xmpp4r-simple.rb, line 364 def deliver_deferred(jid, message, type) msg = {:to => jid, :message => message, :type => type} queue(:pending_messages) << [msg] end
Use this to force the client to disconnect and not automatically reconnect.
# File lib/xmpp4r-simple.rb, line 355 def disconnect disconnect! end
Returns an array of subscription notifications received since the last time #new_subscriptions was called. Passing a block will yield each update in turn, allowing you to break part-way through processing (especially useful when your subscription handling code is not thread-safe (e.g., ActiveRecord).
e.g.:
jabber.new_subscriptions do |friend, presence| puts "Received presence update from #{friend.to_s}: #{presence}" end
# File lib/xmpp4r-simple.rb, line 277 def new_subscriptions(&block) dequeue(:new_subscriptions, &block) end
Returns true if there are unprocessed presence updates waiting in the queue, false otherwise.
# File lib/xmpp4r-simple.rb, line 283 def new_subscriptions? !queue(:new_subscriptions).empty? end
Returns an array of presence updates received since the last time #presence_updates was called. Passing a block will yield each update in turn, allowing you to break part-way through processing (especially useful when your presence handling code is not thread-safe (e.g., ActiveRecord).
e.g.:
jabber.presence_updates do |friend, new_presence| puts "Received presence update from #{friend}: #{new_presence}" end
# File lib/xmpp4r-simple.rb, line 245 def presence_updates(&block) updates = [] @presence_mutex.synchronize do dequeue(:presence_updates) do |friend| presence = @presence_updates[friend] next unless presence new_update = [friend, presence[0], presence[1]] yield new_update if block_given? updates << new_update @presence_updates.delete(friend) end end return updates end
Returns true if there are unprocessed presence updates waiting in the queue, false otherwise.
# File lib/xmpp4r-simple.rb, line 262 def presence_updates? !queue(:presence_updates).empty? end
Returns an array of messages received since the last time #received_messages was called. Passing a block will yield each message in turn, allowing you to break part-way through processing (especially useful when your message handling code is not thread-safe (e.g., ActiveRecord).
e.g.:
jabber.received_messages do |message| puts "Received message from #{message.from}: #{message.body}" end
# File lib/xmpp4r-simple.rb, line 224 def received_messages(&block) dequeue(:received_messages, &block) end
Returns true if there are unprocessed received messages waiting in the queue, false otherwise.
# File lib/xmpp4r-simple.rb, line 230 def received_messages? !queue(:received_messages).empty? end
Use this to force the client to reconnect after a force_disconnect.
# File lib/xmpp4r-simple.rb, line 348 def reconnect @disconnected = false connect! end
Remove the jabber users specified by jids from the contact list.
# File lib/xmpp4r-simple.rb, line 170 def remove(*jids) contacts(*jids) do |unfriend| unfriend.unsubscribe! end end
Direct access to the underlying Roster helper.
# File lib/xmpp4r-simple.rb, line 315 def roster return @roster if @roster self.roster = Roster::Helper.new(client) end
Send a Jabber stanza over-the-wire.
# File lib/xmpp4r-simple.rb, line 327 def send!(msg) attempts = 0 begin attempts += 1 client.send(msg) rescue Errno::EPIPE, IOError => e sleep 1 disconnect reconnect retry unless attempts > 3 raise e rescue Errno::ECONNRESET => e sleep (attempts^2) * 60 + 60 disconnect reconnect retry unless attempts > 3 raise e end end
Set your presence, with a message.
Available values for presence are:
* nil: online. * :chat: free for chat. * :away: away from the computer. * :dnd: do not disturb. * :xa: extended away.
It's not possible to set an offline status - to do that, disconnect! :-)
# File lib/xmpp4r-simple.rb, line 143 def status(presence, message) @presence = presence @status_message = message stat_msg = Presence.new(@presence, @status_message) send!(stat_msg) end
Returns true if this Jabber account is subscribed to status updates for the jabber user jid, false otherwise.
# File lib/xmpp4r-simple.rb, line 178 def subscribed_to?(jid) contacts(jid) do |contact| return contact.subscribed? end end
Returns an array of subscription notifications received since the last time #subscription_requests was called. Passing a block will yield each update in turn, allowing you to break part-way through processing (especially useful when your subscription handling code is not thread-safe (e.g., ActiveRecord).
e.g.:
jabber.subscription_requests do |friend, presence| puts "Received presence update from #{friend.to_s}: #{presence}" end
# File lib/xmpp4r-simple.rb, line 298 def subscription_requests(&block) dequeue(:subscription_requests, &block) end