1AnyEvent::XMPP::Ext::MUUCs(e3r)Contributed Perl DocumentAantyiEovnent::XMPP::Ext::MUC(3)
2
3
4

NAME

6       AnyEvent::XMPP::Ext::MUC - Implements XEP-0045: Multi-User Chat
7

SYNOPSIS

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

DESCRIPTION

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
19       This extension requires the AnyEvent::XMPP::Ext::Disco extension for
20       service discovery.
21

METHODS

23       new This is the constructor for a MUC extension object.  It takes no
24           further arguments.
25
26       is_conference ($con, $jid, $cb)
27           TODO
28
29       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
34           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
40       join_room ($con, $jid, $nick, %args)
41           This method joins a room.
42
43           $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
47           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
54           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
58           %args hash can contain one of the following keys:
59
60           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
64           history => {}
65               Manage MUC-history from XEP-0045 (7.1.16) Hash can contain of
66               the following keys: "chars", "stanzas", "seconds"
67
68               Example:
69
70                       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
75               TODO: add "since" attributes
76
77           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
81               XXX XXX XXX XXX XXX XXX XXX XXX XXX XXX XXX XXX
82
83               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
87               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
94               See also the "make_instant" and "request_configuration" methods
95               of AnyEvent::XMPP::Ext::MUC.
96
97           password => $password
98               The password for the room.
99
100           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
106               This function is called everytime the nickname collides on
107               join, so you should take care of possible endless retries.
108
109       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
113           If we are not joined undef is returned.
114
115       get_rooms ($con)
116           Returns a list of AnyEvent::XMPP::Ext::MUC::Room objects for the
117           connection $con.
118

EVENTS

120       These are the events that are issued by this MUC extension:
121
122       $room is the AnyEvent::XMPP::Ext::MUC::Room object which the event
123       belongs to.
124
125       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
130           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
136       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
141           The room subject is the subject of that $msg.
142
143       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
148       error => $room, $error
149           This event is emitted when any error occurred.  $error is a
150           AnyEvent::XMPP::Error::MUC object.
151
152       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
156       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
162           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
166           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
171              $muc->event (enter => $room, $room->get_me);
172
173           That could be helpful if you want to place some generic stuff in
174           your "enter" event handlers.
175
176           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
181       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
186       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
190       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
195       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
200       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
205       leave => $room, $user
206           This event is emitted when we leave the room. $user is your
207           AnyEvent::XMPP::Ext::MUC::User handle.
208

AUTHOR

210       Robin Redeker, "<elmex at ta-sa.org>", JID: "<elmex at jabber.org>"
211
213       Copyright 2007, 2008 Robin Redeker, all rights reserved.
214
215       This program is free software; you can redistribute it and/or modify it
216       under the same terms as Perl itself.
217
218
219
220perl v5.38.0                      2023-07-20       AnyEvent::XMPP::Ext::MUC(3)
Impressum