/*
 * SIP Communicator, the OpenSource Java VoIP and Instant Messaging client.
 *
 * Distributable under LGPL license.
 * See terms of license at gnu.org.
 */
package net.java.sip.communicator.service.protocol;

import java.util.*;

import net.java.sip.communicator.service.protocol.event.*;

/**
 * Allows creating, configuring, joining and administering of individual
 * text-based ad-hoc conference rooms.
 *
 * @author Valentin Martinet
 */
public interface OperationSetAdHocMultiUserChat
    extends OperationSet
{
    /**
     * Creates an ad-hoc room with the named <tt>adHocRoomName</tt> and 
     * according to the specified <tt>adHocRoomProperties</tt>. When the method
     * returns the ad-hoc room the local user will not have joined it and thus 
     * will not receive messages on it until the <tt>AdHocChatRoom.join()</tt> 
     * method is called.
     * <p>
     * 
     * @param adHocRoomName
     *            the name of the <tt>AdHocChatRoom</tt> to create.
     * @param adHocRoomProperties
     *            properties specifying how the ad-hoc room should be created;
     *            <tt>null</tt> for no properties just like an empty
     *            <code>Map</code>
     * @throws OperationFailedException
     *             if the ad-hoc room couldn't be created for some reason.
     * @throws OperationNotSupportedException
     *             if chat room creation is not supported by this server
     * 
     * @return the newly created <tt>AdHocChatRoom</tt> named <tt>roomName</tt>.
     */
    public AdHocChatRoom createAdHocChatRoom(String adHocRoomName, 
                                   Map<String, Object> adHocRoomProperties)
        throws OperationFailedException, OperationNotSupportedException;

    /**
     * Creates an ad-hoc room with the named <tt>adHocRoomName</tt> and in 
     * including to the specified <tt>contacts</tt>. When the method
     * returns the ad-hoc room the local user will not have joined it and thus 
     * will not receive messages on it until the <tt>AdHocChatRoom.join()</tt> 
     * method is called.
     * <p>
     * 
     * @param adHocRoomName
     *            the name of the <tt>AdHocChatRoom</tt> to create.
     * @param contacts
     *            the contacts who are added to the room when it's created;
     *            <tt>null</tt> for no contacts
     * @throws OperationFailedException
     *             if the ad-hoc room couldn't be created for some reason.
     * @throws OperationNotSupportedException
     *             if chat room creation is not supported by this server
     * 
     * @return the newly created <tt>AdHocChatRoom</tt> named <tt>roomName</tt>.
     */
    public AdHocChatRoom createAdHocChatRoom(String adHocRoomName, 
                                   List<Contact> contacts)
        throws OperationFailedException, OperationNotSupportedException;

    /**
     * Returns a list of all currently joined <tt>AdHocChatRoom</tt>-s.
     *
     * @return a list of all currently joined <tt>AdHocChatRoom</tt>-s
     */
    public List<AdHocChatRoom> getAdHocChatRooms();

    /**
     * Adds a listener that will be notified of changes in our participation in
     * an ad-hoc chat room such as us being joined, left.
     *
     * @param listener a local user participation listener.
     */
    public void addPresenceListener(
        LocalUserAdHocChatRoomPresenceListener listener);

    /**
     * Removes a listener that was being notified of changes in our
     * participation in an ad-hoc room such as us being joined, left.
     * 
     * @param listener a local user participation listener.
     */
    public void removePresenceListener(
        LocalUserAdHocChatRoomPresenceListener listener);

    /**
     * Adds the given <tt>listener</tt> to the list of
     * <tt>AdHocChatRoomInvitationListener</tt>-s that would be notified when
     * an add-hoc chat room invitation has been received.
     *
     * @param listener the <tt>AdHocChatRoomInvitationListener</tt> to add
     */
    public void addInvitationListener(AdHocChatRoomInvitationListener listener);

    /**
     * Removes <tt>listener</tt> from the list of invitation listeners
     * registered to receive invitation events.
     *
     * @param listener the invitation listener to remove.
     */
     public void removeInvitationListener(
         AdHocChatRoomInvitationListener listener);

    /**
     * Adds the given <tt>listener</tt> to the list of
     * <tt>AdHocChatRoomInvitationRejectionListener</tt>-s that would be
     * notified when an add-hoc chat room invitation has been rejected.
     *
     * @param listener the <tt>AdHocChatRoomInvitationListener</tt> to add
     */
    public void addInvitationRejectionListener(
            AdHocChatRoomInvitationRejectionListener listener);

    /**
     * Removes the given listener from the list of invitation listeners
     * registered to receive events every time an invitation has been rejected.
     *
     * @param listener the invitation listener to remove.
     */
    public void removeInvitationRejectionListener(
        AdHocChatRoomInvitationRejectionListener listener);

    /**
     * Informs the sender of an invitation that we decline their invitation.
     *
     * @param invitation the invitation we are rejecting.
     * @param rejectReason the reason to reject the invitation (optional)
     */
    public void rejectInvitation(   AdHocChatRoomInvitation invitation,
                                    String rejectReason);
}

@@ -717,36 +717,32 @@
 local user will 
-not 
 have joined it a
@@ -743,122 +743,8 @@
 d it
- and thus %0A     * will not receive messages on it until the %3Ctt%3EAdHocChatRoom.join()%3C/tt%3E %0A     * method is called
 .%0A  
@@ -1753,24 +1753,62 @@
 ontacts%3C/tt%3E
+ for the given %3Ctt%3Ereason%0A     * %3C/tt%3E
 . When the m
@@ -1804,39 +1804,32 @@
  When the method
-%0A     *
  returns the ad-
@@ -1861,17 +1861,21 @@
 ill 
-not 
 have 
+%0A     * 
 join
@@ -1883,122 +1883,8 @@
 d it
- and thus %0A     * will not receive messages on it until the %3Ctt%3EAdHocChatRoom.join()%3C/tt%3E %0A     * method is called
 .%0A  
@@ -2139,24 +2139,76 @@
 no contacts%0A
+     * @param reason the reason for this invitation%0A
      * @thro
@@ -2586,32 +2586,32 @@
 adHocRoomName, %0A
-
                 
@@ -2651,16 +2651,31 @@
 contacts
+, String reason
 )%0A      

Support for invitation reason Yahoo! & ICQ), updated comments.