NAME

       "Net::Async::Matrix::Room" - a single Matrix room

DESCRIPTION

       An instances in this class are used by Net::Async::Matrix to represent a single Matrix
       room.

EVENTS

       The following events are invoked, either using subclass methods or "CODE" references in
       parameters:

   on_synced_state
       Invoked after the initial sync of the room has been completed as far as the state.

   on_message $member, $content, $event
   on_back_message $member, $content, $event
       Invoked on receipt of a new message from the given member, either "live" from the event
       stream, or from backward pagination.

   on_membership $member, $event, $subject_member, %changes
   on_back_membership $member, $event, $subject_member, %changes
       Invoked on receipt of a membership change event for the given member, either "live" from
       the event stream, or from backward pagination. %changes will be a key/value list of state
       field names that were changed, whose values are 2-element ARRAY references containing the
       before/after values of those fields.

        on_membership:      $field_name => [ $old_value, $new_value ]
        on_back_membership: $field_name => [ $new_value, $old_value ]

       Note carefully that the second value in each array gives the "updated" value, in the
       direction of the change - that is, for "on_membership" it gives the new value after the
       change but for "on_back_message" it gives the old value before. Fields whose values did
       not change are not present in the %changes list; the values of these can be inspected on
       the $member object.

       It is unspecified what values the $member object has for fields present in the change list
       - client code should not rely on these fields.

       In most cases when users change their own membership status (such as normal join or
       leave), the $member and $subject_member parameters refer to the same object. In other
       cases, such as invites or kicks, the $member parameter refers to the member performing the
       change, and the $subject_member refers to member that the change is about.

   on_state_changed $member, $event, %changes
   on_back_state_changed $member, $event, %changes
       Invoked on receipt of a change of room state (such as name or topic).

       In the special case of room aliases, because they are considered "state" but are stored
       per-homeserver, the changes value will consist of three fields; the old and new values
       from that home server, and a list of the known aliases from all the other servers:

        on_state_changed:      aliases => [ $old, $new, $other ]
        on_back_state_changed: aliases => [ $new, $old, $other ]

       This allows a client to detect deletions and additions by comparing the before and after
       lists, while still having access to the full set of before or after aliases, should it
       require it.

   on_presence $member, %changes
       Invoked when a member of the room changes membership or presence state. The $member object
       will already be in the new state. %changes will be a key/value list of state fields names
       that were changed, and references to 2-element ARRAYs containing the old and new values
       for this field.

   on_typing $member, $is_typing
       Invoked on receipt of a typing notification change, when the given member either starts or
       stops typing.

   on_members_typing @members
       Invoked on receipt of a typing notification change to give the full set of currently-
       typing members. This is invoked after the individual "on_typing" events.

   on_read_receipt $member, $event_id, $content
       Invoked on receipt of a "m.read" type of receipt message.

METHODS

   await_synced
          $f = $room->await_synced

       Returns a Future stored within the room that will complete (with no value) once the room
       initial state sync has been completed. This completes just before the "on_synced_state"
       event.

   live_state
          $state = $room->live_state

       Returns a Net::Async::Matrix::Room::State instance representing the current live-tracking
       state of the room.

       This instance will mutate and change as new state events are received.

   room_id
          $id = $room->room_id

       Returns the opaque room ID string for the room. Usually this would not be required, except
       for long-term persistence uniqueness purposes, or for inclusion in direct protocol URLs.

   name
          $name = $room->name

       Returns the room name, if defined, otherwise the opaque room ID.

   set_name
          $room->set_name( $name )->get

       Requests to set a new room name.

   aliases
          @aliases = $room->aliases

       Returns a list of all the known room alias names taken from the "m.room.alias" events.
       Note that these are simply names claimed to have aliases from the alias events; a client
       ought to still check that these are valid before presenting them to the user as such, or
       in other ways relying on their values.

   join_rule
          $rule = $room->join_rule

       Returns the current "join_rule" for the room; a string giving the type of access new
       members may get:

       •   public

           Any user may join without further permission

       •   invite

           Users may only join if explicitly invited

       •   knock

           Any user may send a knock message to request access; may only join if invited

       •   private

           No new users may join the room

   topic
          $topic = $room->topic

       Returns the room topic, if defined

   set_topic
          $room->set_topic( $topic )->get

       Requests to set a new room topic.

   levels
          %levels = $room->levels

       Returns a key/value list of the room levels; that is, the member power level required to
       perform each of the named actions.

   change_levels
          $room->change_levels( %levels )->get

       Performs a room levels change, submitting new values for the given keys while leaving
       other keys unchanged.

   members
          @members = $room->members

       Returns a list of member structs containing the currently known members of the room, in no
       particular order. This list will include users who are not yet members of the room, but
       simply have been invited.

   joined_members
          @members = $room->joined_members

       Returns the subset of "all_members" who actually in the "join" state - i.e. are not
       invitees, or have left.

   member_level
          $level = $room->member_level( $user_id )

       Returns the current cached value for the power level of the given user ID, or the default
       value if no specific value exists for the given ID.

   change_member_levels
          $room->change_member_levels( %levels )->get

       Performs a member power level change, submitting new values for user IDs to the home
       server. As there is no server API to make individual mutations, this is done by taking the
       currently cached values, applying the changes given by the %levels key/value list, and
       submitting the resulting whole as the new value for the "m.room.power_levels" room state.

       The %levels key/value list should provide new values for keys giving user IDs, or the
       special user ID of "default" to change the overall default value for users not otherwise
       mentioned. Setting the special value of "undef" for a user ID will remove that ID from the
       set, reverting them to the default.

   leave
          $room->leave->get

       Requests to leave the room. After this completes, the user will no longer be a member of
       the room.

   invite
          $room->invite( $user_id )->get

       Sends an invitation for the user with the given User ID to join the room.

   kick
          $room->kick( $user_id, $reason )->get

       Requests to remove the user with the given User ID from the room.

       Optionally, a textual description reason can also be provided.

   send_message
          $event_id = $room->send_message( %args )->get

       Sends a new message to the room. Requires a "type" named argument giving the message type.
       Depending on the type, further keys will be required that specify the message contents:

       m.text, m.emote, m.notice
           Require "body"

       m.image, m.audio, m.video, m.file
           Require "url"

       m.location
           Require "geo_uri"

       If an additional argument called "txn_id" is provided, this is used as the transaction ID
       for the message, which is then sent as a "PUT" request instead of a "POST".

          $event_id = $room->send_message( $text )->get

       A convenient shortcut to sending an "text" message with a body string and no additional
       content.

   paginate_messages
          $room->paginate_messages( limit => $n )->get

       Requests more messages of back-pagination history.

       There is no need to maintain a reference on the returned "Future"; it will be adopted by
       the room object.

   typing_start
          $room->typing_start

       Sends a typing notification that the user is currently typing in this room.  This
       notification will periodically be re-sent as required by the protocol until the
       "typing_stop" method is called.

   typing_stop
          $room->typing_stop

       Sends a typing notification that the user is no longer typing in this room.  This method
       also cancels the repeating re-send behaviour created by "typing_start".

   send_read_receipt
          $room->send_read_receipt( event_id => $event_id, ... )->get

       Sends a "m.read" receipt to the given room for the given event ID.

MEMBERSHIP STRUCTURES

       Parameters documented as $member receive a membership struct, which supports the following
       methods:

   $user = $member->user
       User object of the member.

   $displayname = $member->displayname
       Profile displayname of the user.

   $membership = $member->membership
       Membership state. One of "invite" or "join".

AUTHOR

       Paul Evans <leonerd@leonerd.org.uk>