Parent

Included Modules

Files

Class/Module Index [+]

Quicksearch

Jabber::Simple

Public Class Methods

new(jid, password, status = nil, status_message = "Available") click to toggle source

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 = Jabber::Simple.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

Public Instance Methods

accept_subscriptions=(accept_status) click to toggle source

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
accept_subscriptions?() click to toggle source

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
add(*jids) click to toggle source

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 Jabber::Simple#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
client() click to toggle source

Direct access to the underlying Jabber client.

# File lib/xmpp4r-simple.rb, line 321
def client
  connect!() unless connected?
  @client
end
connected?() click to toggle source

Returns true if the Jabber client is connected to the Jabber server, false otherwise.

# File lib/xmpp4r-simple.rb, line 207
def connected?
  @client ||= nil
  connected = @client.respond_to?(:is_connected?) && @client.is_connected?
  return connected
end
contacts(*contacts, &block) click to toggle source

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
deliver(jid, message, type=:chat) click to toggle source

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 Jabber::Simple#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
deliver_deferred(jid, message, type) click to toggle source

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
disconnect() click to toggle source

Use this to force the client to disconnect and not automatically reconnect.

# File lib/xmpp4r-simple.rb, line 355
def disconnect
  disconnect!
end
new_subscriptions(&block) click to toggle source

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
new_subscriptions?() click to toggle source

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
presence_updates(&block) click to toggle source

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
presence_updates?() click to toggle source

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
received_messages(&block) click to toggle source

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
received_messages?() click to toggle source

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
reconnect() click to toggle source

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(*jids) click to toggle source

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
roster() click to toggle source

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!(msg) click to toggle source

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
status(presence, message) click to toggle source

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
subscribed_to?(jid) click to toggle source

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
subscription_requests(&block) click to toggle source

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

[Validate]

Generated with the Darkfish Rdoc Generator 2.