Class: MatrixSdk::Room

Inherits:
Object show all
Extended by:
Extensions
Includes:
Logging
Defined in:
lib/matrix_sdk/room.rb

Overview

A class for tracking the information about a room on Matrix

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from Extensions

ignore_inspect

Methods included from Logging

#logger, #logger=

Constructor Details

#initialize(client, room_id, data = {}) ⇒ Room

Returns a new instance of Room.



61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
# File 'lib/matrix_sdk/room.rb', line 61

def initialize(client, room_id, data = {})
  event_initialize
  @client = client
  @id = room_id.to_s

  @name = nil
  @topic = nil
  @canonical_alias = nil
  @aliases = []
  @join_rule = nil
  @guest_access = nil
  @world_readable = nil
  @members = []
  @events = []
  @members_loaded = false
  @event_history_limit = 10
  @avatar_url = nil

  @prev_batch = nil

  data.each do |k, v|
    instance_variable_set("@#{k}", v) if instance_variable_defined? "@#{k}"
  end

  @name_checked = Time.new(0)

  logger.debug "Created room #{room_id}"
end

Instance Attribute Details

#aliasesArray(String) (readonly)

Returns a list of user-set aliases for the room.

Returns:

  • (Array(String))

    a list of user-set aliases for the room

See Also:



43
# File 'lib/matrix_sdk/room.rb', line 43

attr_reader :id, :client, :topic, :aliases, :members, :events

#canonical_aliasString?

Returns the canonical alias of the room.

Returns:

  • (String, nil)

    the canonical alias of the room



15
16
17
# File 'lib/matrix_sdk/room.rb', line 15

def canonical_alias
  @canonical_alias
end

#clientClient (readonly)

Returns the client for the room.

Returns:

  • (Client)

    the client for the room



43
# File 'lib/matrix_sdk/room.rb', line 43

attr_reader :id, :client, :topic, :aliases, :members, :events

#event_history_limitFixnum

Returns the limit of events to keep in the event log.

Returns:

  • (Fixnum)

    the limit of events to keep in the event log



15
# File 'lib/matrix_sdk/room.rb', line 15

attr_accessor :canonical_alias, :event_history_limit

#eventsObject (readonly)

Returns the value of attribute events.



43
# File 'lib/matrix_sdk/room.rb', line 43

attr_reader :id, :client, :topic, :aliases, :members, :events

#guest_access:can_join, :forbidden

Returns the guest access for the room - either :can_join or :forbidden.

Returns:

  • (:can_join, :forbidden)

    the guest access for the room - either :can_join or :forbidden



43
# File 'lib/matrix_sdk/room.rb', line 43

attr_reader :id, :client, :topic, :aliases, :members, :events

#idString (readonly) Also known as: room_id

Returns the internal ID of the room.

Returns:

  • (String)

    the internal ID of the room



43
44
45
# File 'lib/matrix_sdk/room.rb', line 43

def id
  @id
end

#join_rule:invite, :public

Returns the join rule for the room - either :invite or :public.

Returns:

  • (:invite, :public)

    the join rule for the room - either :invite or :public



43
# File 'lib/matrix_sdk/room.rb', line 43

attr_reader :id, :client, :topic, :aliases, :members, :events

#membersArray(User) (readonly)

Returns the members of the room.

Returns:

  • (Array(User))

    the members of the room

See Also:

  • reload_members!


43
# File 'lib/matrix_sdk/room.rb', line 43

attr_reader :id, :client, :topic, :aliases, :members, :events

#nameString?

Returns the user-provided name of the room.

Returns:

  • (String, nil)

    the user-provided name of the room

See Also:



43
# File 'lib/matrix_sdk/room.rb', line 43

attr_reader :id, :client, :topic, :aliases, :members, :events

#on_ephemeral_eventEventHandlerArray (readonly)

Returns The list of event handlers for only ephemeral events.

Returns:



51
# File 'lib/matrix_sdk/room.rb', line 51

events :event, :state_event, :ephemeral_event

#on_eventEventHandlerArray (readonly)

Returns The list of event handlers for all events.

Returns:



51
# File 'lib/matrix_sdk/room.rb', line 51

events :event, :state_event, :ephemeral_event

#on_state_eventEventHandlerArray (readonly)

Returns The list of event handlers for only state events.

Returns:



51
# File 'lib/matrix_sdk/room.rb', line 51

events :event, :state_event, :ephemeral_event

#topicString?

Returns the user-provided topic of the room.

Returns:

  • (String, nil)

    the user-provided topic of the room

See Also:



43
# File 'lib/matrix_sdk/room.rb', line 43

attr_reader :id, :client, :topic, :aliases, :members, :events

Instance Method Details

#add_alias(room_alias) ⇒ Boolean

Add an alias to the room

Returns:

  • (Boolean)

    if the addition was successful or not



472
473
474
475
476
# File 'lib/matrix_sdk/room.rb', line 472

def add_alias(room_alias)
  client.api.set_room_alias(id, room_alias)
  @aliases << room_alias
  true
end

#add_tag(tag, **data) ⇒ Object

Add a tag to the room

Parameters:

  • tag (String)

    The tag to add

  • data (Hash)

    The data to assign to the tag



415
416
417
418
# File 'lib/matrix_sdk/room.rb', line 415

def add_tag(tag, **data)
  client.api.add_user_tag(client.mxid, id, tag, data)
  true
end

#allow_guests=(allow_guests) ⇒ Object



511
512
513
514
# File 'lib/matrix_sdk/room.rb', line 511

def allow_guests=(allow_guests)
  self.guest_access = (allow_guests ? :can_join : :forbidden)
  @guest_access == :can_join
end

#avatar_urlObject

Gets the avatar url of the room - if any



142
143
144
145
146
147
# File 'lib/matrix_sdk/room.rb', line 142

def avatar_url
  @avatar_url ||= client.api.get_room_avatar(id).url
rescue MatrixNotFoundError
  # No avatar has been set
  nil
end

#avatar_url=(avatar_url) ⇒ Object

Raises:

  • (ArgumentError)


521
522
523
524
525
526
527
# File 'lib/matrix_sdk/room.rb', line 521

def avatar_url=(avatar_url)
  avatar_url = URI(avatar_url) unless avatar_url.is_a? URI
  raise ArgumentError, 'Must be a valid MXC URL' unless avatar_url.is_a? URI::MATRIX

  client.api.set_room_avatar(id, avatar_url)
  @avatar_url = avatar_url
end

#backfill_messages(reverse = false, limit = 10) ⇒ Object

Note:

This will trigger the ‘on_event` events as messages are added

Backfills messages into the room history

Parameters:

  • reverse (Boolean) (defaults to: false)

    whether to fill messages in reverse or not

  • limit (Integer) (defaults to: 10)

    the maximum number of messages to backfill



285
286
287
288
289
290
291
292
293
294
# File 'lib/matrix_sdk/room.rb', line 285

def backfill_messages(reverse = false, limit = 10)
  data = client.api.get_room_messages(id, @prev_batch, direction: :b, limit: limit)

  events = data[:chunk]
  events.reverse! unless reverse
  events.each do |ev|
    put_event(ev)
  end
  true
end

#ban_user(user_id, reason = '') ⇒ Boolean

Bans a user from the room

Parameters:

  • user_id (String, User)

    the MXID of the user

  • reason (String) (defaults to: '')

    the reason for the ban

Returns:

  • (Boolean)

    wether the action succeeded



323
324
325
326
327
# File 'lib/matrix_sdk/room.rb', line 323

def ban_user(user_id, reason = '')
  user_id = user_id.id if user_id.is_a? MatrixSdk::User
  client.api.ban_user(id, user_id, reason: reason)
  true
end

#display_nameString

Note:

This method will populate the #members list if it has to fall back to the member name generation.

Gets a human-readable name for the room

This will return #name or #canonical_alias if they’ve been set, otherwise it will query the API for members and generate a string from a subset of their names.

Returns:

  • (String)

    a human-readable name for the room



103
104
105
106
107
108
109
110
111
112
113
114
115
116
# File 'lib/matrix_sdk/room.rb', line 103

def display_name
  return name if name
  return canonical_alias if canonical_alias

  members = joined_members
            .reject { |m| m.user_id == client.mxid }
            .map(&:display_name)

  return members.first if members.one?
  return "#{members.first} and #{members.last}" if members.count == 2
  return "#{members.first} and #{members.count - 1} others" if members.count > 2

  'Empty Room'
end

#get_account_data(type) ⇒ Hash

Retrieves a custom entry from the room-specific account data

Parameters:

  • type (String)

    the data type to retrieve

Returns:

  • (Hash)

    the data that was stored under the given type



349
350
351
# File 'lib/matrix_sdk/room.rb', line 349

def (type)
  client.api.(client.mxid, id, type)
end

#guest_access?Boolean

Checks if guest_access is set to :can_join

Returns:

  • (Boolean)


158
159
160
# File 'lib/matrix_sdk/room.rb', line 158

def guest_access?
  guest_access == :can_join
end

#inspectString

An inspect method that skips a handful of instance variables to avoid flooding the terminal with debug data.

Returns:

  • (String)

    a regular inspect string without the data for some variables



56
57
# File 'lib/matrix_sdk/room.rb', line 56

ignore_inspect :client, :members, :events, :prev_batch, :logger,
:on_event, :on_state_event, :on_ephemeral_event

#invite_only=(invite_only) ⇒ Object



501
502
503
504
# File 'lib/matrix_sdk/room.rb', line 501

def invite_only=(invite_only)
  self.join_rule = invite_only ? :invite : :public
  @join_rule == :invite
end

#invite_only?Boolean

Checks if join_rule is set to :invite

Returns:

  • (Boolean)


163
164
165
# File 'lib/matrix_sdk/room.rb', line 163

def invite_only?
  join_rule == :invite
end

#invite_user(user_id) ⇒ Boolean

Invites a user into the room

Parameters:

  • user_id (String, User)

    the MXID of the user

Returns:

  • (Boolean)

    wether the action succeeded



303
304
305
306
307
# File 'lib/matrix_sdk/room.rb', line 303

def invite_user(user_id)
  user_id = user_id.id if user_id.is_a? MatrixSdk::User
  client.api.invite_user(id, user_id)
  true
end

#joined_membersObject

Populates and returns the #members array



119
120
121
122
123
124
125
126
127
128
129
# File 'lib/matrix_sdk/room.rb', line 119

def joined_members
  return members if @members_loaded && !members.empty?

  client.api.get_room_members(id)[:chunk].each do |chunk|
    next unless chunk [:content][:membership] == 'join'

    ensure_member(User.new(client, chunk[:state_key], display_name: chunk[:content].fetch(:displayname, nil)))
  end
  @members_loaded = true
  members
end

#kick_user(user_id, reason = '') ⇒ Boolean

Kicks a user from the room

Parameters:

  • user_id (String, User)

    the MXID of the user

  • reason (String) (defaults to: '')

    the reason for the kick

Returns:

  • (Boolean)

    wether the action succeeded



313
314
315
316
317
# File 'lib/matrix_sdk/room.rb', line 313

def kick_user(user_id, reason = '')
  user_id = user_id.id if user_id.is_a? MatrixSdk::User
  client.api.kick_user(id, user_id, reason: reason)
  true
end

#leaveBoolean

Requests to be removed from the room

Returns:

  • (Boolean)

    wether the request succeeded



340
341
342
343
344
# File 'lib/matrix_sdk/room.rb', line 340

def leave
  client.api.leave_room(id)
  client.instance_variable_get(:@rooms).delete id
  true
end

#modify_required_power_levels(events = nil, params = {}) ⇒ Boolean

Modifies the required power levels for actions in the room

Parameters:

  • events (Hash) (defaults to: nil)

    the event-specific power levels to change

  • params (Hash) (defaults to: {})

    other power-level params to change

Returns:

  • (Boolean)

    if the change was successful



553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
# File 'lib/matrix_sdk/room.rb', line 553

def modify_required_power_levels(events = nil, params = {})
  return false if events.nil? && (params.nil? || params.empty?)

  data = client.api.get_power_levels(id)
  data.merge!(params)
  data.delete_if { |_k, v| v.nil? }

  if events
    data[:events] = {} unless data.key? :events
    data[:events].merge!(events)
    data[:events].delete_if { |_k, v| v.nil? }
  end

  client.api.set_power_levels(id, data)
  true
end

#modify_user_power_levels(users = nil, users_default = nil) ⇒ Boolean

Modifies the power levels of the room

Parameters:

  • users (Hash) (defaults to: nil)

    the user-specific power levels to set or remove

  • users_default (Hash) (defaults to: nil)

    the default user power levels to set

Returns:

  • (Boolean)

    if the change was successful



533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
# File 'lib/matrix_sdk/room.rb', line 533

def modify_user_power_levels(users = nil, users_default = nil)
  return false if users.nil? && users_default.nil?

  data = client.api.get_power_levels(id)
  data[:users_default] = users_default unless users_default.nil?

  if users
    data[:users] = {} unless data.key? :users
    data[:users].merge!(users)
    data[:users].delete_if { |_k, v| v.nil? }
  end

  client.api.set_power_levels(id, data)
  true
end

#redact_message(event_id, reason = nil) ⇒ Object

Redacts a message from the room

Parameters:

  • event_id (String)

    the ID of the event to redact

  • reason (String, nil) (defaults to: nil)

    the reason for the redaction



276
277
278
279
# File 'lib/matrix_sdk/room.rb', line 276

def redact_message(event_id, reason = nil)
  client.api.redact_event(id, event_id, reason: reason)
  true
end

#reload!Object Also known as: refresh!

State updates



424
425
426
427
428
429
# File 'lib/matrix_sdk/room.rb', line 424

def reload!
  reload_name!
  reload_topic!
  reload_aliases!
  true
end

#reload_aliases!Boolean Also known as: refresh_aliases!

Note:

The list of aliases is not sorted, ordering changes will result in alias list updates.

Reloads the list of aliases by an API query

Returns:

  • (Boolean)

    if the alias list was updated or not



482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
# File 'lib/matrix_sdk/room.rb', line 482

def reload_aliases!
  begin
    new_aliases = client.api.get_room_aliases(id).aliases
  rescue MatrixNotFoundError
    data = client.api.get_room_state(id)
    new_aliases = data.select { |chunk| chunk[:type] == 'm.room.aliases' && chunk.key?(:content) && chunk[:content].key?(:aliases) }
                      .map { |chunk| chunk[:content][:aliases] }
                      .flatten
                      .compact
  end

  return false if new_aliases.nil?

  changed = new_aliases != aliases
  @aliases = new_aliases if changed
  changed
end

#reload_name!Boolean Also known as: refresh_name!

Reloads the name of the room

Returns:

  • (Boolean)

    if the name was changed or not



439
440
441
442
443
444
445
446
447
448
# File 'lib/matrix_sdk/room.rb', line 439

def reload_name!
  data = begin
           client.api.get_room_name(id)
         rescue MatrixNotFoundError
           nil
         end
  changed = data[:name] != @name
  @name = data[:name] if changed
  changed
end

#reload_topic!Boolean Also known as: refresh_topic!

Reloads the topic of the room

Returns:

  • (Boolean)

    if the topic was changed or not



458
459
460
461
462
463
464
465
466
467
# File 'lib/matrix_sdk/room.rb', line 458

def reload_topic!
  data = begin
           client.api.get_room_topic(id)
         rescue MatrixNotFoundError
           nil
         end
  changed = data[:topic] != @topic
  @topic = data[:topic] if changed
  changed
end

#remove_tag(tag) ⇒ Object

Remove a tag from the room

Parameters:

  • tag (String)

    The tag to remove



407
408
409
410
# File 'lib/matrix_sdk/room.rb', line 407

def remove_tag(tag)
  client.api.remove_user_tag(client.mxid, id, tag)
  true
end

#send_audio(url, name, audio_info = {}) ⇒ Object

Note:

The URLs should all be of the ‘mxc://’ schema

Sends a link to an audio clip to the room

Parameters:

  • url (String, URI)

    the URL to the audio clip

  • name (String)

    the name of the audio clip

  • audio_info (Hash) (defaults to: {})

    extra information about the audio clip

Options Hash (audio_info):

  • :duration (Integer)

    the duration of the audio clip in milliseconds

  • :mimetype (String)

    the MIME type of the audio clip

  • :size (Integer)

    the size of the audio clip in bytes



269
270
271
# File 'lib/matrix_sdk/room.rb', line 269

def send_audio(url, name, audio_info = {})
  client.api.send_content(id, url, name, 'm.audio', extra_information: audio_info)
end

#send_emote(text) ⇒ Object

Sends an emote (/me) message to the room

Parameters:

  • text (String)

    the emote to send



197
198
199
# File 'lib/matrix_sdk/room.rb', line 197

def send_emote(text)
  client.api.send_emote(id, text)
end

#send_file(url, name, file_info = {}) ⇒ Object

Note:

The URLs should all be of the ‘mxc://’ schema

Sends a link to a generic file to the room

Parameters:

  • url (String, URI)

    the URL to the file

  • name (String)

    the name of the file

  • file_info (Hash) (defaults to: {})

    extra information about the file

Options Hash (file_info):

  • :mimetype (String)

    the MIME type of the file

  • :size (Integer)

    the size of the file in bytes

  • :thumbnail_url (String, URI)

    the URL to a thumbnail of the file

  • :thumbnail_info (Hash)

    ThumbnailInfo about the thumbnail file



210
211
212
# File 'lib/matrix_sdk/room.rb', line 210

def send_file(url, name, file_info = {})
  client.api.send_content(id, url, name, 'm.file', extra_information: file_info)
end

#send_html(html, body = nil, msg_type = 'm.text') ⇒ Object

Sends a custom HTML message to the room

Parameters:

  • html (String)

    the HTML message to send

  • body (String, nil) (defaults to: nil)

    a plain-text representation of the object (Will default to the HTML with tags stripped away)

  • msg_type (String) (defaults to: 'm.text')

    A message type for the message

See Also:



184
185
186
187
188
189
190
191
192
193
# File 'lib/matrix_sdk/room.rb', line 184

def send_html(html, body = nil, msg_type = 'm.text')
  content = {
    body: body || html.gsub(/<\/?[^>]*>/, ''),
    msgtype: msg_type,
    format: 'org.matrix.custom.html',
    formatted_body: html
  }

  client.api.send_message_event(id, 'm.room.message', content)
end

#send_image(url, name, image_info = {}) ⇒ Object

Note:

The URLs should all be of the ‘mxc://’ schema

Sends a link to an image to the room

Parameters:

  • url (String, URI)

    the URL to the image

  • name (String)

    the name of the image

  • image_info (Hash) (defaults to: {})

    extra information about the image

Options Hash (image_info):

  • :h (Integer)

    the height of the image in pixels

  • :w (Integer)

    the width of the image in pixels

  • :mimetype (String)

    the MIME type of the image

  • :size (Integer)

    the size of the image in bytes

  • :thumbnail_url (String, URI)

    the URL to a thumbnail of the image

  • :thumbnail_info (Hash)

    ThumbnailInfo about the thumbnail image



231
232
233
# File 'lib/matrix_sdk/room.rb', line 231

def send_image(url, name, image_info = {})
  client.api.send_content(id, url, name, 'm.image', extra_information: image_info)
end

#send_location(geo_uri, name, thumbnail_url = nil, thumbnail_info = {}) ⇒ Object

Note:

The thumbnail URL should be of the ‘mxc://’ schema

Sends a location object to the room

Parameters:

  • geo_uri (String, URI)

    the geo-URL (e.g. geo:<coords>) of the location

  • name (String)

    the name of the location

  • thumbnail_url (String, URI) (defaults to: nil)

    the URL to a thumbnail image of the location

  • thumbnail_info (Hash) (defaults to: {})

    a ThumbnailInfo for the location thumbnail



241
242
243
# File 'lib/matrix_sdk/room.rb', line 241

def send_location(geo_uri, name, thumbnail_url = nil, thumbnail_info = {})
  client.api.send_location(id, geo_uri, name, thumbnail_url: thumbnail_url, thumbnail_info: thumbnail_info)
end

#send_notice(text) ⇒ Object

Sends a notice (bot) message to the room

Parameters:

  • text (String)

    the notice to send



216
217
218
# File 'lib/matrix_sdk/room.rb', line 216

def send_notice(text)
  client.api.send_notice(id, text)
end

#send_text(text) ⇒ Object

Sends a plain-text message to the room

Parameters:

  • text (String)

    the message to send



173
174
175
# File 'lib/matrix_sdk/room.rb', line 173

def send_text(text)
  client.api.send_message(id, text)
end

#send_video(url, name, video_info = {}) ⇒ Object

Note:

The URLs should all be of the ‘mxc://’ schema

Sends a link to a video to the room

Parameters:

  • url (String, URI)

    the URL to the video

  • name (String)

    the name of the video

  • video_info (Hash) (defaults to: {})

    extra information about the video

Options Hash (video_info):

  • :duration (Integer)

    the duration of the video in milliseconds

  • :h (Integer)

    the height of the video in pixels

  • :w (Integer)

    the width of the video in pixels

  • :mimetype (String)

    the MIME type of the video

  • :size (Integer)

    the size of the video in bytes

  • :thumbnail_url (String, URI)

    the URL to a thumbnail of the video

  • :thumbnail_info (Hash)

    ThumbnailInfo about the thumbnail of the video



257
258
259
# File 'lib/matrix_sdk/room.rb', line 257

def send_video(url, name, video_info = {})
  client.api.send_content(id, url, name, 'm.video', extra_information: video_info)
end

#set_account_data(type, account_data) ⇒ Object

Stores a custom entry into the room-specific account data

Parameters:

  • type (String)

    the data type to store

  • account_data (Hash)

    the data to store



356
357
358
359
# File 'lib/matrix_sdk/room.rb', line 356

def (type, )
  client.api.(client.mxid, id, type, )
  true
end

#set_user_profile(display_name: nil, avatar_url: nil, reason: nil) ⇒ Object

Note:

the avatar URL should be a mxc:// URI

Changes the room-specific user profile

Parameters:

  • display_name (String) (defaults to: nil)

    the new display name to use in the room

  • avatar_url (String, URI) (defaults to: nil)

    the new avatar URL to use in the room



365
366
367
368
369
370
371
372
373
374
375
376
# File 'lib/matrix_sdk/room.rb', line 365

def (display_name: nil, avatar_url: nil, reason: nil)
  return nil unless display_name || avatar_url

  data = client.api.get_membership(id, client.mxid)
  raise "Can't set profile if you haven't joined the room" unless data[:membership] == 'join'

  data[:displayname] = display_name unless display_name.nil?
  data[:avatar_url] = avatar_url unless avatar_url.nil?

  client.api.set_membership(id, client.mxid, 'join', reason || 'Updating room profile information', data)
  true
end

#tagsResponse

Returns a list of the room tags

Examples:

Managing tags

room.tags
# => { :room_tag => { data: false } }
room.tags.add('some_tag', data: true)
# => { :some_tag => { data: true }, :room_tag => { data: false} }
room.tags.remove('room_tag')
# => { :some_tag => { data: true} }

Returns:

  • (Response)

    A list of the tags and their data, with add and remove methods implemented



387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
# File 'lib/matrix_sdk/room.rb', line 387

def tags
  client.api.get_user_tags(client.mxid, id)[:tags].tap do |tag_obj|
    tag_obj.instance_variable_set(:@room, self)
    tag_obj.define_singleton_method(:room) do
      @room
    end
    tag_obj.define_singleton_method(:add) do |tag, **data|
      @room.add_tag(tag.to_s.to_sym, data)
      self[tag.to_s.to_sym] = data
      self
    end
    tag_obj.define_singleton_method(:remove) do |tag|
      @room.remove_tag(tag.to_s.to_sym)
      delete tag.to_s.to_sym
    end
  end
end

#unban_user(user_id) ⇒ Boolean

Unbans a user from the room

Parameters:

  • user_id (String, User)

    the MXID of the user

Returns:

  • (Boolean)

    wether the action succeeded



332
333
334
335
336
# File 'lib/matrix_sdk/room.rb', line 332

def unban_user(user_id)
  user_id = user_id.id if user_id.is_a? MatrixSdk::User
  client.api.unban_user(id, user_id)
  true
end