Class: Jabber::Simple

Inherits:
Object
  • Object
show all
Includes:
DRb::DRbUndumped
Defined in:
lib/external/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!”)



89
90
91
92
93
94
95
 
# File 'lib/external/xmpp4r-simple.rb', line 89

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.



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

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) 


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

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.



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

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.



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

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) 


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

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.



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

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.



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

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.



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

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.



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

def disconnect
  disconnect!
end

#inspect ⇒ Object

:nodoc:



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

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 #Jabber::Simple.friendfriend.to_s: #presence” end



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

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) 


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

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



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

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) 


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

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 #Jabber::Simple.messagemessage.from: #Jabber::Simple.messagemessage.body” end



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

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) 


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

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

#reconnect ⇒ Object

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



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

def reconnect
  @disconnected = false
  connect!
end

#remove(*jids) ⇒ Object

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



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

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

#roster ⇒ Object

Direct access to the underlying Roster helper.



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

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

#send!(msg) ⇒ Object

Send a Jabber stanza over-the-wire.



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

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



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

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) 


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

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 #Jabber::Simple.friendfriend.to_s: #presence” end



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

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