Class: Chatrix::Api::Rooms

Inherits:
ApiComponent show all
Defined in:
lib/chatrix/api/rooms.rb

Overview

Contains methods for using room endpoints in the API.

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods inherited from ApiComponent

#make_request

Constructor Details

#initialize(matrix) ⇒ Rooms

Initializes a new Rooms instance.

Parameters:

  • matrix (Matrix) —

    The matrix API instance.



17
18
19
20
 
# File 'lib/chatrix/api/rooms.rb', line 17

def initialize(matrix)
  super
  @actions = Api::RoomActions.new @matrix
end

Instance Attribute Details

#actions ⇒ RoomActions (readonly)

Returns an instance of RoomActions to perform room actions such as joining a room or sending messages.

Returns:

  • (RoomActions) —

    an instance of RoomActions to perform room actions such as joining a room or sending messages.



13
14
15
 
# File 'lib/chatrix/api/rooms.rb', line 13

def actions
  @actions
end

Instance Method Details

#add_user_tag(user, room, tag, data = {}) ⇒ Boolean

Adds a user tag to a room.

Parameters:

  • user (String) —

    The user adding the tag.

  • room (String) —

    The room to add the tag to.

  • tag (String) —

    The tag to add.

  • data (Hash) (defaults to: {}) —

    Any additional data to add to the tag, e.g. ordering.

Returns:

  • (Boolean) —

    true if the tag was successfully added, otherwise false.



75
76
77
78
79
80
81
 
# File 'lib/chatrix/api/rooms.rb', line 75

def add_user_tag(user, room, tag, data = {})
  make_request(
    :put,
    "/user/#{user}/rooms/#{room}/tags/#{tag}",
    content: data
  ).code == 200
end

#create_alias(room, room_alias) ⇒ Boolean

Creates a new alias for a room.

Parameters:

  • room (String) —

    The room to create an alias for.

  • room_alias (String) —

    The alias to create for the room.

Returns:

  • (Boolean) —

    true if the alias was created successfully, otherwise false.



114
115
116
117
118
119
120
 
# File 'lib/chatrix/api/rooms.rb', line 114

def create_alias(room, room_alias)
  make_request(
    :put,
    "/directory/room/#{room_alias}",
    content: { room_id: room }
  ).code == 200
end

#delete_alias(room_alias) ⇒ Boolean

Deletes a room alias.

Parameters:

  • room_alias (String) —

    The alias to delete.

Returns:

  • (Boolean) —

    true if the alias was successfully removed, otherwise false.



104
105
106
 
# File 'lib/chatrix/api/rooms.rb', line 104

def delete_alias(room_alias)
  make_request(:delete, "/directory/room/#{room_alias}").code == 200
end

#delete_user_tag(user, room, tag) ⇒ Boolean

Deletes a user tag from a room.

Parameters:

  • user (String) —

    The user to remove the tag for.

  • room (String) —

    The room to remove the tag from.

  • tag (String) —

    The tag to remove.

Returns:

  • (Boolean) —

    true if the tag was removed successfully, otherwise false.



60
61
62
63
64
65
 
# File 'lib/chatrix/api/rooms.rb', line 60

def delete_user_tag(user, room, tag)
  make_request(
    :delete,
    "/user/#{user}/rooms/#{room}/tags/#{tag}"
  ).code == 200
end

#get_alias_info(room_alias) ⇒ Hash

Get information about a room alias.

This can be used to get the room ID that an alias points to.

Parameters:

  • room_alias (String) —

    The room alias to query, this must be an alias and not an ID.

Returns:

  • (Hash) —

    Returns information about the alias in a Hash.

See Also:



93
94
95
96
97
98
 
# File 'lib/chatrix/api/rooms.rb', line 93

def get_alias_info(room_alias)
  make_request(:get, "/directory/room/#{room_alias}").parsed_response
rescue NotFoundError
  raise RoomNotFoundError.new(room_alias),
        'The specified room alias could not be found'
end

#get_event_context(room, event, limit = 10) ⇒ Hash

Gets context for an event in a room.

The method will return events that happened before and after the specified event.

Parameters:

  • room (String) —

    The room to query.

  • event (String) —

    The event to get context for.

  • limit (Fixnum) (defaults to: 10) —

    Maximum number of events to retrieve.

Returns:

  • (Hash) —

    The returned hash contains information about the events happening before and after the specified event, as well as start and end timestamps and state information for the event.



141
142
143
144
145
146
147
 
# File 'lib/chatrix/api/rooms.rb', line 141

def get_event_context(room, event, limit = 10)
  make_request(
    :get,
    "/rooms/#{room}/context/#{event}",
    params: { limit: limit }
  ).parsed_response
end

#get_id(room_alias) ⇒ String

Get a room's ID from its alias.

Parameters:

  • room_alias (String) —

    The room alias to query.

Returns:

  • (String) —

    The actual room ID for the room.



126
127
128
 
# File 'lib/chatrix/api/rooms.rb', line 126

def get_id(room_alias)
  get_room_alias_info(room_alias)['room_id']
end

#get_members(room) ⇒ Array

Get the members of a room.

Parameters:

  • room (String) —

    The room to query.

Returns:

  • (Array) —

    An array of users that are in this room.



153
154
155
 
# File 'lib/chatrix/api/rooms.rb', line 153

def get_members(room)
  make_request(:get, "/rooms/#{room}/members")['chunk']
end

#get_messages(room, from: 'START', to: 'END', direction: 'b', limit: 10) ⇒ Hash

Get a list of messages from a room.

Parameters:

  • room (String) —

    The room to get messages from.

  • from (String) (defaults to: 'START') —

    Token to return events from.

  • direction ('b', 'f') (defaults to: 'b') —

    Direction to return events from.

  • limit (Fixnum) (defaults to: 10) —

    Maximum number of events to return.

Returns:

  • (Hash) —

    A hash containing the messages, as well as start and end tokens for pagination.



165
166
167
168
169
170
171
172
 
# File 'lib/chatrix/api/rooms.rb', line 165

def get_messages(room, from: 'START', to: 'END',
                 direction: 'b', limit: 10)
  make_request(
    :get,
    "/rooms/#{room}/messages",
    params: { from: from, to: to, dir: direction, limit: limit }
  ).parsed_response
end

#get_rooms(from: 'START', to: 'END', limit: 10, direction: 'b') ⇒ Hash

Get the list of public rooms on the server.

The start and end values returned in the result can be passed to from and to, for pagination purposes.

Parameters:

  • from (String) (defaults to: 'START') —

    The stream token to start looking from.

  • to (String) (defaults to: 'END') —

    The stream token to stop looking at.

  • limit (Fixnum) (defaults to: 10) —

    Maximum number of results to return in one request.

  • direction ('f', 'b') (defaults to: 'b') —

    Direction to look in.

Returns:

  • (Hash) —

    Hash containing the list of rooms (in the chunk value), and pagination parameters start and end.



34
35
36
37
38
39
40
 
# File 'lib/chatrix/api/rooms.rb', line 34

def get_rooms(from: 'START', to: 'END', limit: 10, direction: 'b')
  make_request(
    :get,
    '/publicRooms',
    params: { from: from, to: to, limit: limit, dir: direction }
  ).parsed_response
end

#get_room_state(room) ⇒ Array #get_room_state(room, type) ⇒ Hash #get_room_state(room, type, key) ⇒ Hash

Overloads:

  • #get_room_state(room) ⇒ Array

    Get state events for the current state of a room.

    Parameters:

    • room (String) —

      The room to get events for.

    Returns:

    • (Array) —

      An array with state events for the room.

  • #get_room_state(room, type) ⇒ Hash

    Get the contents of a specific kind of state in the room.

    Parameters:

    • room (String) —

      The room to get the data from.

    • type (String) —

      The type of state to get.

    Returns:

    • (Hash) —

      Information about the state type.

  • #get_room_state(room, type, key) ⇒ Hash

    Get the contents of a specific kind of state including only the specified key in the result.

    Parameters:

    • room (String) —

      The room to get the data from.

    • type (String) —

      The type of state to get.

    • key (String) —

      The key of the state to look up.

    Returns:

    • (Hash) —

      Information about the requested state.



190
191
192
193
194
195
196
197
198
199
 
# File 'lib/chatrix/api/rooms.rb', line 190

def get_state(room, type = nil, key = nil)
  if type && key
    make_request(:get, "/rooms/#{room}/state/#{type}/#{key}")
      .parsed_response
  elsif type
    make_request(:get, "/rooms/#{room}/state/#{type}").parsed_response
  else
    make_request(:get, "/rooms/#{room}/state").parsed_response
  end
end

#get_user_tags(user, room) ⇒ Hash{String=>Hash}

Get tags that a specific user has set on a room.

Parameters:

  • user (String) —

    The user whose settings to retrieve (@user:host.tld).

  • room (String) —

    The room to get tags from.

Returns:

  • (Hash{String=>Hash}) —

    A hash with tag data. The tag name is the key and any additional metadata is contained in the Hash value.



49
50
51
 
# File 'lib/chatrix/api/rooms.rb', line 49

def get_user_tags(user, room)
  make_request(:get, "/user/#{user}/rooms/#{room}/tags")['tags']
end

#send_state(room, type, content, key = nil) ⇒ String

Sends a state event to a room, with an optional state key.

Parameters:

  • room (String) —

    The room to send the event to.

  • type (String) —

    The event type to send.

  • content (Hash) —

    The content to set for the event.

  • key (String, nil) (defaults to: nil) —

    Optional state_key to use.

Returns:

  • (String) —

    The event ID for the sent event.



207
208
209
210
211
212
213
 
# File 'lib/chatrix/api/rooms.rb', line 207

def send_state(room, type, content, key = nil)
  path = "/rooms/#{room}/state/#{type}"

  path += "/#{key}" if key

  make_request(:put, path, content: content)['event_id']
end