// **********************************************************************
//
// Copyright (c) 2002
// IONA Technologies, Inc.
// Waltham, MA, USA
//
// All Rights Reserved
//
// **********************************************************************

#ifndef OCI_IDL
#define OCI_IDL

/**
 *
 * The Open Communications Interface (OCI). The definitions in this
 * module provide a uniform interface to network protocols. This
 * allows for easy plug-in of new protocols or other communication
 * mechanisms into ORBs that implement the OCI. Furthermore, protocol
 * implementations need only to be written once and can then be reused
 * with all OCI compliant ORBs. For more information, please see the
 * OCI documentation.
 *
 **/

#include <OB/OCIClient.idl>
#include <OB/Current.idl>

#pragma prefix "ooc.com"

module OCI
{

/* AcceptorInfo forward declaration */
local interface AcceptorInfo;

/* AccFactoryInfo forward declaration */
local interface AccFactoryInfo;

/**
 *
 * An interface for an Acceptor object, which is used by CORBA
 * servers to accept client connection requests. It also provides
 * operations for the management of IOR profiles.
 *
 * @see AccRegistry
 * @see AccFactory
 * @see Transport
 *
 **/
 
local interface Acceptor
{
    /** The plugin id. */
    readonly attribute PluginId id;

    /** The profile id tag. */
    readonly attribute ProfileId tag;

    /**
     *
     * The "handle" for this Acceptor. Like with the handle for
     * Transports, the handle may <em>only</em> be used with
     * operations like <code>select()</code>. A handle value of -1
     * indicates that the protocol plug-in does not support
     * "selectable" Transports.
     *
     **/

    readonly attribute OCI::Handle handle;

    /**
     *
     * Closes the Acceptor. <code>accept</code> or <code>listen</code>
     * may not be called after <code>close</code> has been called.
     *
     * @exception COMM_FAILURE In case of an error.
     *
     **/

    void close();

    /**
     *
     * Shutdown the Acceptor. After shutdown, the socket will not
     * listen to further connection requests.
     *
     * @exception COMM_FAILURE In case of an error.
     *
     **/

    void shutdown();

    /**
     *
     * Sets the acceptor up to listen for incoming connections. Until
     * this method is called on the acceptor, new connection requests
     * should result in a connection request failure.
     * 
     * @exception COMM_FAILURE In case of an error.
     *
     **/

    void listen();
    
    /**
     *
     * Used by CORBA servers to accept client connection requests. It
     * returns a Transport object, which can be used for sending and
     * receiving octet streams to and from the client.
     *
     * @param block If set to <code>TRUE</code>, the operation blocks
     * until a new connection has been accepted. If set to
     * <code>FALSE</code>, the operation returns a nil object
     * reference if there is no new connection ready to be accepted.
     *
     * @return The new Transport object.
     *
     * @exception COMM_FAILURE In case of an error.
     *
     **/

    Transport accept(in boolean block);

    /**
     *
     * Connect to this acceptor. This operation can be used to unblock
     * threads that are blocking in <code>accept</code>.
     *
     * @return The new Transport object.
     *
     * @exception TRANSIENT If the server cannot be contacted.
     * @exception COMM_FAILURE In case of other errors.
     *
     **/

    Transport connect_self();

    /**
     *
     * Add new profiles that match this Acceptor to an IOR.
     *
     * @param profile_info The basic profile information to use for
     * the new profiles.
     *
     * @param ref The IOR.
     *
     **/

    void add_profiles(in ProfileInfo profile_info, inout IOR ref);

    /**
     *
     * From the given IOR, get basic information about all profiles
     * for which are local to this Acceptor.
     *
     * @param ref The IOR from which the profiles are taken.
     *
     * @return The sequence of basic information about profiles. If
     * this sequence is empty, there is no profile in the IOR that
     * is local to the Acceptor.
     *
     **/

    ProfileInfoSeq get_local_profiles(in IOR ref);

     /**
      *
      * Returns the information object associated with
      * the Acceptor.
      *
      * @return The Acceptor information object.
      *
      **/

    AcceptorInfo get_info();
};

/** Alias for a sequence of Acceptors. */
typedef sequence< Acceptor > AcceptorSeq;

/* AcceptCB forward declaration */
local interface AcceptCB;

/**
 *
 * Information on an OCI Acceptor object. Objects of this type must be
 * narrowed to an Acceptor information object for a concrete protocol
 * implementation, for example to <code>OCI::IIOP::AcceptorInfo</code>
 * in case the plug-in implements IIOP.
 *
 * @see Acceptor
 *
 **/

local interface AcceptorInfo
{
    /** The plugin id. */
    readonly attribute PluginId id;

    /** The profile id tag. */
    readonly attribute ProfileId tag;

    /**
     *
     * Returns a human readable description of the transport.
     *
     * @return The description.
     *
     **/

    string describe();

    /**
     *
     * Add a callback that is called whenever a new connection is
     * accepted. If the callback has already been registered, this
     * method has no effect.
     *
     * @param cb The callback to add.
     *
     **/

    void add_accept_cb(in AcceptCB cb);

    /**
     *
     * Remove an accept callback. If the callback was not registered,
     * this method has no effect.
     *
     * @param cb The callback to remove.
     *
     **/

    void remove_accept_cb(in AcceptCB cb);
};

/**
 *
 * An interface for an accept callback object.
 *
 * @see AcceptorInfo
 *
 **/

local interface AcceptCB
{
    /**
     *
     * Called after a new connection has been accepted. If the
     * application wishes to reject the connection
     * <code>CORBA::NO_PERMISSION</code> may be raised.
     *
     * @param transport_info The TransportInfo for the new connection.
     *
     **/

    void accept_cb(in TransportInfo transport_info);
};

/** Alias for a sequence of accept callback objects. */
typedef sequence< AcceptCB > AcceptCBSeq;

/**
 *
 * A parameter is invalid.
 *
 * @member reason A description of the error.
 *
 **/

exception InvalidParam
{
    string reason;
};

/**
 *
 * An interface for an AccFactory object, which is used by CORBA
 * servers to create Acceptors.
 *
 * @see Acceptor
 * @see AccFactoryRegistry
 *
 **/
 
local interface AccFactory
{
    /** The plugin id. */
    readonly attribute PluginId id;

    /** The profile id tag. */
    readonly attribute ProfileId tag;

    /**
     *
     * Create an Acceptor using the given configuration parameters.
     * Refer to the plug-in documentation for a description of the
     * configuration parameters supported for a particular protocol.
     *
     * @param params The configuration parameters.
     *
     * @return The new Acceptor.
     *
     * @exception InvalidParam If any of the parameters are invalid.
     *
     **/

    Acceptor create_acceptor(in ParamSeq params)
        raises(InvalidParam);

    /**
     *
     * Change the object-key in the IOR profile for this given
     * protocol.
     *
     * @param ior The IOR
     *
     * @param key The new object key
     *
     **/

    void change_key(inout IOP::IOR ior, in ObjectKey key);

    /**
     *
     * Returns the information object associated with the Acceptor
     * factory.
     *
     * @return The Acceptor
     *
     **/

    AccFactoryInfo get_info();
};

/** Alias for a sequence of AccFactory objects. */
typedef sequence< AccFactory > AccFactorySeq;

/**
 *
 * Information on an OCI AccFactory object.
 *
 * @see AccFactory
 *
 **/

local interface AccFactoryInfo
{
    /** The plugin id. */
    readonly attribute PluginId id;

    /** The profile id tag. */
    readonly attribute ProfileId tag;

    /**
     *
     * Returns a human readable description of the transport.
     *
     * @return The description.
     *
     **/

    string describe();
};

/**
 *
 * A registry for Acceptor factories.
 *
 * @see Acceptor
 * @see AccFactory
 *
 **/

local interface AccFactoryRegistry
{
    /**
     *
     * Adds an Acceptor factory to the registry.
     *
     * @param factory The Acceptor factory to add.
     *
     * @exception FactoryAlreadyExists If a factory already exists with the
     * same plugin id as the given factory.
     *
     **/

    void add_factory(in AccFactory _factory)
        raises(FactoryAlreadyExists);

    /**
     *
     * Returns the factory with the given plugin id.
     *
     * @param id The plugin id.
     *
     * @return The Acceptor factory.
     *
     * @exception NoSuchFactory If no factory was found with a matching
     * plugin id.
     *
     **/

    AccFactory get_factory(in PluginId id)
        raises(NoSuchFactory);

    /**
     *
     * Returns all registered factories.
     *
     * @return The Acceptor factories.
     *
     **/

    AccFactorySeq get_factories();
};

/**
 *
 * Interface to access Transport and Acceptor information objects
 * related to the current request.
 *
 **/

local interface Current : CORBA::Current
{
    /**
     *
     * This method returns the Transport information object for the
     * Transport used to invoke the current request.
     *
     * @returns The Transport information object.
     *
     **/
    
    TransportInfo get_oci_transport_info();
    
    /**
     *
     * This method returns the Acceptor information object for the
     * Acceptor which created the Transport used to invoke the current
     * request.
     *
     * @returns The Acceptor information object.
     *
     **/
    
    AcceptorInfo get_oci_acceptor_info();
};

}; // End module OCI

#endif
