.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (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
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    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
.\" ========================================================================
.\"
.IX Title "AnyEvent::XMPP::Ext::MUC 3"
.TH AnyEvent::XMPP::Ext::MUC 3 2024-07-13 "perl v5.38.2" "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
AnyEvent::XMPP::Ext::MUC \- Implements XEP\-0045: Multi\-User Chat
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 4
\&   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));
\&   ...
.Ve
.SH DESCRIPTION
.IX Header "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.
.PP
This extension requires the AnyEvent::XMPP::Ext::Disco extension for service
discovery.
.SH METHODS
.IX Header "METHODS"
.IP \fBnew\fR 4
.IX Item "new"
This is the constructor for a MUC extension object.
It takes no further arguments.
.ie n .IP "\fBis_conference ($con, \fR\fB$jid\fR\fB, \fR\fB$cb\fR\fB)\fR" 4
.el .IP "\fBis_conference ($con, \fR\f(CB$jid\fR\fB, \fR\f(CB$cb\fR\fB)\fR" 4
.IX Item "is_conference ($con, $jid, $cb)"
TODO
.ie n .IP "\fBis_room ($con, \fR\fB$jid\fR\fB, \fR\fB$cb\fR\fB)\fR" 4
.el .IP "\fBis_room ($con, \fR\f(CB$jid\fR\fB, \fR\f(CB$cb\fR\fB)\fR" 4
.IX Item "is_room ($con, $jid, $cb)"
This method sends a information discovery to the \f(CW$jid\fR, via the connection
\&\f(CW$con\fR.  \f(CW$cb\fR is called when the information arrives or with an error after
the usual IQ timeout.
.Sp
When the \f(CW$jid\fR was a room \f(CW$cb\fR 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.
.ie n .IP "\fBjoin_room ($con, \fR\fB$jid\fR\fB, \fR\fB$nick\fR\fB, \fR\fB%args\fR\fB)\fR" 4
.el .IP "\fBjoin_room ($con, \fR\f(CB$jid\fR\fB, \fR\f(CB$nick\fR\fB, \fR\f(CB%args\fR\fB)\fR" 4
.IX Item "join_room ($con, $jid, $nick, %args)"
This method joins a room.
.Sp
\&\f(CW$con\fR should be the AnyEvent::XMPP::IM::Connection object that
is to be used to send the necessary stanzas.
\&\f(CW$jid\fR should be the bare JID of the room.
\&\f(CW$nick\fR should be your desired nickname in the room.
.Sp
When you successfully entered the room a \f(CW\*(C`enter\*(C'\fR event is emitted.  In case
you created the room, and it is locked, a \f(CW\*(C`locked\*(C'\fR event is emitted.  Please
look in the \f(CW\*(C`EVENTS\*(C'\fR section below for more details about how to handle
\&\f(CW\*(C`locked\*(C'\fR rooms. (You won't have to care about locked rooms if you
didn't disable the \f(CW\*(C`create_instant\*(C'\fR flag in \f(CW%args\fR).
.Sp
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.
.Sp
\&\f(CW%args\fR hash can contain one of the following keys:
.RS 4
.ie n .IP "timeout => $timeout_in_secs" 4
.el .IP "timeout => \f(CW$timeout_in_secs\fR" 4
.IX Item "timeout => $timeout_in_secs"
This is the timeout for joining the room.
The default timeout is 60 seconds if the timeout is not specified.
.IP "history => {}" 4
.IX Item "history => {}"
Manage MUC-history from XEP\-0045 (7.1.16)
Hash can contain of the following keys: \f(CW\*(C`chars\*(C'\fR, \f(CW\*(C`stanzas\*(C'\fR, \f(CW\*(C`seconds\*(C'\fR
.Sp
Example:
.Sp
.Vb 4
\&        history => {chars => 0} # don\*(Aqt 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
.Ve
.Sp
TODO: add \f(CW\*(C`since\*(C'\fR attributes
.ie n .IP "create_instant => $bool" 4
.el .IP "create_instant => \f(CW$bool\fR" 4
.IX Item "create_instant => $bool"
If you set \f(CW$bool\fR to a true value we try to establish an instant room
on joining if it doesn't already exist.
.Sp
XXX XXX XXX 
XXX XXX XXX 
XXX XXX XXX 
XXX XXX XXX
.Sp
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 \f(CW$bool\fR.
.Sp
\&\fBPLEASE NOTE:\fR If you set \f(CW$bool\fR to a \fBfalse\fR value you have to check the
\&\f(CW\*(C`did_create_room\*(C'\fR 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 \fBmay stay LOCKED for ever\fR.
.Sp
See also the \f(CW\*(C`make_instant\*(C'\fR and \f(CW\*(C`request_configuration\*(C'\fR methods of
AnyEvent::XMPP::Ext::MUC.
.ie n .IP "password => $password" 4
.el .IP "password => \f(CW$password\fR" 4
.IX Item "password => $password"
The password for the room.
.ie n .IP "nickcollision_cb => $cb" 4
.el .IP "nickcollision_cb => \f(CW$cb\fR" 4
.IX Item "nickcollision_cb => $cb"
If the join to the room results in a nickname collision the \f(CW$cb\fR
will be called with the nickname that collided and the return value will
be used as alternate nickname and the join is retried.
.Sp
This function is called \fIeverytime\fR the nickname collides on join, so you
should take care of possible endless retries.
.RE
.RS 4
.RE
.ie n .IP "\fBget_room ($con, \fR\fB$jid\fR\fB)\fR" 4
.el .IP "\fBget_room ($con, \fR\f(CB$jid\fR\fB)\fR" 4
.IX Item "get_room ($con, $jid)"
This returns the AnyEvent::XMPP::Ext::MUC::Room object
for the bare part of the \f(CW$jid\fR if we are joining or have
joined such a room.
.Sp
If we are not joined undef is returned.
.IP "\fBget_rooms ($con)\fR" 4
.IX Item "get_rooms ($con)"
Returns a list of AnyEvent::XMPP::Ext::MUC::Room objects
for the connection \f(CW$con\fR.
.SH EVENTS
.IX Header "EVENTS"
These are the events that are issued by this MUC extension:
.PP
\&\f(CW$room\fR is the AnyEvent::XMPP::Ext::MUC::Room object which
the event belongs to.
.ie n .IP "message => $room, $msg, $is_echo" 4
.el .IP "message => \f(CW$room\fR, \f(CW$msg\fR, \f(CW$is_echo\fR" 4
.IX Item "message => $room, $msg, $is_echo"
This event is emitted when a message was received from the room.
\&\f(CW$msg\fR is a AnyEvent::XMPP::Ext::MUC::Message object and \f(CW$is_echo\fR
is true if the message is an echo.
.Sp
\&\fBNOTE:\fR Please note that some conferences send messages already
before you have finished joining a room. That means that you might
already get a \f(CW\*(C`message\*(C'\fR event for a room that you haven't got an \f(CW\*(C`enter\*(C'\fR
for event yet. That means that methods like \f(CW\*(C`get_me\*(C'\fR might return undef.
.ie n .IP "subject_change => $room, $msg, $is_echo" 4
.el .IP "subject_change => \f(CW$room\fR, \f(CW$msg\fR, \f(CW$is_echo\fR" 4
.IX Item "subject_change => $room, $msg, $is_echo"
This event is emitted when a user changes the room subject.
\&\f(CW$msg\fR is a AnyEvent::XMPP::Ext::MUC::Message object and \f(CW$is_echo\fR
is true if the message is an echo.
.Sp
The room subject is the subject of that \f(CW$msg\fR.
.ie n .IP "subject_change_error => $room, $error" 4
.el .IP "subject_change_error => \f(CW$room\fR, \f(CW$error\fR" 4
.IX Item "subject_change_error => $room, $error"
If you weren't allowed to change the subject or some other error
occurred you will receive this event.
\&\f(CW$error\fR is a AnyEvent::XMPP::Error::MUC object.
.ie n .IP "error => $room, $error" 4
.el .IP "error => \f(CW$room\fR, \f(CW$error\fR" 4
.IX Item "error => $room, $error"
This event is emitted when any error occurred.
\&\f(CW$error\fR is a AnyEvent::XMPP::Error::MUC object.
.ie n .IP "join_error => $room, $error" 4
.el .IP "join_error => \f(CW$room\fR, \f(CW$error\fR" 4
.IX Item "join_error => $room, $error"
This event is emitted when a error occurred when joining a room.
\&\f(CW$error\fR is a AnyEvent::XMPP::Error::MUC object.
.ie n .IP "locked => $room" 4
.el .IP "locked => \f(CW$room\fR" 4
.IX Item "locked => $room"
This event is emitted when you disabled the 'create_instant'
flag when calling \f(CW\*(C`join_room\*(C'\fR. 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.
.Sp
Please consult the methods \f(CW\*(C`make_instant\*(C'\fR, \f(CW\*(C`request_configuration\*(C'\fR and
\&\f(CW\*(C`send_configuration\*(C'\fR of AnyEvent::XMPP::Ext::MUC::Room for more information
about how to configure a room.
.Sp
\&\fBNOTE:\fR You won't get another event when you finished configuring the room, so
you maybe want to call this on the \f(CW\*(C`AnyEvent::XMPP::Ext::MUC\*(C'\fR object when you
finished configuring the room successfully:
.Sp
.Vb 1
\&   $muc\->event (enter => $room, $room\->get_me);
.Ve
.Sp
That could be helpful if you want to place some generic
stuff in your \f(CW\*(C`enter\*(C'\fR event handlers.
.Sp
\&\fBNOTE2:\fR If you didn't disable the \f(CW\*(C`create_instant\*(C'\fR flag of \f(CW\*(C`join_room\*(C'\fR you
won't have to care about a \f(CW\*(C`locked\*(C'\fR event, as everything will be internally
handled for you and you will get an \f(CW\*(C`enter\*(C'\fR event if the room is finally
setted up.
.ie n .IP "enter => $room, $user" 4
.el .IP "enter => \f(CW$room\fR, \f(CW$user\fR" 4
.IX Item "enter => $room, $user"
This event is emitted when we successfully joined the room.
\&\f(CW$user\fR is a AnyEvent::XMPP::Ext::MUC::User object which is
the user handle for ourself.
.ie n .IP "join => $room, $user" 4
.el .IP "join => \f(CW$room\fR, \f(CW$user\fR" 4
.IX Item "join => $room, $user"
This event is emitted when a new user joins the room.
\&\f(CW$user\fR is the AnyEvent::XMPP::Ext::MUC::User object of that user.
.ie n .IP "nick_change => $room, $user, $oldnick, $newnick" 4
.el .IP "nick_change => \f(CW$room\fR, \f(CW$user\fR, \f(CW$oldnick\fR, \f(CW$newnick\fR" 4
.IX Item "nick_change => $room, $user, $oldnick, $newnick"
This event is emitted when a user changed his nickname.
\&\f(CW$user\fR is the AnyEvent::XMPP::Ext::MUC::User object of that user.
\&\f(CW$oldnick\fR is the old nickname and \f(CW$newnick\fR is the new nickname.
.ie n .IP "presence => $room, $user" 4
.el .IP "presence => \f(CW$room\fR, \f(CW$user\fR" 4
.IX Item "presence => $room, $user"
This event is emitted when a user changes it's presence status
(eg. affiliation or role, or away status).
\&\f(CW$user\fR is the AnyEvent::XMPP::Ext::MUC::User object of that user.
.ie n .IP "part => $room, $user" 4
.el .IP "part => \f(CW$room\fR, \f(CW$user\fR" 4
.IX Item "part => $room, $user"
This event is emitted when a user leaves the channel.  \f(CW$user\fR is the
AnyEvent::XMPP::Ext::MUC::User of that user, but please note that you shouldn't
send any messages to this user anymore.
.ie n .IP "leave => $room, $user" 4
.el .IP "leave => \f(CW$room\fR, \f(CW$user\fR" 4
.IX Item "leave => $room, $user"
This event is emitted when we leave the room. \f(CW$user\fR is your
AnyEvent::XMPP::Ext::MUC::User handle.
.SH AUTHOR
.IX Header "AUTHOR"
Robin Redeker, \f(CW\*(C`<elmex at ta\-sa.org>\*(C'\fR, JID: \f(CW\*(C`<elmex at jabber.org>\*(C'\fR
.SH "COPYRIGHT & LICENSE"
.IX Header "COPYRIGHT & LICENSE"
Copyright 2007, 2008 Robin Redeker, all rights reserved.
.PP
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.