/* -*- 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)
// 
// ============================================================================

#if !defined (_EVENT_COMM_IDL)
#define _EVENT_COMM_IDL

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

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

    string tag_;
    // Tag for the notification.

    any value_;
    // A notification can contain anything.

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

  interface Notification_Receiver
    // = TITLE
    //   Defines the interface for a <Notification_Receiver> of events.
    //   Note that all operations are <oneway> to avoid blocking.
  {
    void receive_notification (in Notification notification);
    // Inform the <Notification_Receiver> that <event> has occurred.

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

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

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

    void send_notification (in Notification notification);
    // Send the <Notification> to all the consumers who
    // have subscribed and who match the filtering criteria.

    void subscribe (in Notification_Receiver notification_receiver,
                    in string filtering_criteria);
    // Subscribe the <Notification_Receiver> 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 Notification_Receiver notification_receiver,
                      in string filtering_criteria);
    // Unsubscribe the <Notification_Receiver> that matches the
    // filtering criteria.  If <filtering_criteria> is "" then all
    // <Notification_Receivers> with the matching object reference are
    // removed.
  };
};

#endif /* _EVENT_COMM_IDL */