ECLStartNotify Class

ECLStartNotify is an abstract base class. An application cannot create an instance of this class directly. To use this class, the application must define its own class which is derived from ECLStartNotify. The application must implement the NotifyEvent() member function in its derived class. It may also optionally implement NotifyError() and NotifyStop() member functions.

The ECLStartNotify class is used to allow an application to be notified of the starting and stopping of ZIEWin connections. Start/stop events are generated whenever a ZIEWin connection (window) is started or stopped by any means, including the ECLConnMgr start/stop methods.

To be notified of start/stop events, the application must perform the following steps:

Define a class derived from ECLStartNotify.
Implement the derived class and implement the NotifyEvent() member function.
Optionally implement the NotifyError() and/or NotifyStop() functions.
Create an instance of the derived class.
Register the instance with the ECLConnMgr::RegisterStartEvent() function.

The example shown demonstrates how this may be done. When the above steps are complete, each time a connection is started or stopped the applications NotifyEvent() member function will be called. The function is passed two parameters giving the handle of the connection, and a BOOL start/stop indicator. The application may perform any functions required in the NotifyEvent() procedure, including calling other ECL functions. Note that the application cannot prevent the stopping of a connection; the notification is made after the session is already stopped.

If an error is detected during event generation, the NotifyError() member function is called with an ECLErr object. Events may or may not continue to be generated after an error, depending on the nature of the error. When event generation terminates (either due to an error, by calling the ECLConnMgr::UnregisterStartEvent, or by destruction of the ECLConnMgr object) the NotifyStop() member function is called. However event notification is terminated, the NotifyStop() member function is always called, and the application object is unregistered.

If the application does not provide an implementation of the NotifyError() member function, the default implementation is used (a simple message box is displayed to the user). The application can override the default behavior by implementing the NotifyError() function in the applications derived class. Likewise, the default NotifyStop() function is used if the application does not provide this function (the default behavior is to do nothing).

Note that the application can also choose to provide its own constructor and destructor for the derived class. This can be useful if the application wants to store some instance-specific data in the class and pass that information as a parameter on the constructor. For example, the application may want to post a message to an application window when a start/stop event occurs. Rather than define the window handle as a global variable (so it would be visible to the NotifyEvent() function), the application can define a constructor for the class which takes the window handle and stores it in the class member data area.

The application must not destroy the notification object while it is registered to receive events.

Implementation Restriction:Currently, the ECLConnMgr object allows only one notification object to be registered for a start/stop event notification. The ECLConnMgr::RegisterStartEvent will throw an error if a notify object is already registered for that ECLConnMgr object.