/* -*- C++ -*- */
// $Id$

// ============================================================================
//
// = LIBRARY
//    EventComm
//
// = FILENAME
//    Event_Comm.idl
//
// = DESCRIPTION
//    The CORBA IDL module for distributed event notification.
//
// = AUTHOR
//    Douglas C. Schmidt (schmidt@cs.wustl.edu) and
//    Pradeep Gore (pradeep@cs.wustl.edu)
//
// ============================================================================

#if !defined (_EVENT_COMM_IDL)
#define _EVENT_COMM_IDL

module Event_Comm
{
  // = TITLE
  //   The CORBA IDL module for distributed event notification.

  struct Event
  {
    // = TITLE
    //   Defines the interface for an event <Event>.
    //
    // = DESCRIPTION
    //   This is the type passed by the Notifier to the Consumer.
    //   Since it contains an <any>, it can hold any type.  Naturally,
    //   the consumer must understand how to interpret this!

    string tag_;
    // Tag for the event.  This is used by the <Notifier> to compare
    // with the <Consumer>s' filtering criteria.

    any value_;
    // An event can contain anything.

    Object object_ref_;
    // Object reference for callbacks.
  };

  interface Consumer
  {
    // = TITLE
    //   Defines the interface for a <Consumer> of events.

    void push (in Event event_instance);
    // Inform the <Consumer> that <event> has occurred.

    void disconnect (in string reason);
    // Disconnect the <Consumer> from the <Notifier>,
    // giving it the <reason>.
  };

  interface Notifier
  {
    // = TITLE
    //   Defines the interface for a <Notifier> of events.

    exception CannotSubscribe
    {
      // = TITLE
      //   This exception in thrown when a <subscribe> fails.

      string reason_;
    };

    exception CannotUnsubscribe
    {
      // = TITLE
      //   This exception in thrown when a <unsubscribe> fails.

      string reason_;
    };

    // = The following operations are intended for Suppliers.

    void disconnect (in string reason);
    // Disconnect all the receivers, giving them the <reason>.

    void push (in Event event_instance);
    // Send the <event> to all the consumers who have subscribed and
    // who match the filtering criteria.

    // = The following operations are intended for Consumers.

    void subscribe (in Consumer subscriber,
                    in string filtering_criteria) raises (CannotSubscribe);
    // Subscribe the <Consumer> to receive events that match the
    // regular expresssion <filtering_criteria> applied by the
    // <Notifier>.  If <filtering_criteria> is "" then all events are
    // matched.

    void unsubscribe (in Consumer unsubscriber,
                      in string filtering_criteria) raises (CannotUnsubscribe);
    // Unsubscribe the <Consumer> that matches the filtering criteria.
    // If <filtering_criteria> is "" then all <Consumers> with the
    // matching object reference are removed.
  };
};

#endif /* _EVENT_COMM_IDL */