Class: Jabber::MUC::SimpleMUCClient

Class | Jabber::MUC::SimpleMUCClient
In: | lib/xmpp4r/muc/helper/simplemucclient.rb
Parent: | MUCClient

This class attempts to implement a lot of complexity of the Multi-User Chat protocol. If you want to implement JEP0045 yourself, use Jabber::MUC::MUCClient for some minor abstraction.

Minor flexibility penalty: the on_* callbacks are no CallbackLists and may therefore only used once. A second invocation will overwrite the previous set up block.

*Hint:* the parameter time may be nil if the server didn‘t send it.

Example usage:

      my_muc = Jabber::MUC::SimpleMUCClient.new(my_client)
      my_muc.on_message { |time,nick,text|
        puts (time || Time.new).strftime('%I:%M') + " <#{nick}> #{text}"
      }
      my_muc.join(Jabber::JID.new('jdev@conference.jabber.org/XMPP4R-Bot'))

Please take a look at Jabber::MUC::MUCClient for derived methods, such as MUCClient#join, MUCClient#exit, …

### Methods

ban demote invite kick new on_join on_leave on_message on_private_message on_room_message on_self_leave on_subject promote say subject subject= unban

### Public Class methods

new(stream)

Initialize a SimpleMUCClient

stream: | [Stream] to operate on
jid: | [JID] room@component/nick
password: | [String] Optional password

[Source]

        # File lib/xmpp4r/muc/helper/simplemucclient.rb, line 40
    40:       def initialize(stream)
    41:         super
    42:
    43:         @room_message_block = nil
    44:         @message_block = nil
    45:         @private_message_block = nil
    46:         @subject_block = nil
    47:
    48:         @subject = nil
    49:
    50:         @join_block = nil
    51:         add_join_callback(999) { |pres|
    52:           # Presence time
    53:           time = nil
    54:           pres.each_element('x') { |x|
    55:             if x.kind_of?(Delay::XDelay)
    56:               time = x.stamp
    57:             end
    58:           }
    59:
    60:           # Invoke...
    61:           @join_block.call(time, pres.from.resource) if @join_block
    62:           false
    63:         }
    64:
    65:         @leave_block = nil
    66:         @self_leave_block = nil
    67:         add_leave_callback(999) { |pres|
    68:           # Presence time
    69:           time = nil
    70:           pres.each_element('x') { |x|
    71:             if x.kind_of?(Delay::XDelay)
    72:               time = x.stamp
    73:             end
    74:           }
    75:
    76:           # Invoke...
    77:           if pres.from == jid
    78:             @self_leave_block.call(time) if @self_leave_block
    79:           else
    80:             @leave_block.call(time, pres.from.resource) if @leave_block
    81:           end
    82:           false
    83:         }
    84:       end

### Public Instance methods

ban(recipients, reason)

Administratively ban one or more user jids from the room.

Will wait for response, possibly raising ServerError

Sample usage:

      my_muc.ban 'pistol@foobar.com', 'Avaunt, you cullion!'

recipients: | [Array] of, or single [String]: JIDs
reason: | [String] Ban reason

[Source]

         # File lib/xmpp4r/muc/helper/simplemucclient.rb, line 199
    199:       def ban(recipients, reason)
    200:         recipients = [recipients] unless recipients.kind_of? Array
    201:         items = recipients.collect { |recipient|
    202:           item = IqQueryMUCAdminItem.new
    203:           item.jid = recipient
    204:           item.affiliation = :outcast
    205:           item.reason = reason
    206:           item
    207:         }
    208:         send_affiliations(items)
    209:       end

demote(recipients)

Demote one or more users in the room to participant.

Will wait for response, possibly raising ServerError

Sample usage:

      my_muc.demote 'pistol'

recipients: | [Array] of, or single [String]: Nicks

[Source]

         # File lib/xmpp4r/muc/helper/simplemucclient.rb, line 260
    260:       def demote(recipients)
    261:         recipients = [recipients] unless recipients.kind_of? Array
    262:         items = recipients.collect { |recipient|
    263:           item = IqQueryMUCAdminItem.new
    264:           item.nick = recipient
    265:           item.role = :participant
    266:           item
    267:         }
    268:         send_affiliations(items)
    269:       end

invite(recipients)

Request the MUC to invite users to this room

Sample usage:

      my_muc.invite( {'wiccarocks@shakespeare.lit/laptop' => 'This coven needs both wiccarocks and hag66.',
                      'hag66@shakespeare.lit' => 'This coven needs both hag66 and wiccarocks.'} )

recipients: | [Hash] of [JID] => [String] Reason

[Source]

         # File lib/xmpp4r/muc/helper/simplemucclient.rb, line 157
    157:       def invite(recipients)
    158:         msg = Message.new
    159:         x = msg.add(XMUCUser.new)
    160:         recipients.each { |jid,reason|
    161:           x.add(XMUCUserInvite.new(jid, reason))
    162:         }
    163:         send(msg)
    164:       end

kick(recipients, reason)

Administratively remove one or more users from the room.

Will wait for response, possibly raising ServerError

Sample usage:

      my_muc.kick 'pistol', 'Avaunt, you cullion!'
      my_muc.kick(['Bill', 'Linus'], 'Stop flaming')

recipients: | [Array] of, or single [String]: Nicks
reason: | [String] Kick reason

[Source]

         # File lib/xmpp4r/muc/helper/simplemucclient.rb, line 177
    177:       def kick(recipients, reason)
    178:         recipients = [recipients] unless recipients.kind_of? Array
    179:         items = recipients.collect { |recipient|
    180:           item = IqQueryMUCAdminItem.new
    181:           item.nick = recipient
    182:           item.role = :none
    183:           item.reason = reason
    184:           item
    185:         }
    186:         send_affiliations(items)
    187:       end

on_join(&block)

Block to be called when somebody enters the room

If there is a non-nil time passed to the block, chances are great that this is initial presence from a participant after you have joined the room.

block: | Takes two arguments: time, nickname

[Source]

         # File lib/xmpp4r/muc/helper/simplemucclient.rb, line 311
    311:       def on_join(&block)
    312:         @join_block = block
    313:       end

on_leave(&block)

Block to be called when somebody leaves the room

block: | Takes two arguments: time, nickname

[Source]

         # File lib/xmpp4r/muc/helper/simplemucclient.rb, line 318
    318:       def on_leave(&block)
    319:         @leave_block = block
    320:       end

on_message(&block)

Block to be invoked when a message from a participant to the whole room arrives

block: | Takes three arguments: time, sender nickname, text

[Source]

         # File lib/xmpp4r/muc/helper/simplemucclient.rb, line 285
    285:       def on_message(&block)
    286:         @message_block = block
    287:       end

on_private_message(&block)

Block to be invoked when a private message from a participant to you arrives.

block: | Takes three arguments: time, sender nickname, text

[Source]

         # File lib/xmpp4r/muc/helper/simplemucclient.rb, line 293
    293:       def on_private_message(&block)
    294:         @private_message_block = block
    295:       end

on_room_message(&block)

Block to be invoked when a message from the room arrives

Example:

      Astro has joined this session

block: | Takes two arguments: time, text

[Source]

         # File lib/xmpp4r/muc/helper/simplemucclient.rb, line 277
    277:       def on_room_message(&block)
    278:         @room_message_block = block
    279:       end

on_self_leave(&block)

Block to be called when you leave the room

Deactivation occurs afterwards.

block: | Takes one argument: time

[Source]

         # File lib/xmpp4r/muc/helper/simplemucclient.rb, line 327
    327:       def on_self_leave(&block)
    328:         @self_leave_block = block
    329:       end

on_subject(&block)

Block to be invoked when somebody sets a new room subject

block: | Takes three arguments: time, nickname, new subject

[Source]

         # File lib/xmpp4r/muc/helper/simplemucclient.rb, line 300
    300:       def on_subject(&block)
    301:         @subject_block = block
    302:       end

promote(recipients)

Promote one or more users in the room to moderator.

Will wait for response, possibly raising ServerError

Sample usage:

      my_muc.promote 'pistol'

recipients: | [Array] of, or single [String]: Nicks

[Source]

         # File lib/xmpp4r/muc/helper/simplemucclient.rb, line 240
    240:       def promote(recipients)
    241:         recipients = [recipients] unless recipients.kind_of? Array
    242:         items = recipients.collect { |recipient|
    243:           item = IqQueryMUCAdminItem.new
    244:           item.nick = recipient
    245:           item.role = :moderator
    246:           item
    247:         }
    248:         send_affiliations(items)
    249:       end

say(text, to=nil)

Send a simple text message

text: | [String] Message body
to: | [String] Optional nick if directed to specific user

[Source]

         # File lib/xmpp4r/muc/helper/simplemucclient.rb, line 146
    146:       def say(text, to=nil)
    147:         send(Message.new(nil, text), to)
    148:       end

subject()

Room subject/topic

result: | [String] The subject

[Source]

         # File lib/xmpp4r/muc/helper/simplemucclient.rb, line 126
    126:       def subject
    127:         @subject
    128:       end

subject=(s)

Change the room‘s subject/topic

This will not be reflected by SimpleMUCClient#subject immediately, wait for SimpleMUCClient#on_subject

s: | [String] New subject

[Source]

         # File lib/xmpp4r/muc/helper/simplemucclient.rb, line 136
    136:       def subject=(s)
    137:         msg = Message.new
    138:         msg.subject = s
    139:         send(msg)
    140:       end

unban(recipients)

Unban one or more user jids for the room.

Will wait for response, possibly raising ServerError

Sample usage:

      my_muc.unban 'pistol@foobar.com'

recipients: | [Array] of, or single [String]: JIDs

[Source]

         # File lib/xmpp4r/muc/helper/simplemucclient.rb, line 220
    220:       def unban(recipients)
    221:         recipients = [recipients] unless recipients.kind_of? Array
    222:         items = recipients.collect { |recipient|
    223:           item = IqQueryMUCAdminItem.new
    224:           item.jid = recipient
    225:           item.affiliation = :none
    226:           item
    227:         }
    228:         send_affiliations(items)
    229:       end

[Validate]