Provided by: libanyevent-xmpp-perl_0.55-6_all 
NAME
AnyEvent::XMPP::Ext::MUC - Implements XEP-0045: Multi-User Chat
SYNOPSIS
my $con = AnyEvent::XMPP::Connection->new (...);
$con->add_extension (my $disco = AnyEvent::XMPP::Ext::Disco->new);
$con->add_extension (my $muc = AnyEvent::XMPP::Ext::MUC->new (disco => $disco));
...
DESCRIPTION
This module handles multi user chats and provides new events to catch multi user chat messages. It
intercepts messages from the connection so they don't interfere with your other callbacks on the
connection.
This extension requires the AnyEvent::XMPP::Ext::Disco extension for service discovery.
METHODS
new This is the constructor for a MUC extension object. It takes no further arguments.
is_conference ($con, $jid, $cb)
TODO
is_room ($con, $jid, $cb)
This method sends a information discovery to the $jid, via the connection $con. $cb is called when
the information arrives or with an error after the usual IQ timeout.
When the $jid was a room $cb is called with the first argument being a
AnyEvent::XMPP::Ext::MUC::RoomInfo object. If the destination wasn't reachable, the room doesn't
exist or some other error happened the first argument will be undefined and the second a
AnyEvent::XMPP::Error::IQ object.
join_room ($con, $jid, $nick, %args)
This method joins a room.
$con should be the AnyEvent::XMPP::IM::Connection object that is to be used to send the necessary
stanzas. $jid should be the bare JID of the room. $nick should be your desired nickname in the
room.
When you successfully entered the room a "enter" event is emitted. In case you created the room, and
it is locked, a "locked" event is emitted. Please look in the "EVENTS" section below for more
details about how to handle "locked" rooms. (You won't have to care about locked rooms if you didn't
disable the "create_instant" flag in %args).
If an error occurred and we couldn't join the room, the first two arguments are undef and the third
is a AnyEvent::XMPP::Error::MUC object signalling the error.
%args hash can contain one of the following keys:
timeout => $timeout_in_secs
This is the timeout for joining the room. The default timeout is 60 seconds if the timeout is
not specified.
history => {}
Manage MUC-history from XEP-0045 (7.1.16) Hash can contain of the following keys: "chars",
"stanzas", "seconds"
Example:
history => {chars => 0} # don't load history
history => {stanzas => 3} # load last 3 history elements
history => {seconds => 300, chars => 500}
# load history in last 5 minutes, but max 500 characters
TODO: add "since" attributes
create_instant => $bool
If you set $bool to a true value we try to establish an instant room on joining if it doesn't
already exist.
XXX XXX XXX XXX XXX XXX XXX XXX XXX XXX XXX XXX
The default for this flag is true! So if you want to create an reserved room with custom creation
in the beginning you have to pass a false value as $bool.
PLEASE NOTE: If you set $bool to a false value you have to check the "did_create_room" status
flag on your own instance of AnyEvent::XMPP::Ext::MUC::User (provided as the second argument to
the callback) to see whether you need to finish room creation! If you don't do this the room may
stay LOCKED for ever.
See also the "make_instant" and "request_configuration" methods of AnyEvent::XMPP::Ext::MUC.
password => $password
The password for the room.
nickcollision_cb => $cb
If the join to the room results in a nickname collision the $cb will be called with the nickname
that collided and the return value will be used as alternate nickname and the join is retried.
This function is called everytime the nickname collides on join, so you should take care of
possible endless retries.
get_room ($con, $jid)
This returns the AnyEvent::XMPP::Ext::MUC::Room object for the bare part of the $jid if we are
joining or have joined such a room.
If we are not joined undef is returned.
get_rooms ($con)
Returns a list of AnyEvent::XMPP::Ext::MUC::Room objects for the connection $con.
EVENTS
These are the events that are issued by this MUC extension:
$room is the AnyEvent::XMPP::Ext::MUC::Room object which the event belongs to.
message => $room, $msg, $is_echo
This event is emitted when a message was received from the room. $msg is a
AnyEvent::XMPP::Ext::MUC::Message object and $is_echo is true if the message is an echo.
NOTE: Please note that some conferences send messages already before you have finished joining a
room. That means that you might already get a "message" event for a room that you haven't got an
"enter" for event yet. That means that methods like "get_me" might return undef.
subject_change => $room, $msg, $is_echo
This event is emitted when a user changes the room subject. $msg is a
AnyEvent::XMPP::Ext::MUC::Message object and $is_echo is true if the message is an echo.
The room subject is the subject of that $msg.
subject_change_error => $room, $error
If you weren't allowed to change the subject or some other error occurred you will receive this
event. $error is a AnyEvent::XMPP::Error::MUC object.
error => $room, $error
This event is emitted when any error occurred. $error is a AnyEvent::XMPP::Error::MUC object.
join_error => $room, $error
This event is emitted when a error occurred when joining a room. $error is a
AnyEvent::XMPP::Error::MUC object.
locked => $room
This event is emitted when you disabled the 'create_instant' flag when calling "join_room". It means
that you just created a new room, which is locked. You need to configure it before it is unlocked and
others can enter.
Please consult the methods "make_instant", "request_configuration" and "send_configuration" of
AnyEvent::XMPP::Ext::MUC::Room for more information about how to configure a room.
NOTE: You won't get another event when you finished configuring the room, so you maybe want to call
this on the "AnyEvent::XMPP::Ext::MUC" object when you finished configuring the room successfully:
$muc->event (enter => $room, $room->get_me);
That could be helpful if you want to place some generic stuff in your "enter" event handlers.
NOTE2: If you didn't disable the "create_instant" flag of "join_room" you won't have to care about a
"locked" event, as everything will be internally handled for you and you will get an "enter" event if
the room is finally setted up.
enter => $room, $user
This event is emitted when we successfully joined the room. $user is a
AnyEvent::XMPP::Ext::MUC::User object which is the user handle for ourself.
join => $room, $user
This event is emitted when a new user joins the room. $user is the AnyEvent::XMPP::Ext::MUC::User
object of that user.
nick_change => $room, $user, $oldnick, $newnick
This event is emitted when a user changed his nickname. $user is the AnyEvent::XMPP::Ext::MUC::User
object of that user. $oldnick is the old nickname and $newnick is the new nickname.
presence => $room, $user
This event is emitted when a user changes it's presence status (eg. affiliation or role, or away
status). $user is the AnyEvent::XMPP::Ext::MUC::User object of that user.
part => $room, $user
This event is emitted when a user leaves the channel. $user is the AnyEvent::XMPP::Ext::MUC::User of
that user, but please note that you shouldn't send any messages to this user anymore.
leave => $room, $user
This event is emitted when we leave the room. $user is your AnyEvent::XMPP::Ext::MUC::User handle.
AUTHOR
Robin Redeker, "<elmex at ta-sa.org>", JID: "<elmex at jabber.org>"
COPYRIGHT & LICENSE
Copyright 2007, 2008 Robin Redeker, all rights reserved.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl
itself.
perl v5.36.0 2022-12-06 AnyEvent::XMPP::Ext::MUC(3pm)