ECS_Engine

- Interface to an ECS engine

SYNOPSIS

#include <ECS/Engine.hh>
class ECS_Engine
{
  public:
	_ECSAIO_PRIVAPI ECS_Engine(int32 engineId);
	_ECSAIO_PRIVAPI ECS_Engine(ECS_Engine const& other);
	_ECSAIO_PRIVAPI ECS_Engine const& operator=(ECS_Engine const& other);
	_ECSAIO_PRIVAPI virtual ~ECS_Engine();
	virtual bool isValid() const;
	virtual ostream& print(ostream& os) const;
	_ECSAIO_PRIVAPI int32 processEvent
	 (
	   const ECS_Event& event,
	   const char* streamName = 0
	 );
	_ECSAIO_PRIVAPI int32 getInstanceId();
	_ECSAIO_PRIVAPI int32 nEventReceivers();
	_ECSAIO_PRIVAPI ECS_EventReceiver* getNthEventReceiver
	 (int32 index);
	_ECSAIO_PRIVAPI int32 addEventReceiver(ECS_EventReceiver& receiver);
	_ECSAIO_PRIVAPI int32 removeEventReceiver(ECS_EventReceiver& receiver);
	_ECSAIO_PRIVAPI int32 removeAllEventReceivers();
	_ECSAIO_PRIVAPI int32 nAnnotaters();
	_ECSAIO_PRIVAPI ECS_Annotater* getNthAnnotater(int32 index);
	_ECSAIO_PRIVAPI int32 addAnnotater(ECS_Annotater& annotater);
	_ECSAIO_PRIVAPI int32 removeAnnotater(ECS_Annotater& annotater);
	_ECSAIO_PRIVAPI int32 removeAllAnnotaters();
};

CLASS TYPE

Concrete

AUDIENCE

ECS Developers

DESCRIPTION

This is the class to be used for programmatic interaction with an ECS engine.

This is the class to use to send events to an engine and to register classes to receive events which are output by an engine, and to handle annotation requests.

Constructors and Destructors

_ECSAIO_PRIVAPI ECS_Engine(int32 engineId);: The default constructor
_ECSAIO_PRIVAPI ECS_Engine(ECS_Engine const& other);: The copy constructor
_ECSAIO_PRIVAPI ECS_Engine const& operator=(ECS_Engine const& other);: The assignment operator
_ECSAIO_PRIVAPI virtual ~ECS_Engine();: The destructor

Utility

virtual bool isValid() const;

Test that this class refers to a valid engine

virtual ostream& print(ostream& os) const;

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

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

Send an event to the engine on stream streamName (default 0).

Note: Sending an event requires all events/requests in the queue to be processed. Callbacks may occur to instances of ECS_Annotater or ECS_EventReceiver before this method returns.

Returns

ECS_SUCCESS

The event was sent to the engine, no errors were detected.

ECS_AIO_TYPE1_PREEMPTION_OCCURED

The event was sent to the engine, but communication with another engine had to be terminated to free resources to do it.

This is a positive return code and does not necessarily indicate a problem. However, there is an overhead involved in establishing and terminating connection with an engine. If this return occurs frequently and performance is an issue then you may want to consider restructuring your application into separate processes.

ECS_AIO_TYPE2_PREEMPTION_OCCURED

The event was sent to the engine, but a connection for event transmission of events to another engine has to be terminated to free resources to do it.

This is a similar error to the above, however it is slightly less serious. In this case, it is the number of receivers that is causing a problem. Each receiver registered consumes a channel for transmission of events between the engine and this process. The number of these connections is limited. If multiple receivers are registered for another engine there may not be any connections left to use for sending the event to this engine.

This status indicates that the API has found another unused event connection and has closed it so that one could be opened to this engine.

ECS_AIO_INVALID

This object does not reference a valid engine. Either the instance Id specified is invalid, or the process is out of memory

ECS_AIO_ENGINE_LIMIT_REACHED

The process has already established connections with the maximum number of engines.

ECS_AIO_TOO_MANY_RECEIVERS

All event connections are already in use by receivers registered with other engines.

ESOK_COMMUNICATION_ERROR

Communications error, this error may be transient and recoverable.

ECS_BAD_PARAMETER

The PDU is invalid

EIO_NULL_CHR

Event PDU contains NULL (00) characters. These characters are not valid in MDL events.

_ECSAIO_PRIVAPI int32 getInstanceId();

Returns the numeric instance identifier of this engine.

_ECSAIO_PRIVAPI int32 nEventReceivers();

Returns the number of event receivers that have been registered with this engine by this process.

_ECSAIO_PRIVAPI ECS_EventReceiver* getNthEventReceiver(int32 index);

Returns a pointer to theindexth event receiver registered with this class.

The first receiver has an index of 1. If an invalid index is specified then 0 will be returned.

Receivers are not stored in insertion order. The order of the iteration may change if receivers are added or removed.

_ECSAIO_PRIVAPI int32 addEventReceiver(ECS_EventReceiver& receiver);

Specify an instance of ECS_EventReceiver (or subclass) to receive events output from this engine.

Multiple event receivers may be registered. There is a limit dictated by the engine and underlying communication mechanism.

Returns

ECS_SUCCESS: The receiver has been registered with the engine, no errors were detected.
ECS_AIO_TYPE1_PREEMPTION_OCCURED: The event was sent to the engine, but communication with another engine had to be terminated to free resources to do it.
This is a positive return code and does not necessarily indicate a problem. However further interaction with that engine will not be possible until all the receivers associated with another engine are removed.
ECS_AIO_TYPE2_PREEMPTION_OCCURED: The event was sent to the engine, but communication of events with another engine had to be terminated to free resources to do it.
This is a similar error to ECS_AIO_TYPE1_PREEMPTION_OCCURED, however in this case it will still be possible to process annotation requests from that engine.
ECS_AIO_INVALID: This object does not reference a valid engine. Either the instance Id specified is invalid, or the process is out of memory.
ECS_AIO_ENGINE_LIMIT_REACHED: The process has already established connections with the maximum number of engines.
ECS_AIO_TOO_MANY_RECEIVERS: All event connections are already in use by receivers registered with other engines.
ESOK_COMMUNICATION_ERROR: Communications error, this error may be transient and recoverable.

_ECSAIO_PRIVAPI int32 removeEventReceiver(ECS_EventReceiver& receiver);

Remove the registration of an event receiver from this engine.

_ECSAIO_PRIVAPI int32 removeAllEventReceivers();

Removes the registration of all event receivers registered with this engine.

Following this call all events output by this engine will be ignored until at least one new event receiver is registered.

_ECSAIO_PRIVAPI int32 nAnnotaters();

Returns the number of annotater objects that have been registered with this engine by this process.

_ECSAIO_PRIVAPI ECS_Annotater* getNthAnnotater(int32 index);

Returns a pointer to the instance of an ECS_Annotater subclass to which is registered to process annotation requests from this engine.

_ECSAIO_PRIVAPI int32 addAnnotater(ECS_Annotater& annotater);

Specify an instance of an ECS_Annotater subclass to which annotation requests should be directed.

The first annotater has an index of 1. If an invalid index is specified then 0 will be returned.

Annotaters are not stored in insertion order. The order of the iteration may change if annotaters are added or removed.

_ECSAIO_PRIVAPI int32 removeAnnotater(ECS_Annotater& annotater);

Remove the annotater instance specified by annotater from the set of annotaters which handle requests from this engine.

_ECSAIO_PRIVAPI int32 removeAllAnnotaters();

Stop processing of annotation requests from this engine.

NOTES

None

LIBRARY

ECS

VERSION

1.5

DATE RELEASED

1998/02/25

AUTHOR(S)

Hewlett-Packard Company