diff options
Diffstat (limited to 'TAO/orbsvcs/orbsvcs/CosEventComm.idl')
-rw-r--r-- | TAO/orbsvcs/orbsvcs/CosEventComm.idl | 177 |
1 files changed, 177 insertions, 0 deletions
diff --git a/TAO/orbsvcs/orbsvcs/CosEventComm.idl b/TAO/orbsvcs/orbsvcs/CosEventComm.idl new file mode 100644 index 00000000000..e97413fa618 --- /dev/null +++ b/TAO/orbsvcs/orbsvcs/CosEventComm.idl @@ -0,0 +1,177 @@ +/** + * @file CosEventComm.idl + * + * @brief Define the CosEventComm module + * + * $Id$ + * + * 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 attemps 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 */ |