ECLCommNotify Class
ECLCommNotify 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 ECLCommNotify. The application must implement the NotifyEvent() member function in its derived class. It may also optionally implement NotifyError() and NotifyStop() member functions.
The ECLCommNotify class is used to allow an application to be notified of communications connect/disconnect events on a ZIEWin connection. Connect/disconnect events are generated whenever a ZIEWin connection (window) is connected or disconnected from a host system.
- Define a class derived from ECLCommNotify.
- Implement the derived class and implement the NotifyEvent() member function.
- Optionally implement the NotifyError() function, NotifyStop() function or both.
- Create an instance of the derived class.
- Register the instance with the ECLConnection::RegisterCommEvent() function.
The example shown demonstrates how this may be done. When the above steps are complete, each time a connection's communications link is connected or disconnected from a host, the applications NotifyEvent() member function will be called.
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 ECLConnection::UnregisterCommEvent, or by destruction of the ECLConnection 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 communications 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 ECLConnection object allows only one notification object to be registered for communications event notification. The ECLConnection::RegisterCommEvent will throw an error if a notify object is already registered for that ECLConnection object.