// Sample code file: ComListener.java

/*
   Copyright (c) 2000 Novell, Inc.  All Rights Reserved.

   THIS WORK IS SUBJECT TO U.S. AND INTERNATIONAL COPYRIGHT LAWS AND TREATIES. 
   USE AND REDISTRIBUTION OF THIS WORK IS SUBJECT TO THE LICENSE AGREEMENT 
   ACCOMPANYING THE SOFTWARE DEVELOPMENT KIT (SDK) THAT CONTAINS THIS WORK. 
   PURSUANT TO THE SDK LICENSE AGREEMENT, NOVELL HEREBY GRANTS TO DEVELOPER A 
   ROYALTY-FREE, NON-EXCLUSIVE LICENSE TO INCLUDE NOVELL'S SAMPLE CODE IN ITS 
   PRODUCT. NOVELL GRANTS DEVELOPER WORLDWIDE DISTRIBUTION RIGHTS TO MARKET, 
   DISTRIBUTE, OR SELL NOVELL'S SAMPLE CODE AS A COMPONENT OF DEVELOPER'S 
   PRODUCTS. NOVELL SHALL HAVE NO OBLIGATIONS TO DEVELOPER OR DEVELOPER'S 
   CUSTOMERS WITH RESPECT TO THIS CODE. 
*/
 


package com.novell.Chat;

//Java imports
import java.io.*;
import java.util.Vector;

/**
 * Defines the events that are raised by the Communications class.
 * Some of these events require return values.
 */
public interface ComListener
{
    /**
     * Called when a message is received.
     *
     * @param colorCode The code of the color to use for the name.
     * @param name The name of the user who sent the message.
     * @param message The message received.
     */
    public void messageReceived(int colorCode, String name, String message);
    
    /**
     * Called when a valid connection has been established. 
     * Once this event is raised, you can assume that the connection
     * is valid and has been approved by both sides.
     *
     * @param comm Reference to the Communications object that is handling the
     *             the connection.
     */
    public void connectionEstablished(Communications comm);    
    
    /**
     * Called when a valid connection has been established. 
     * Once this event is raised, you can assume that the connection
     * is valid and has been approved by both sides.
     *
     * @param comm Reference to the Communications object that is handling the
     *             the connection.
     */
    public void reConnectionEstablished(Communications comm, String oldKey);    
    
    /**
     * Requests the listener to verify the connection by checking the 
     * user's full name against the ipAddress.
     *
     * @param fullName The fullName of the user to check.
     * @param ipAddress The supposed IP Address of the user.
     * @return True if it verifies correctly.
     */
    public boolean verifyConnection(String fullName, String ipAddress);
    
    /**
     * Asks the listener if it accepts or rejects the connection.
     *
     * @param comm Reference to the connection.
     * @return -1 if it is to reject, >=0 for the color to use for the user name.
     */
    public int acceptConnection(Communications comm);
    
    /**
     * Called when the given connection is lost.
     *
     * @param comm Reference to the connection.
     */
    public void disconnected(Communications comm);
    
    /**
     * This is called when a user enters or leaves a chat room.
     * It is a request to update your user lists.
     *
     * @param comm Reference to the connection.
     */
    public void connectionUpdate(Communications comm);
    
    /**
     * Informs the listener of the current status of the connection.
     *
     * @param comm Reference to the connection.
     * @param message The status message.
     */
    public void comStatus(Communications comm, String message);
    
    /**
     * Informs the listener of errors that occur in the connection.
     *
     * @param comm Reference to the connection.
     * @param errorCode The error code constant.
     * @param message The error message.
     */
    public void comError(Communications comm, int errorCode, String message);
    
    /**
     * Raised when a request to transfer the server to this user to received.
     * Used only by Clients.
     *
     * @param startColor The color to start giving to new users for their user name.
     * @return True if successfull.
     */
    public boolean serverTransferRequest(int startColor);
    
    /**
     * Raised when a response is received to transfer the server.
     * Used only by Servers.
     *
     * @param accepted True if the request was accepted.
     */
    public void serverTransferResponse(boolean accepted);
    
    /**
     * Raised when a client must change which server it is connected to.
     *
     * @param roomFullName The fullname of the Chat Room.
     */   
    public void changeServer(String roomFullName);
    
    /**
     * Raised when a server should echo a message to the other clients.
     *
     * @param data The message to echo.
     */
    public boolean echoData(String data);
    
    /**
         * Called to stop the connection.
         */
    public void disconnect();
    
    /**
         * Called to stop the connection and close the socket with a specific client.
         *
         * @param key The (IP:Port) key of the client to disconnect.
         */
    public void disconnect(String key);
    
    /**
     * @return The owners name of the Chat Room.
     */
    public String getOwnerName();
    
    /**
         * Called to stop the connection and close the socket.
         */
    public void close();
}