Class: Jabber::Simple

Inherits:
Object
  • Object
show all
Includes:
DRb::DRbUndumped
Defined in:
lib/xmpp4r-simple.rb

Instance Method Summary collapse

Constructor Details

#initialize(jid, password, status = nil, status_message = "Available", host = nil, port = 5222) ⇒ Simple

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(“[email protected]”, “password”, “Chat with me - Please!”)



86
87
88
89
90
91
92
93
94
 
# File 'lib/xmpp4r-simple.rb', line 86

def initialize(jid, password, status = nil, status_message = "Available", host = nil, port=5222)
  @jid = jid
  @password = password
  @host = host
  @port = port
  @disconnected = false
  status(status, status_message)
  start_deferred_delivery_thread
end

Instance Method Details

#accept_subscriptions=(accept_status) ⇒ Object

Change whether or not subscriptions (friend requests) are automatically accepted.



312
313
314
 
# File 'lib/xmpp4r-simple.rb', line 312

def accept_subscriptions=(accept_status)
  @accept_subscriptions = accept_status
end

#accept_subscriptions? ⇒ Boolean

Returns true if auto-accept subscriptions (friend requests) is enabled (default), false otherwise.

Returns:

  • (Boolean) 


306
307
308
309
 
# File 'lib/xmpp4r-simple.rb', line 306

def accept_subscriptions?
  @accept_subscriptions = true if @accept_subscriptions.nil?
  @accept_subscriptions
end

#add(*jids) ⇒ Object

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("[email protected]")

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.



164
165
166
167
168
169
 
# File 'lib/xmpp4r-simple.rb', line 164

def add(*jids)
  contacts(*jids) do |friend|
    next if subscribed_to? friend
    friend.ask_for_authorization!
  end
end

#client ⇒ Object

Direct access to the underlying Jabber client.



323
324
325
326
 
# File 'lib/xmpp4r-simple.rb', line 323

def client
  connect!() unless connected?
  @client
end

#connected? ⇒ Boolean

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

Returns:

  • (Boolean) 


209
210
211
212
213
 
# File 'lib/xmpp4r-simple.rb', line 209

def connected?
  @client ||= nil
  connected = @client.respond_to?(:is_connected?) && @client.is_connected?
  return connected
end

#contacts(*contacts, &block) ⇒ Object

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.



193
194
195
196
197
198
199
200
201
202
203
204
205
 
# File 'lib/xmpp4r-simple.rb', line 193

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) ⇒ Object

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.



116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
 
# File 'lib/xmpp4r-simple.rb', line 116

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) ⇒ Object

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.



366
367
368
369
 
# File 'lib/xmpp4r-simple.rb', line 366

def deliver_deferred(jid, message, type)
  msg = {:to => jid, :message => message, :type => type}
  queue(:pending_messages) << [msg]
end

#disconnect ⇒ Object

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



357
358
359
 
# File 'lib/xmpp4r-simple.rb', line 357

def disconnect
  disconnect!
end

#inspect ⇒ Object

:nodoc:



96
97
98
 
# File 'lib/xmpp4r-simple.rb', line 96

def inspect #:nodoc:
  "Jabber::Simple #{@jid}"
end

#new_subscriptions(&block) ⇒ Object

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



279
280
281
 
# File 'lib/xmpp4r-simple.rb', line 279

def new_subscriptions(&block)
  dequeue(:new_subscriptions, &block)
end

#new_subscriptions? ⇒ Boolean

Returns true if there are unprocessed presence updates waiting in the queue, false otherwise.

Returns:

  • (Boolean) 


285
286
287
 
# File 'lib/xmpp4r-simple.rb', line 285

def new_subscriptions?
  !queue(:new_subscriptions).empty?
end

#presence_updates(&block) ⇒ Object

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



247
248
249
250
251
252
253
254
255
256
257
258
259
260
 
# File 'lib/xmpp4r-simple.rb', line 247

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? ⇒ Boolean

Returns true if there are unprocessed presence updates waiting in the queue, false otherwise.

Returns:

  • (Boolean) 


264
265
266
 
# File 'lib/xmpp4r-simple.rb', line 264

def presence_updates?
  !queue(:presence_updates).empty?
end

#received_messages(&block) ⇒ Object

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



226
227
228
 
# File 'lib/xmpp4r-simple.rb', line 226

def received_messages(&block)
  dequeue(:received_messages, &block)
end

#received_messages? ⇒ Boolean

Returns true if there are unprocessed received messages waiting in the queue, false otherwise.

Returns:

  • (Boolean) 


232
233
234
 
# File 'lib/xmpp4r-simple.rb', line 232

def received_messages?
  !queue(:received_messages).empty?
end

#reconnect ⇒ Object

Use this to force the client to reconnect after a force_disconnect.



350
351
352
353
 
# File 'lib/xmpp4r-simple.rb', line 350

def reconnect
  @disconnected = false
  connect!
end

#remove(*jids) ⇒ Object

Remove the jabber users specified by jids from the contact list.



172
173
174
175
176
 
# File 'lib/xmpp4r-simple.rb', line 172

def remove(*jids)
  contacts(*jids) do |unfriend|
    unfriend.unsubscribe!
  end
end

#roster ⇒ Object

Direct access to the underlying Roster helper.



317
318
319
320
 
# File 'lib/xmpp4r-simple.rb', line 317

def roster
  return @roster if @roster
  self.roster = Roster::Helper.new(client)
end

#send!(msg) ⇒ Object

Send a Jabber stanza over-the-wire.



329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
 
# File 'lib/xmpp4r-simple.rb', line 329

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) ⇒ Object

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! :-)



145
146
147
148
149
150
 
# File 'lib/xmpp4r-simple.rb', line 145

def status(presence, message)
  @presence = presence
  @status_message = message
  stat_msg = Presence.new(@presence, @status_message)
  send!(stat_msg)
end

#subscribed_to?(jid) ⇒ Boolean

Returns true if this Jabber account is subscribed to status updates for the jabber user jid, false otherwise.

Returns:

  • (Boolean) 


180
181
182
183
184
 
# File 'lib/xmpp4r-simple.rb', line 180

def subscribed_to?(jid)
  contacts(jid) do |contact|
    return contact.subscribed?
  end
end

#subscription_requests(&block) ⇒ Object

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



300
301
302
 
# File 'lib/xmpp4r-simple.rb', line 300

def subscription_requests(&block)
  dequeue(:subscription_requests, &block)
end