1AnyEvent::XMPP::Ext::MUUCs(e3r)Contributed Perl DocumentAantyiEovnent::XMPP::Ext::MUC(3)
2
6 AnyEvent::XMPP::Ext::MUC - Implements XEP-0045: Multi-User Chat
7
9 my $con = AnyEvent::XMPP::Connection->new (...);
10 $con->add_extension (my $disco = AnyEvent::XMPP::Ext::Disco->new);
11 $con->add_extension (my $muc = AnyEvent::XMPP::Ext::MUC->new (disco => $disco));
12 ...
13
15 This module handles multi user chats and provides new events to catch
16 multi user chat messages. It intercepts messages from the connection so
17 they don't interfere with your other callbacks on the connection.
18 This extension requires the AnyEvent::XMPP::Ext::Disco extension for
20 service discovery.
21
23 new This is the constructor for a MUC extension object. It takes no
24 further arguments.
25 is_conference ($con, $jid, $cb)
27 TODO
28 is_room ($con, $jid, $cb)
30 This method sends a information discovery to the $jid, via the
31 connection $con. $cb is called when the information arrives or
32 with an error after the usual IQ timeout.
33 When the $jid was a room $cb is called with the first argument
35 being a AnyEvent::XMPP::Ext::MUC::RoomInfo object. If the
36 destination wasn't reachable, the room doesn't exist or some other
37 error happened the first argument will be undefined and the second
38 a AnyEvent::XMPP::Error::IQ object.
39 join_room ($con, $jid, $nick, %args)
41 This method joins a room.
42 $con should be the AnyEvent::XMPP::IM::Connection object that is to
44 be used to send the necessary stanzas. $jid should be the bare JID
45 of the room. $nick should be your desired nickname in the room.
46 When you successfully entered the room a "enter" event is emitted.
48 In case you created the room, and it is locked, a "locked" event is
49 emitted. Please look in the "EVENTS" section below for more
50 details about how to handle "locked" rooms. (You won't have to care
51 about locked rooms if you didn't disable the "create_instant" flag
52 in %args).
53 If an error occurred and we couldn't join the room, the first two
55 arguments are undef and the third is a AnyEvent::XMPP::Error::MUC
56 object signalling the error.
57 %args hash can contain one of the following keys:
59 timeout => $timeout_in_secs
61 This is the timeout for joining the room. The default timeout
62 is 60 seconds if the timeout is not specified.
63 history => {}
65 Manage MUC-history from XEP-0045 (7.1.16) Hash can contain of
66 the following keys: "chars", "stanzas", "seconds"
67 Example:
69 history => {chars => 0} # don't load history
71 history => {stanzas => 3} # load last 3 history elements
72 history => {seconds => 300, chars => 500}
73 # load history in last 5 minutes, but max 500 characters
74 TODO: add "since" attributes
76 create_instant => $bool
78 If you set $bool to a true value we try to establish an instant
79 room on joining if it doesn't already exist.
80 XXX XXX XXX XXX XXX XXX XXX XXX XXX XXX XXX XXX
82 The default for this flag is true! So if you want to create an
84 reserved room with custom creation in the beginning you have to
85 pass a false value as $bool.
86 PLEASE NOTE: If you set $bool to a false value you have to
88 check the "did_create_room" status flag on your own instance of
89 AnyEvent::XMPP::Ext::MUC::User (provided as the second argument
90 to the callback) to see whether you need to finish room
91 creation! If you don't do this the room may stay LOCKED for
92 ever.
93 See also the "make_instant" and "request_configuration" methods
95 of AnyEvent::XMPP::Ext::MUC.
96 password => $password
98 The password for the room.
99 nickcollision_cb => $cb
101 If the join to the room results in a nickname collision the $cb
102 will be called with the nickname that collided and the return
103 value will be used as alternate nickname and the join is
104 retried.
105 This function is called everytime the nickname collides on
107 join, so you should take care of possible endless retries.
108 get_room ($con, $jid)
110 This returns the AnyEvent::XMPP::Ext::MUC::Room object for the bare
111 part of the $jid if we are joining or have joined such a room.
112 If we are not joined undef is returned.
114 get_rooms ($con)
116 Returns a list of AnyEvent::XMPP::Ext::MUC::Room objects for the
117 connection $con.
118
120 These are the events that are issued by this MUC extension:
121 $room is the AnyEvent::XMPP::Ext::MUC::Room object which the event
123 belongs to.
124 message => $room, $msg, $is_echo
126 This event is emitted when a message was received from the room.
127 $msg is a AnyEvent::XMPP::Ext::MUC::Message object and $is_echo is
128 true if the message is an echo.
129 NOTE: Please note that some conferences send messages already
131 before you have finished joining a room. That means that you might
132 already get a "message" event for a room that you haven't got an
133 "enter" for event yet. That means that methods like "get_me" might
134 return undef.
135 subject_change => $room, $msg, $is_echo
137 This event is emitted when a user changes the room subject. $msg
138 is a AnyEvent::XMPP::Ext::MUC::Message object and $is_echo is true
139 if the message is an echo.
140 The room subject is the subject of that $msg.
142 subject_change_error => $room, $error
144 If you weren't allowed to change the subject or some other error
145 occurred you will receive this event. $error is a
146 AnyEvent::XMPP::Error::MUC object.
147 error => $room, $error
149 This event is emitted when any error occurred. $error is a
150 AnyEvent::XMPP::Error::MUC object.
151 join_error => $room, $error
153 This event is emitted when a error occurred when joining a room.
154 $error is a AnyEvent::XMPP::Error::MUC object.
155 locked => $room
157 This event is emitted when you disabled the 'create_instant' flag
158 when calling "join_room". It means that you just created a new
159 room, which is locked. You need to configure it before it is
160 unlocked and others can enter.
161 Please consult the methods "make_instant", "request_configuration"
163 and "send_configuration" of AnyEvent::XMPP::Ext::MUC::Room for more
164 information about how to configure a room.
165 NOTE: You won't get another event when you finished configuring the
167 room, so you maybe want to call this on the
168 "AnyEvent::XMPP::Ext::MUC" object when you finished configuring the
169 room successfully:
170 $muc->event (enter => $room, $room->get_me);
172 That could be helpful if you want to place some generic stuff in
174 your "enter" event handlers.
175 NOTE2: If you didn't disable the "create_instant" flag of
177 "join_room" you won't have to care about a "locked" event, as
178 everything will be internally handled for you and you will get an
179 "enter" event if the room is finally setted up.
180 enter => $room, $user
182 This event is emitted when we successfully joined the room. $user
183 is a AnyEvent::XMPP::Ext::MUC::User object which is the user handle
184 for ourself.
185 join => $room, $user
187 This event is emitted when a new user joins the room. $user is the
188 AnyEvent::XMPP::Ext::MUC::User object of that user.
189 nick_change => $room, $user, $oldnick, $newnick
191 This event is emitted when a user changed his nickname. $user is
192 the AnyEvent::XMPP::Ext::MUC::User object of that user. $oldnick
193 is the old nickname and $newnick is the new nickname.
194 presence => $room, $user
196 This event is emitted when a user changes it's presence status (eg.
197 affiliation or role, or away status). $user is the
198 AnyEvent::XMPP::Ext::MUC::User object of that user.
199 part => $room, $user
201 This event is emitted when a user leaves the channel. $user is the
202 AnyEvent::XMPP::Ext::MUC::User of that user, but please note that
203 you shouldn't send any messages to this user anymore.
204 leave => $room, $user
206 This event is emitted when we leave the room. $user is your
207 AnyEvent::XMPP::Ext::MUC::User handle.
208
210 Robin Redeker, "<elmex at ta-sa.org>", JID: "<elmex at jabber.org>"
211
213 Copyright 2007, 2008 Robin Redeker, all rights reserved.
214 This program is free software; you can redistribute it and/or modify it
216 under the same terms as Perl itself.
217perl v5.38.0 2023-07-20 AnyEvent::XMPP::Ext::MUC(3)