Class: MatrixSdk::Room

Inherits:
Object
  • Object
show all
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

Constructor Details

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

Returns a new instance of Room.



56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
 
# File 'lib/matrix_sdk/room.rb', line 56

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
  @members = []
  @events = []
  @event_history_limit = 10

  @prev_batch = nil

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

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

Instance Attribute Details

#aliases ⇒ Array(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:



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

attr_reader :id, :client, :name, :topic, :aliases, :join_rule, :guest_access, :members, :events

#canonical_alias ⇒ String?

Returns the canonical alias of the room.

Returns:

  • (String, nil) —

    the canonical alias of the room



10
11
12
 
# File 'lib/matrix_sdk/room.rb', line 10

def canonical_alias
  @canonical_alias
end

#client ⇒ Client (readonly)

Returns the client for the room.

Returns:

  • (Client) —

    the client for the room



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

attr_reader :id, :client, :name, :topic, :aliases, :join_rule, :guest_access, :members, :events

#event_history_limit ⇒ Fixnum

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

Returns:

  • (Fixnum) —

    the limit of events to keep in the event log



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

attr_accessor :canonical_alias, :event_history_limit

#events ⇒ Object (readonly)

Returns the value of attribute events.



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

attr_reader :id, :client, :name, :topic, :aliases, :join_rule, :guest_access, :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



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

attr_reader :id, :client, :name, :topic, :aliases, :join_rule, :guest_access, :members, :events

#id ⇒ String (readonly) Also known as: room_id

Returns the internal ID of the room.

Returns:

  • (String) —

    the internal ID of the room



38
39
40
 
# File 'lib/matrix_sdk/room.rb', line 38

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



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

attr_reader :id, :client, :name, :topic, :aliases, :join_rule, :guest_access, :members, :events

#members ⇒ Array(User) (readonly)

Returns the members of the room.

Returns:

  • (Array(User)) —

    the members of the room

See Also:

  • reload_members!


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

attr_reader :id, :client, :name, :topic, :aliases, :join_rule, :guest_access, :members, :events

#name ⇒ String?

Returns the user-provided name of the room.

Returns:

  • (String, nil) —

    the user-provided name of the room

See Also:



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

attr_reader :id, :client, :name, :topic, :aliases, :join_rule, :guest_access, :members, :events

#on_ephemeral_event ⇒ EventHandlerArray (readonly)

Returns The list of event handlers for only ephemeral events.

Returns:



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

events :event, :state_event, :ephemeral_event

#on_event ⇒ EventHandlerArray (readonly)

Returns The list of event handlers for all events.

Returns:



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

events :event, :state_event, :ephemeral_event

#on_state_event ⇒ EventHandlerArray (readonly)

Returns The list of event handlers for only state events.

Returns:



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

events :event, :state_event, :ephemeral_event

#topic ⇒ String?

Returns the user-provided topic of the room.

Returns:

  • (String, nil) —

    the user-provided topic of the room

See Also:



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

attr_reader :id, :client, :name, :topic, :aliases, :join_rule, :guest_access, :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



369
370
371
372
373
374
375
 
# File 'lib/matrix_sdk/room.rb', line 369

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

#add_tag(tag, params = {}) ⇒ Object 



327
328
329
 
# File 'lib/matrix_sdk/room.rb', line 327

def add_tag(tag, params = {})
  client.api.add_user_tag(client.mxid, id, tag, params)
end

#allow_guests=(allow_guests) ⇒ Object 



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

def allow_guests=(allow_guests)
  self.guest_access = (allow_guests ? :can_join : :forbidden)
  @guest_access == :can_join # rubocop:disable Lint/Void
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



250
251
252
253
254
255
256
257
258
 
# File 'lib/matrix_sdk/room.rb', line 250

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
end

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



278
279
280
281
282
283
 
# File 'lib/matrix_sdk/room.rb', line 278

def ban_user(user_id, reason = '')
  client.api.ban_user(id, user_id, reason: reason)
  true
rescue MatrixError
  false
end

#display_name ⇒ String

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



97
98
99
100
101
102
103
104
105
106
107
108
109
110
 
# File 'lib/matrix_sdk/room.rb', line 97

def display_name
  return name if name
  return canonical_alias if canonical_alias

  members = joined_members
            .reject { |m| m.user_id == client.mxid }
            .map(&:get_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) ⇒ Object 



300
301
302
 
# File 'lib/matrix_sdk/room.rb', line 300

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

#guest_access? ⇒ Boolean

Checks if guest_access is set to :can_join

Returns:

  • (Boolean) 


124
125
126
 
# File 'lib/matrix_sdk/room.rb', line 124

def guest_access?
  guest_access == :can_join
end

#inspect ⇒ String

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



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

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

#invite_only=(invite_only) ⇒ Object 



396
397
398
399
 
# File 'lib/matrix_sdk/room.rb', line 396

def invite_only=(invite_only)
  self.join_rule = invite_only ? :invite : :public
  @join_rule == :invite # rubocop:disable Lint/Void
end

#invite_only? ⇒ Boolean

Checks if join_rule is set to :invite

Returns:

  • (Boolean) 


129
130
131
 
# File 'lib/matrix_sdk/room.rb', line 129

def invite_only?
  join_rule == :invite
end

#invite_user(user_id) ⇒ Object

User Management



264
265
266
267
268
269
 
# File 'lib/matrix_sdk/room.rb', line 264

def invite_user(user_id)
  client.api.invite_user(id, user_id)
  true
rescue MatrixError
  false
end

#joined_members ⇒ Object

Populates and returns the #members array



113
114
115
116
117
118
119
120
121
 
# File 'lib/matrix_sdk/room.rb', line 113

def joined_members
  return members unless 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)))
  end
  members
end

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



271
272
273
274
275
276
 
# File 'lib/matrix_sdk/room.rb', line 271

def kick_user(user_id, reason = '')
  client.api.kick_user(id, user_id, reason: reason)
  true
rescue MatrixError
  false
end

#leave ⇒ Object 



292
293
294
295
296
297
298
 
# File 'lib/matrix_sdk/room.rb', line 292

def leave
  client.api.leave_room(id)
  client.rooms.delete id
  true
rescue MatrixError
  false
end

#logger ⇒ Object 



80
81
82
 
# File 'lib/matrix_sdk/room.rb', line 80

def logger
  Logging.logger[self.class.name]
end

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



437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
 
# File 'lib/matrix_sdk/room.rb', line 437

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)
rescue MatrixError
  false
end

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



420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
 
# File 'lib/matrix_sdk/room.rb', line 420

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
rescue MatrixError
  false
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



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

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

#reload_aliases! ⇒ Boolean

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



381
382
383
384
385
386
387
388
389
390
391
392
393
394
 
# File 'lib/matrix_sdk/room.rb', line 381

def reload_aliases!
  data = client.api.get_room_state(id)
  new_aliases = data.select { |chunk| chunk.key?(:content) && chunk[:content].key?(:aliases) }
                    .map { |chunk| chunk[:content][:aliases] }
                    .flatten
                    .reject(&:nil?)
  return false if new_aliases.nil?

  changed = new_aliases != aliases
  @aliases = new_aliases if changed
  changed
rescue MatrixError
  false
end

#reload_name! ⇒ Object 



342
343
344
345
346
347
348
349
 
# File 'lib/matrix_sdk/room.rb', line 342

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

#reload_topic! ⇒ Object 



358
359
360
361
362
363
364
365
 
# File 'lib/matrix_sdk/room.rb', line 358

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

#remove_tag(tag) ⇒ Object 



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

def remove_tag(tag)
  client.api.remove_user_tag(client.mxid, id, tag)
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



235
236
237
 
# File 'lib/matrix_sdk/room.rb', line 235

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



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

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



176
177
178
 
# File 'lib/matrix_sdk/room.rb', line 176

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:



150
151
152
153
154
155
156
157
158
159
 
# File 'lib/matrix_sdk/room.rb', line 150

def send_html(html, body = nil, msg_type = 'm.text')
  content = {
    body: 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



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

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



207
208
209
 
# File 'lib/matrix_sdk/room.rb', line 207

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



182
183
184
 
# File 'lib/matrix_sdk/room.rb', line 182

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



139
140
141
 
# File 'lib/matrix_sdk/room.rb', line 139

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



223
224
225
 
# File 'lib/matrix_sdk/room.rb', line 223

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 



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

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

#set_user_profile(params = {}) ⇒ Object 



308
309
310
311
312
313
314
315
316
317
 
# File 'lib/matrix_sdk/room.rb', line 308

def (params = {})
  return nil unless params[:display_name] || params[: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] = params[:display_name] unless params[:display_name].nil?
  data[:avatar_url] = params[:avatar_url] unless params[:avatar_url].nil?

  client.api.set_membership(id, client.mxid, 'join', params.fetch(:reason, 'Updating room profile information'), data)
end

#tags ⇒ Object 



319
320
321
 
# File 'lib/matrix_sdk/room.rb', line 319

def tags
  client.api.get_user_tags(client.mxid, id)
end

#unban_user(user_id) ⇒ Object 



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

def unban_user(user_id)
  client.api.unban_user(id, user_id)
  true
rescue MatrixError
  false
end