ECS_EventReceiver

- Base class for receiving and processing events output by an engine

SYNOPSIS

#include <ECS/EventReceiver.hh>
class ECS_EventReceiver
{
 public:
	_ECSAIO_PRIVAPI ECS_EventReceiver();
	_ECSAIO_PRIVAPI ECS_EventReceiver(const ECS_EventFilter& filter);
	_ECSAIO_PRIVAPI virtual ~ECS_EventReceiver();
	_ECSAIO_PRIVAPI virtual ostream& print(ostream& os) const;
	_ECSAIO_PRIVAPI int32 connectToEngine(int32 instanceId);
	_ECSAIO_PRIVAPI int32 disconnectFromEngine(int32 instanceId);
	_ECSAIO_PRIVAPI ECS_EventFilter getFilter() const;
	_ECSAIO_PRIVAPI int32 setFilter(const ECS_EventFilter& filter);
	_ECSAIO_PRIVAPI int32 clearFilter();
	_ECSAIO_PRIVAPI virtual int32 handleEvent
	 (
	   const ECS_Event& event,
	   const char* streamName
	 ) = 0;
};

CLASS TYPE

Abstract Base

AUDIENCE

ECS Application Developers

DESCRIPTION

This class provides the interface to which all classes that register to receive events from an engine must conform.

It also provides some private methods used for management of the interface.

Application developers are expected to create a subclass of this class which overrides the method handleEvent() to provide the behavior that their application requires.

The events which are received by an instance of this class (or any subclass) can be constrained by applying a filter (see setFilter()).

It is recommended that the filter be set prior to adding the EventReceiver to the engine, otherwise unwanted events could be received if any events are output by the engine before the filter is set.

The filter will apply to the output of all engines with which the instance is registered. If multiple filters are required then separate instances must be used.

Example

ECS_EventFilter         filter1("mdl", "syntax1");
ECS_EventFilter         filter2("mdl", "syntax2");

ECS_EventReceiver       rec1;
ECS_EventReceiver       rec2;

rec1.setFilter(filter1);
rec1.setFilter(filter2);

ECS_Engine              engine(1);

engine.addEventReceiver(rec1);
engine.addEventReceiver(rec2);

ECS::mainloop();

rec1will receive events with event syntax "syntax1" and rec2 will receive events with "syntax2".

Constructors and Destructors

_ECSAIO_PRIVAPI ECS_EventReceiver();

The default constructor

_ECSAIO_PRIVAPI ECS_EventReceiver(const ECS_EventFilter& filter);

A constructor which allows the initial filter to be set

_ECSAIO_PRIVAPI virtual ~ECS_EventReceiver();

The destructor

Utility

_ECSAIO_PRIVAPI virtual ostream& print(ostream& os) const;

Prints a textual representation of the class to the output stream specified via os.

Engines

_ECSAIO_PRIVAPI int32 connectToEngine(int32 instanceId);

Register to receive events from the specified engine instance

_ECSAIO_PRIVAPI int32 disconnectFromEngine(int32 instanceId);

Stop receiving events from the specified engine instance

Filtering

_ECSAIO_PRIVAPI ECS_EventFilter getFilter() const;

Returns a copy of the filter which currently applies to this instance.

_ECSAIO_PRIVAPI int32 setFilter(const ECS_EventFilter& filter);

Set a filter for events to be received by this instance

The filter applies to all engines from which this instance of ECS_EventReceiver receives events.

_ECSAIO_PRIVAPI int32 clearFilter();

Remove the filter for events to be received by this instance

_ECSAIO_PRIVAPI virtual int32 handleEvent
(
const ECS_Event& event,
const char* streamName
) = 0;

Receive an event from the engine. The default implementation will print the event to standard output. Application developers should override this method in subclasses to provide appropriate handling.

NOTES

None

SEE ALSO

ECS_EventFilter

LIBRARY

ECS

VERSION

1.5

DATE RELEASED

1998/02/25

AUTHOR(S)

Hewlett-Packard Company

COPYRIGHT

Copyright (c) 1997 Hewlett-Packard Company. All Rights Reserved.