.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "Net::Async::Matrix::Room 3pm" .TH Net::Async::Matrix::Room 3pm "2022-12-10" "perl v5.36.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" "Net::Async::Matrix::Room" \- a single Matrix room .SH "DESCRIPTION" .IX Header "DESCRIPTION" An instances in this class are used by Net::Async::Matrix to represent a single Matrix room. .SH "EVENTS" .IX Header "EVENTS" The following events are invoked, either using subclass methods or \f(CW\*(C`CODE\*(C'\fR references in parameters: .SS "on_synced_state" .IX Subsection "on_synced_state" Invoked after the initial sync of the room has been completed as far as the state. .ie n .SS "on_message $member, $content, $event" .el .SS "on_message \f(CW$member\fP, \f(CW$content\fP, \f(CW$event\fP" .IX Subsection "on_message $member, $content, $event" .ie n .SS "on_back_message $member, $content, $event" .el .SS "on_back_message \f(CW$member\fP, \f(CW$content\fP, \f(CW$event\fP" .IX Subsection "on_back_message $member, $content, $event" Invoked on receipt of a new message from the given member, either \*(L"live\*(R" from the event stream, or from backward pagination. .ie n .SS "on_membership $member, $event, $subject_member, %changes" .el .SS "on_membership \f(CW$member\fP, \f(CW$event\fP, \f(CW$subject_member\fP, \f(CW%changes\fP" .IX Subsection "on_membership $member, $event, $subject_member, %changes" .ie n .SS "on_back_membership $member, $event, $subject_member, %changes" .el .SS "on_back_membership \f(CW$member\fP, \f(CW$event\fP, \f(CW$subject_member\fP, \f(CW%changes\fP" .IX Subsection "on_back_membership $member, $event, $subject_member, %changes" Invoked on receipt of a membership change event for the given member, either \&\*(L"live\*(R" from the event stream, or from backward pagination. \f(CW%changes\fR will be a key/value list of state field names that were changed, whose values are 2\-element \s-1ARRAY\s0 references containing the before/after values of those fields. .PP .Vb 2 \& on_membership: $field_name => [ $old_value, $new_value ] \& on_back_membership: $field_name => [ $new_value, $old_value ] .Ve .PP Note carefully that the second value in each array gives the \*(L"updated\*(R" value, in the direction of the change \- that is, for \f(CW\*(C`on_membership\*(C'\fR it gives the new value after the change but for \f(CW\*(C`on_back_message\*(C'\fR it gives the old value before. Fields whose values did not change are not present in the \f(CW%changes\fR list; the values of these can be inspected on the \f(CW$member\fR object. .PP It is unspecified what values the \f(CW$member\fR object has for fields present in the change list \- client code should not rely on these fields. .PP In most cases when users change their own membership status (such as normal join or leave), the \f(CW$member\fR and \f(CW$subject_member\fR parameters refer to the same object. In other cases, such as invites or kicks, the \f(CW$member\fR parameter refers to the member performing the change, and the \&\f(CW$subject_member\fR refers to member that the change is about. .ie n .SS "on_state_changed $member, $event, %changes" .el .SS "on_state_changed \f(CW$member\fP, \f(CW$event\fP, \f(CW%changes\fP" .IX Subsection "on_state_changed $member, $event, %changes" .ie n .SS "on_back_state_changed $member, $event, %changes" .el .SS "on_back_state_changed \f(CW$member\fP, \f(CW$event\fP, \f(CW%changes\fP" .IX Subsection "on_back_state_changed $member, $event, %changes" Invoked on receipt of a change of room state (such as name or topic). .PP In the special case of room aliases, because they are considered \*(L"state\*(R" but are stored per-homeserver, the changes value will consist of three fields; the old and new values \fIfrom that home server\fR, and a list of the known aliases from all the other servers: .PP .Vb 2 \& on_state_changed: aliases => [ $old, $new, $other ] \& on_back_state_changed: aliases => [ $new, $old, $other ] .Ve .PP 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. .ie n .SS "on_presence $member, %changes" .el .SS "on_presence \f(CW$member\fP, \f(CW%changes\fP" .IX Subsection "on_presence $member, %changes" Invoked when a member of the room changes membership or presence state. The \&\f(CW$member\fR object will already be in the new state. \f(CW%changes\fR 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. .ie n .SS "on_typing $member, $is_typing" .el .SS "on_typing \f(CW$member\fP, \f(CW$is_typing\fP" .IX Subsection "on_typing $member, $is_typing" Invoked on receipt of a typing notification change, when the given member either starts or stops typing. .ie n .SS "on_members_typing @members" .el .SS "on_members_typing \f(CW@members\fP" .IX Subsection "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 \f(CW\*(C`on_typing\*(C'\fR events. .ie n .SS "on_read_receipt $member, $event_id, $content" .el .SS "on_read_receipt \f(CW$member\fP, \f(CW$event_id\fP, \f(CW$content\fP" .IX Subsection "on_read_receipt $member, $event_id, $content" Invoked on receipt of a \f(CW\*(C`m.read\*(C'\fR type of receipt message. .SH "METHODS" .IX Header "METHODS" .SS "await_synced" .IX Subsection "await_synced" .Vb 1 \& $f = $room\->await_synced .Ve .PP 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 \&\fIbefore\fR the \f(CW\*(C`on_synced_state\*(C'\fR event. .SS "live_state" .IX Subsection "live_state" .Vb 1 \& $state = $room\->live_state .Ve .PP Returns a Net::Async::Matrix::Room::State instance representing the current live-tracking state of the room. .PP This instance will mutate and change as new state events are received. .SS "room_id" .IX Subsection "room_id" .Vb 1 \& $id = $room\->room_id .Ve .PP Returns the opaque room \s-1ID\s0 string for the room. Usually this would not be required, except for long-term persistence uniqueness purposes, or for inclusion in direct protocol URLs. .SS "name" .IX Subsection "name" .Vb 1 \& $name = $room\->name .Ve .PP Returns the room name, if defined, otherwise the opaque room \s-1ID.\s0 .SS "set_name" .IX Subsection "set_name" .Vb 1 \& $room\->set_name( $name )\->get .Ve .PP Requests to set a new room name. .SS "aliases" .IX Subsection "aliases" .Vb 1 \& @aliases = $room\->aliases .Ve .PP Returns a list of all the known room alias names taken from the \&\f(CW\*(C`m.room.alias\*(C'\fR events. Note that these are simply names \fIclaimed\fR 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. .SS "join_rule" .IX Subsection "join_rule" .Vb 1 \& $rule = $room\->join_rule .Ve .PP Returns the current \f(CW\*(C`join_rule\*(C'\fR for the room; a string giving the type of access new members may get: .IP "\(bu" 4 public .Sp Any user may join without further permission .IP "\(bu" 4 invite .Sp Users may only join if explicitly invited .IP "\(bu" 4 knock .Sp Any user may send a knock message to request access; may only join if invited .IP "\(bu" 4 private .Sp No new users may join the room .SS "topic" .IX Subsection "topic" .Vb 1 \& $topic = $room\->topic .Ve .PP Returns the room topic, if defined .SS "set_topic" .IX Subsection "set_topic" .Vb 1 \& $room\->set_topic( $topic )\->get .Ve .PP Requests to set a new room topic. .SS "levels" .IX Subsection "levels" .Vb 1 \& %levels = $room\->levels .Ve .PP Returns a key/value list of the room levels; that is, the member power level required to perform each of the named actions. .SS "change_levels" .IX Subsection "change_levels" .Vb 1 \& $room\->change_levels( %levels )\->get .Ve .PP Performs a room levels change, submitting new values for the given keys while leaving other keys unchanged. .SS "members" .IX Subsection "members" .Vb 1 \& @members = $room\->members .Ve .PP 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. .SS "joined_members" .IX Subsection "joined_members" .Vb 1 \& @members = $room\->joined_members .Ve .PP Returns the subset of \f(CW\*(C`all_members\*(C'\fR who actually in the \f(CW"join"\fR state \- i.e. are not invitees, or have left. .SS "member_level" .IX Subsection "member_level" .Vb 1 \& $level = $room\->member_level( $user_id ) .Ve .PP Returns the current cached value for the power level of the given user \s-1ID,\s0 or the default value if no specific value exists for the given \s-1ID.\s0 .SS "change_member_levels" .IX Subsection "change_member_levels" .Vb 1 \& $room\->change_member_levels( %levels )\->get .Ve .PP Performs a member power level change, submitting new values for user IDs to the home server. As there is no server \s-1API\s0 to make individual mutations, this is done by taking the currently cached values, applying the changes given by the \f(CW%levels\fR key/value list, and submitting the resulting whole as the new value for the \f(CW\*(C`m.room.power_levels\*(C'\fR room state. .PP The \f(CW%levels\fR key/value list should provide new values for keys giving user IDs, or the special user \s-1ID\s0 of \f(CW\*(C`default\*(C'\fR to change the overall default value for users not otherwise mentioned. Setting the special value of \f(CW\*(C`undef\*(C'\fR for a user \s-1ID\s0 will remove that \s-1ID\s0 from the set, reverting them to the default. .SS "leave" .IX Subsection "leave" .Vb 1 \& $room\->leave\->get .Ve .PP Requests to leave the room. After this completes, the user will no longer be a member of the room. .SS "invite" .IX Subsection "invite" .Vb 1 \& $room\->invite( $user_id )\->get .Ve .PP Sends an invitation for the user with the given User \s-1ID\s0 to join the room. .SS "kick" .IX Subsection "kick" .Vb 1 \& $room\->kick( $user_id, $reason )\->get .Ve .PP Requests to remove the user with the given User \s-1ID\s0 from the room. .PP Optionally, a textual description reason can also be provided. .SS "send_message" .IX Subsection "send_message" .Vb 1 \& $event_id = $room\->send_message( %args )\->get .Ve .PP Sends a new message to the room. Requires a \f(CW\*(C`type\*(C'\fR named argument giving the message type. Depending on the type, further keys will be required that specify the message contents: .IP "m.text, m.emote, m.notice" 4 .IX Item "m.text, m.emote, m.notice" Require \f(CW\*(C`body\*(C'\fR .IP "m.image, m.audio, m.video, m.file" 4 .IX Item "m.image, m.audio, m.video, m.file" Require \f(CW\*(C`url\*(C'\fR .IP "m.location" 4 .IX Item "m.location" Require \f(CW\*(C`geo_uri\*(C'\fR .PP If an additional argument called \f(CW\*(C`txn_id\*(C'\fR is provided, this is used as the transaction \s-1ID\s0 for the message, which is then sent as a \f(CW\*(C`PUT\*(C'\fR request instead of a \f(CW\*(C`POST\*(C'\fR. .PP .Vb 1 \& $event_id = $room\->send_message( $text )\->get .Ve .PP A convenient shortcut to sending an \f(CW\*(C`text\*(C'\fR message with a body string and no additional content. .SS "paginate_messages" .IX Subsection "paginate_messages" .Vb 1 \& $room\->paginate_messages( limit => $n )\->get .Ve .PP Requests more messages of back-pagination history. .PP There is no need to maintain a reference on the returned \f(CW\*(C`Future\*(C'\fR; it will be adopted by the room object. .SS "typing_start" .IX Subsection "typing_start" .Vb 1 \& $room\->typing_start .Ve .PP 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 \f(CW\*(C`typing_stop\*(C'\fR method is called. .SS "typing_stop" .IX Subsection "typing_stop" .Vb 1 \& $room\->typing_stop .Ve .PP 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 \&\f(CW\*(C`typing_start\*(C'\fR. .SS "send_read_receipt" .IX Subsection "send_read_receipt" .Vb 1 \& $room\->send_read_receipt( event_id => $event_id, ... )\->get .Ve .PP Sends a \f(CW\*(C`m.read\*(C'\fR receipt to the given room for the given event \s-1ID.\s0 .SH "MEMBERSHIP STRUCTURES" .IX Header "MEMBERSHIP STRUCTURES" Parameters documented as \f(CW$member\fR receive a membership struct, which supports the following methods: .ie n .SS "$user = $member\->user" .el .SS "\f(CW$user\fP = \f(CW$member\fP\->user" .IX Subsection "$user = $member->user" User object of the member. .ie n .SS "$displayname = $member\->displayname" .el .SS "\f(CW$displayname\fP = \f(CW$member\fP\->displayname" .IX Subsection "$displayname = $member->displayname" Profile displayname of the user. .ie n .SS "$membership = $member\->membership" .el .SS "\f(CW$membership\fP = \f(CW$member\fP\->membership" .IX Subsection "$membership = $member->membership" Membership state. One of \f(CW\*(C`invite\*(C'\fR or \f(CW\*(C`join\*(C'\fR. .SH "AUTHOR" .IX Header "AUTHOR" Paul Evans