kdu_client::install_notifier

Provides a generic mechanism for the network management thread to notify the application when the connection state changes or when new data is placed in the cache. Specifically, the application provides an appropriate object, derived from the abstract base class, kdu_client_notifier. The object's virtual notify function is called from within the network management thread whenever any of the following conditions occur:

• Connection with the server is completed;
• The server has acknowledged a request for a new window into the image, possibly modifying the requested window to suit its needs (call get_window_in_progress to learn about any changes to the window which is actually being served);
• One or more new messages from the server have been received and used to augment the cache; or
• The server has disconnected — in this case, notifier→notify is called immediately before the network management thread is terminated, but is_alive is guaranteed to be false from immediately before the point at which the notification was raised, so as to avoid possible race conditions in the client application.

A typical notifier would post a message on an interactive client's message queue so as to wake the application up if necessary. A more intelligent notifier may choose to wake the application up in this way only if a substantial change has occurred in the cache — something which may be determined with the aid of the kdu_cache::get_transferred_bytes function.

The following functions should never be called from within the notifier→notify call, since that call is generated from within the network management thread: connect, close, disconnect and post_window.

We note that the notifier remains installed after its notify function has been called, so there is no need to re-install the notifier. If you wish to remove the notifier, the install_notifier function may be called with a NULL argument.

notifier [kdu_client_notifier *]