Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
AnyEvent::XMPP::Ext::MUser)Contributed Perl DocumenAnyEvent::XMPP::Ext::MUC(3)

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

	  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));

       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.

       new This	is the constructor for a MUC extension object.	It takes no
	   further arguments.

       is_conference ($con, $jid, $cb)

       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"


		       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.


	       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

	       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

	       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.

       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.

       Robin Redeker, "<elmex at>", JID: "<elmex at>"

       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.32.0			  2012-12-25	   AnyEvent::XMPP::Ext::MUC(3)


Want to link to this manual page? Use this URL:

home | help