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.
METHODS
$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.
$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 = $room->name
Returns the room name, if defined, otherwise the opaque room ID.
$room->set_name( $name )->get
Requests to set a new room name.
@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.
$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 = $room->topic
Returns the room topic, if defined
$room->set_topic( $topic )->get
Requests to set a new room topic.
%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.
$room->change_levels( %levels )->get
Performs a room levels change, submitting new values for the given keys while leaving other keys unchanged.
@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.
@members = $room->joined_members
Returns the subset of all_members who actually in the "join" state - i.e. are not invitees, or have left.
$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.
$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.
$room->leave->get
Requests to leave the room. After this completes, the user will no longer be a member of the room.
$room->invite( $user_id )->get
Sends an invitation for the user with the given User ID to join the room.
$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:
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.
$room->send_message( $text )->get
A convenient shortcut to sending an text message with a body string and no additional content.
$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.
$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.
$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.
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>