// **********************************************************************
//
// Copyright (c) 1999
// Object Oriented Concepts, Inc.
// Billerica, MA, USA
//
// All Rights Reserved
//
// **********************************************************************

#ifndef BROADCASTER_IDL
#define BROADCASTER_IDL

#include <Receiver.idl>

/**
 *
 * An interface which is used to broadcast messages to multiple
 * receivers.
 *
 * This interface must be implemented by the chat server. It provides
 * operations for connecting and disconnecting chat clients
 * (i.e. receivers). It also provides operations that chat clients can
 * use to send messages to all other connected clients.
 *
 * @see Receiver
 *
 **/

interface Broadcaster
{
    /**
     *
     * A struct that describes receivers.
     *
     * @member receiver The receiver.
     *
     * @member id The receiver's user id.
     *
     * @member host The receiver's host name.
     *
     * @member nick The receiver's nick name.
     *
     **/

    struct ReceiverDescription
    {
	Receiver receiver;
	string id;
	string host;
	string nick;
    };

    /**
     *
     * A sequence of receiver descriptions.
     *
     **/
     
    typedef sequence<ReceiverDescription> ReceiverDescSeq;

    /**
     *
     * A sequence of strings.
     *
     **/
     
    typedef sequence<string> StringSeq;

    /**
     *
     * This exception is raised if a receiver is unreachable, e.g. due
     * to firewalls or name server problems.
     *
     **/

    exception ReceiverUnreachable { };

    /**
     *
     * This exception is raised if a receiver tries to register more
     * than once.
     *
     **/

    exception AlreadyRegistered { };

    /**
     *
     * This exception is raised if a receiver is not connected.
     *
     **/

    exception UnknownReceiver { };

    /**
     *
     * This exception is raised if a nick name cannot be used because
     * that nick name is already used by some other user.
     *
     **/

    exception NickExists { };

    /**
     *
     * This exception is raised if a nick name is unknown.
     *
     **/

    exception UnknownNick { };

    /**
     *
     * Register a receiver (chat client).
     *
     * Chat clients must use this function to register with the chat
     * server (broadcaster) in order to receive messages from
     * the chat server.
     *
     * @param receiver The receiver which wants to register itself.
     *
     * @param id The receiver's user id.
     *
     * @param host The receiver's host name.
     *
     * @param nick The receiver's nick name.
     *
     * @exception AlreadyRegistered Raised if a receiver tries to
     * register more than once.
     *
     * @exception NickExists Raised if the requested nick name is
     * already in use.
     *
     **/

    void register(in Receiver receiver, in string id, in string host,
		  in string nick)
	raises(AlreadyRegistered, NickExists);

    /**
     *
     * Register a receiver (chat client) with callback check.
     *
     * This operations behaves like <code>register</code>, except that
     * it tries to call back the receiver and throws a
     * <code>ReceiverUnreachable</code> exception if it can't reach
     * the receiver, for example due to firewall or nameserver
     * problems.
     *
     * @param receiver The receiver which wants to register itself.
     *
     * @param id The receiver's user id.
     *
     * @param host The receiver's host name.
     *
     * @param nick The receiver's nick name.
     *
     * @exception ReceiverUnreachable Raised if for some reason the
     * chat server cannot call back to the chat client.
     *
     * @exception AlreadyRegistered Raised if a receiver tries to
     * register more than once.
     *
     * @exception NickExists Raised if the requested nick name is
     * already in use.
     *
     **/

    void registerWithCheck(in Receiver receiver, in string id, in string host,
			   in string nick)
	raises(ReceiverUnreachable, AlreadyRegistered, NickExists);

    /**
     *
     * Unregister a receiver (chat client).
     *
     * Chat clients must use this function to unregister with the chat
     * server (broadcaster) before they disconnect.
     *
     * @param receiver The receiver which wants to register itself.
     *
     * @exception UnknownReceiver Raised if the receiver is not
     * registered.
     *
     **/

    void unregister(in Receiver receiver)
	raises(UnknownReceiver);

    /**
     *
     * Set a receiver's nick name.
     *
     * @param receiver The receiver which wants to set its nick name.
     *
     * @param nick The nick name.
     *
     * @exception UnknownReceiver Raised if the receiver is not
     * registered.
     *
     * @exception NickExists Raised if the requested nick name is
     * already in use.
     *
     **/

    void setNickName(in Receiver receiver, in string nick)
	raises(UnknownReceiver, NickExists);

    /**
     *
     * Set a receiver description by its nick name.
     *
     * @param nick The nick name.
     *
     * @param desc The receiver description.
     *
     * @exception UnknownNick Raised if the nick name is not known.
     *
     **/

    void getReceiverByNick(in string nick, out ReceiverDescription desc)
	raises(UnknownNick);

    /**
     *
     * Get all receiver names.
     *
     * @return A string sequence containing all receiver names.
     *
     **/

    StringSeq getReceiverNames();

    /**
     *
     * Say something to all registered chat clients (receivers).
     *
     * @param text The message text.
     *
     **/

    void say(in string text);
};

#endif
