Programming Reference: ODDSEventMgr

# Programming Reference

## ODDSEventMgr

Class Definition File | ODDSEMgr.idl
Class C++ Binding | ODDSEMgr.xh

Class Hierarchy

    SOMObject
       ODDSEventMgr

Description

The ODDSEventMgr class is the base class for managing events. It supplies methods for handling the events for an event set. This class is intended to be subclassed, but it provides methods that the containing object could invoke events generically. The actual method call should be defined in the subclass.

The responsibilities of the event class are:

- Maintain a list of ODDSSinks that have requested notification. Methods for adding, removing, and obtaining an enumerator are provided.
- Maintain a unique identifier to identify the event set, supplied by the constructor.
- Maintain a reference to its ODDSConnection object.
- Provide methods to allow its container to iterate over the list of ODDSSinks to issue method calls directly. This is accomplished by using the PrepareEventFiring, FireEvent, and StopEventFiring methods.

Constructor | This constructor should be used instead of the default constructor to set the guid.

Signature

    ODDSEventMgr (ODGUID guid)

Parameters

guid (ODGUID) - input

  An event manager unique identifier.

Methods

The methods defined by the ODDSConnection class include:

- AddSink
- CreateSinkEnum
- FireEvent
- PrepareEventFiring
- RemoveSink
- SinkIsConnected
- StopEventFiring

Overridden Methods | There are no methods overridden by the ODDSEventMgr class.

### AddSink

This method verifies that the ID of the sink matches the ID of the event manager and adds a reference to the sink to the event manager sink list.

Signature

    long AddSink (ODDSSink *sink)

Parameters

sink (ODDSSink *) - input

  A reference to a sink.

Returns

- ODDS_ERROR_INVALID_PARAMETER
- ODDS_ERROR_SINK_DUPLICATE
- ODDS_ERROR_ODGUID_NOT_SUPPORTED

Remarks

This method verifies that the ID of the sink matches the ID of the event manager and adds a reference to the sink to the event manager sink list. A sink object can only be added to the event manager sink list once.

Exception Handling

- ODDS_ERROR_OUTOFMEMORY
- ODDS_ERROR_MUTEX_FAILED

Related Methods

- ODDSConnection::AddSink
- ODDSEventMgr::RemoveSink

### CreateSinkEnum

This method accesses sinks connected to the event manager.

Signature

    long CreateSinkEnum (ODDSSinkEnum **sink)

Parameters

sink (ODDSSinkEnum **) - output

  A reference to a sink enumerator reference. A sink enumeration is created and returned.

Returns

- ODDS_ERROR_INVALID_PARAMETER
- ODDS_ERROR_SINK_DUPLICATE
- ODDS_ERROR_NO_SINKS

Remarks

This method returns an object that can be used to access the sinks connected to this event manager.

Exception Handling

- ODDS_ERROR_MUTEX_FAILED

### FireEvent

This method invokes ODDSSink's FireEvent on the next sink in the enumerator.

Signature

    long FireEvent (ODDSSinkEnum *sink,
                    string eventName,
                    _IDL_SEQUENCE_any *inputParms,
                    long *result)

Parameters

sink (ODDSSinkEnum *) - input

  A reference to a sink enumerator reference obtained by the PrepareEventFiring. An invalid parameter error is returned if the enumerator is not obtained by the PrepareEventFiring method.

eventName (ODDSSinkEnum *) - input

  A reference to a null-terminated string of characters giving the method name to call for notification of the event. The method's parameters must be placed in the inputParms field.

inputParms (_IDL_SEQUENCE_any *) - in/out

  A reference to a sequence of anys. Each any contains an input or output parameter for the method named by the eventName parameter.

result (long *) - output

  A reference to a long in which the result is returned from the method call named by the eventName parameter.

Returns

- ODDS_ERROR_INVALID_PARAMETER
- ODDS_ERROR_END_RANGE
- ODDS_ERROR_INVALID_CURSOR

Remarks

This method invokes ODDSSink's FireEvent on the next sink in the enumerator. If all sinks have been previously called, returns an error.

Exception Handling

- ODDS_ERROR_OUTOFMEMORY
- ODDS_ERROR_MUTEX_FAILED

Related Methods

- ODDSEventMgr::PrepareEventFiring
- ODDSEventMgr::StopEventFiring

### PrepareEventFiring

This method sets up a sink enumerator for calling sinks to notify them of an event.

Signature

    long PrepareEventFiring (long *numberOfSinks,
                             ODDSSinkEnum **sinks)

Parameters

numberOfSinks (long *) - output

  A reference to a count of the number of sinks in the event manager sink list.

sinks (ODDSSinkEnum **) - output

  A reference to a sink enumerator reference. A sink enumeration is created and returned. This reference must be passed to FireEvent and StopEventFiring.

Returns

- ODDS_ERROR_INVALID_PARAMETER
- ODDS_ERROR_NO_SINKS

Remarks

This method sets up a sink enumerator for calling sinks to notify them of an event. Each subsequent call to FireEvent will increment the enumerator's cursor to notify the next sink.

Exception Handling

- ODDS_ERROR_OUTOFMEMORY
- ODDS_ERROR_MUTEX_FAILED

Related Methods

- ODDSEventMgr::FireEvent
- ODDSEventMgr::StopEventFiring

### RemoveSink

This method removes a reference to the sink from the event manager sink list.

Signature

    long RemoveSink (ODGUID *id)

Parameters

id (ODGUID *) - input

  An unique identifier of an event manager.

Returns

- ODDS_ERROR_INVALID_PARAMETER

Remarks

This method removes the reference to the sink form the event manager sink list.

Exception Handling

- ODDS_ERROR_MUTEX_FAILED

Related Methods

- ODDSEventMgr::AddSink

### SinkIsConnected

This method determines if a sink is connected to an event manager sink list.

Signature

    Boolean SinkIsConnected (ODDSSink *sink)

Parameters

sink (ODDSSink *) - input

  A reference to an ODDSSink object.

Returns

rv (long) - returns

  Returns true if the sink is on the event manager sink list; otherwise, returns false.

Remarks

This method determines if the sink is on the event manager sink list. If the sink is connected, returns a Boolean true; otherwise, returns a Boolean false.

Exception Handling

- ODDS_ERROR_INVALID_PARAMETER
- ODDS_ERROR_MUTEX_FAILED

Related Methods

- ODDSEventMgr::AddSink

### StopEventFiring

This method frees the event enumerator obtained by the PrepareEventFiring method.

Signature

    long StopEventFiring (ODDSSinkEnum *sink)

Parameters

sink (ODDSSinkEnum *) - input

  A reference to an sink enumerator reference obtained by the PrepareEventFiring method. An invalid parameter error is returned if the enumerator is not obtained by PrepareEventFiring.

Returns

- ODDS_ERROR_INVALID_PARAMETER

Remarks

This method frees the sink enumerator obtained by the PrepareEventFiring method.

Exception Handling

- ODDS_ERROR_MUTEX_FAILED

Related Methods

- ODDSEventMgr::FireEvent
- ODDSEventMgr::PrepareEventFiring

[ Top | Previous | Next | Contents | Index | Documentation Homepage ]