/**
 * @file CosEventComm.idl
 *
 * @brief Define the CosEventComm module
 *
 * Described in CORBAservices: Common Object Services Specification,
 * chapter 4.
 *
 * CosEventComm Module, page 4-8 includes the following interfaces:
 * PushConsumer, PushSupplier, PullSupplier, PullConsumer
 *
 * The Event service IDL can be downloaded from
 * ftp://www.omg.org/pub/docs/formal/97-11-02.idl
 *
 * The complete specification is available from:
 * http://www.omg.org/technology/documents/formal/event_service.htm
 *
 * @author Pradeep Gore <pradeep@cs.wustl.edu>
 */

#ifndef TAO_EVENTCOMM_IDL
#define TAO_EVENTCOMM_IDL

#pragma prefix "omg.org"

/**
 * @namespace CosEventComm
 *
 * @brief Define the interfaces implemented by users of the CORBA
 * Event Service.
 */
module CosEventComm
{
  /**
   * @exception Disconnected
   *
   * @brief Exception raised when a client tries to communicate with
   * the Event Service after it has disconnected.
   *
   * The exception is raised if:
   *
   * - If supplier tries to push an event before fully connecting to
   *   the EC.
   * - A consumer tries to pull an event before fully connecting to
   *   the EC.
   */
  exception Disconnected {};

  /**
   * @interface PushConsumer
   *
   * @brief Define the interface implemented by push-style consumers
   *
   * A push-style consumer passively receives events from the Event
   * Service.  Applications simply implement this interface, connect
   * to the Event Service and receive events.
   */
  interface PushConsumer
  {
    /// Receive one event from the Consumer's peer.
    /**
     * A supplier communicates event data to the consumer by
     * invoking the push operation.
     * @param data The event
     * @throws CosEventComm::Disconnected if the object considers
     *   itself no longer connected to its peer.
     */
    void push (in any data) raises (Disconnected);

    /// The peer has disconnected from the PushConsumer.
    /**
     * The disconnect_push_consumer operation indicates that the peer
     * has disconnected, for example, because it has been destroyed.
     * The application can safely release all resources attached to
     * this consumer and destroy it, no further push() calls should be
     * expected.
     */
    void disconnect_push_consumer ();
  };

  /**
   * @interface PushSupplier
   *
   * @brief Define the interface implemented by push-style suppliers.
   *
   * A push-style supplier actively pushes events into the Event
   * Service
   */
  interface PushSupplier
  {
    /// The peer has disconnected from the push-style supplier
    /**
     * The disconnect_push_supplier operation indicates that the peer
     * has disconnected, for example, because it has been destroyed.
     * The application can safe release all resource attached to this
     * supplier and destroy it, further attempts to push events into
     * its peer will fail.
     */
    void disconnect_push_supplier ();
  };

  /**
   * @interface PullConsumer
   *
   * @brief Define the interface implemented by pull-style consumers
   *
   * A pull-style consumer actively queries the Event Channel for
   * events.
   */
  interface PullConsumer
  {
    /// The peer has disconnected from the pull-style consumer.
    /**
     * The disconnect_pull_consumer operation indicates that the peer
     * has disconnected, for example, because it has been destroyed.
     * The application can safely release all resources attached to
     * this consumer and destroy it, any attempts to pull more data
     * should fail.
     */
    void disconnect_pull_consumer ();
  };

  /**
   * @interface PullSupplier
   *
   * @brief Define the interface implemented by pull-style suppliers.
   *
   * A pull-style supplier passively generates events for the Event
   * Service
   */
  interface PullSupplier
  {
    /// Pull (blocking) one event from the supplier.
    /**
     * The pull operation should block until the next event becomes
     * available.
     * @return The next event
     * @throws CosEventComm::Disconnected if the object considers
     *   itself no longer connected to its peer.
     */
    any pull () raises (Disconnected);

    /// Pull (non-blocking) one event from the supplier.
    /**
     * The try_pull operation does not block: if the event data is
     * available, it returns the event data and sets the has_event
     * parameter to true; if the event is not available, it sets the
     * has_event parameter to false and the event data is returned
     * as long with an undefined value.
     *
     * @param has_event Set to TRUE if there was another event
     *   available, FALSE otherwise.
     * @return The next event if one was available, an any containing
     *   a 'long' with an undefined value otherwise.
     * @throws CosEventComm::Disconnected if the object considers
     *   itself no longer connected to its peer.
     */
    any try_pull (out boolean has_event) raises (Disconnected);

    /// The peer has disconnected from the pull-style supplier.
    /**
     * The disconnect_pull_supplier operation indicates that the peer
     * has disconnected, for example, because it has been destroyed.
     * The application can safe release all resource attached to this
     * supplier and destroy it, the peer should not make any attempts
     * to pull more data after this request.
     */
    void disconnect_pull_supplier ();
  };

};

#pragma prefix ""

#endif /* TAO_EVENTCOMM_IDL */