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") ⇒ 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
 
# 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

Instance Method Details

#accept_subscriptions=(accept_status) ⇒ Object

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



310
311
312
 
# File 'lib/xmpp4r-simple.rb', line 310

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) 


304
305
306
307
 
# File 'lib/xmpp4r-simple.rb', line 304

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.



162
163
164
165
166
167
 
# 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 ⇒ Object

Direct access to the underlying Jabber client.



321
322
323
324
 
# File 'lib/xmpp4r-simple.rb', line 321

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) 


207
208
209
210
211
 
# 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) ⇒ 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.



191
192
193
194
195
196
197
198
199
200
201
202
203
 
# 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) ⇒ 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.



114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
 
# 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) ⇒ 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.



364
365
366
367
 
# 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 ⇒ Object

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



355
356
357
 
# File 'lib/xmpp4r-simple.rb', line 355

def disconnect
  disconnect!
end

#inspect ⇒ Object

:nodoc:



94
95
96
 
# File 'lib/xmpp4r-simple.rb', line 94

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



277
278
279
 
# File 'lib/xmpp4r-simple.rb', line 277

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) 


283
284
285
 
# File 'lib/xmpp4r-simple.rb', line 283

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



245
246
247
248
249
250
251
252
253
254
255
256
257
258
 
# 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? ⇒ Boolean

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

Returns:

  • (Boolean) 


262
263
264
 
# File 'lib/xmpp4r-simple.rb', line 262

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



224
225
226
 
# File 'lib/xmpp4r-simple.rb', line 224

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) 


230
231
232
 
# File 'lib/xmpp4r-simple.rb', line 230

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

#reconnect ⇒ Object

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



348
349
350
351
 
# File 'lib/xmpp4r-simple.rb', line 348

def reconnect
  @disconnected = false
  connect!
end

#remove(*jids) ⇒ Object

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



170
171
172
173
174
 
# File 'lib/xmpp4r-simple.rb', line 170

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

#roster ⇒ Object

Direct access to the underlying Roster helper.



315
316
317
318
 
# File 'lib/xmpp4r-simple.rb', line 315

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

#send!(msg) ⇒ Object

Send a Jabber stanza over-the-wire.



327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
 
# 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) ⇒ 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! :-)



143
144
145
146
147
148
 
# 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) ⇒ Boolean

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

Returns:

  • (Boolean) 


178
179
180
181
182
 
# File 'lib/xmpp4r-simple.rb', line 178

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



298
299
300
 
# File 'lib/xmpp4r-simple.rb', line 298

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