view release on metacpan or  search on metacpan

lib/AnyEvent/XMPP/Ext/MUC.pm  view on Meta::CPAN

C<$con> should be the L<AnyEvent::XMPP::IM::Connection> object that
is to be used to send the necessary stanzas.
C<$jid> should be the bare JID of the room.
C<$nick> should be your desired nickname in the room.

When you successfully entered the room a C<enter> event is emitted.  In case
you created the room, and it is locked, a C<locked> event is emitted.  Please
look in the C<EVENTS> section below for more details about how to handle
C<locked> rooms. (You won't have to care about locked rooms if you
didn't disable the C<create_instant> flag in C<%args>).

If an error occurred and we couldn't join the room, the first two arguments are
undef and the third is a L<AnyEvent::XMPP::Error::MUC> object signalling the error.

C<%args> hash can contain one of the following keys:

=over 4

=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.

=item history => {}

Manage MUC-history from XEP-0045 (7.1.16)
Hash can contain of the following keys: C<chars>, C<stanzas>, C<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 C<since> attributes

=item create_instant => $bool

If you set C<$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 C<$bool>.

B<PLEASE NOTE:> If you set C<$bool> to a B<false> value you have to check the
C<did_create_room> status flag on your own instance of
L<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 B<may stay LOCKED for ever>.

See also the C<make_instant> and C<request_configuration> methods of
L<AnyEvent::XMPP::Ext::MUC>.

=item password => $password

The password for the room.

=item nickcollision_cb => $cb

If the join to the room results in a nickname collision the C<$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 I<everytime> the nickname collides on join, so you
should take care of possible endless retries.

=back

=cut

sub join_room {
   my ($self, $con, $jid, $nick, %args) = @_;

   unless (exists $args{create_instant}) {
      $args{create_instant} = 1;
   }

   my $timeout = $args{timeout} || $self->{join_timeout};

   my $room = $self->install_room ($con, $jid);

   $room->{locked_cb} =
      $args{create_instant} ? sub {
         my ($room) = @_;

         $room->make_instant (sub {
            my ($room, $error) = @_;

            if ($error) {
               $self->event (join_error => $room, $error);
            } else {
               $self->event (enter => $room, $room->get_me);
            }
         });
      } : undef;

   $room->{room_join_timer} =
      AnyEvent->timer (after => $timeout, cb => sub {
         delete $room->{room_join_timer};
         $self->uninstall_room ($con, $room);

         my $muce = AnyEvent::XMPP::Error::MUC->new (
            type => 'join_timeout',
            text => "Couldn't join room in time, timeout after $timeout\n"
         );
         
         $self->event (join_error => $room, $muce);
      });

   my $rcb_id;
   $rcb_id = $self->reg_cb (
      join_error => sub {
         my ($muc, $eroom, $error) = @_;
         return unless cmp_jid ($eroom->nick_jid, $room->nick_jid);

         if ($error->type eq 'nickname_in_use'
             && exists $args{nickcollision_cb}) {

            $nick = $args{nickcollision_cb}->($nick);
            $room->send_join ($nick, $args{password}, $args{history});
            return;
         }

         delete $room->{room_join_timer};
         $self->uninstall_room ($con, $room);
         $muc->unreg_cb ($rcb_id);
      },
      enter => sub {
         my ($muc, $eroom, $user) = @_;
         return unless cmp_jid ($eroom->nick_jid, $room->nick_jid);

         delete $room->{room_join_timer};
         $muc->unreg_cb ($rcb_id);
      }
   );

   $room->send_join ($nick, $args{password}, $args{history});
}

sub install_room {
   my ($self, $con, $room_jid) = @_;

   my $room
      = $self->{rooms}->{stringprep_jid $con->jid}->{prep_bare_jid $room_jid}
         = AnyEvent::XMPP::Ext::MUC::Room->new (
            muc        => $self,
            connection => $con,
            jid        => $room_jid
         );

   $room
}

sub uninstall_room {
   my ($self, $con, $room) = @_;
   my $r =
      delete $self->{rooms}->{stringprep_jid $con->jid}->{prep_bare_jid $room->jid};
   delete $r->{muc};
}

=item B<get_room ($con, $jid)>

This returns the L<AnyEvent::XMPP::Ext::MUC::Room> object
for the bare part of the C<$jid> if we are joining or have
joined such a room.

If we are not joined undef is returned.

=cut

sub get_room {
   my ($self, $con, $jid) = @_;
   $self->{rooms}->{stringprep_jid $con->jid}->{prep_bare_jid $jid}
}

=item B<get_rooms ($con)>

Returns a list of L<AnyEvent::XMPP::Ext::MUC::Room> objects
for the connection C<$con>.

=cut

sub get_rooms {
   my ($self, $con) = @_;
   values %{$self->{rooms}->{stringprep_jid $con->jid} || {}}
}

=back

=head1 EVENTS

These are the events that are issued by this MUC extension:

C<$room> is the L<AnyEvent::XMPP::Ext::MUC::Room> object which
the event belongs to.

=over 4