Callbacks

Sometimes the CHAI needs calling the application code to report some network activity or to request information.

The callback mechanism is based on a set of interfaces. In order to be called from the CHAI, an application has to implement these interfaces and register their objects as handlers.

There are two types of Interface classes:

• The notification handlers, used to inform the application or to request for information. Their Interface name is suffixed with _NotificationHandler.
• The asynchronous return handler, called to tell that an asynchronous function is done. Such interface is suffixed with _AsyncReturnHandler.

Several notification handlers can be attached to an object using Register***NotificationHandler method. Similarly it is possible to remove a notification handler using Unregister***NotificationHandler method.

By design, a unique asynchronous return handler is associated to an async operation.

Notification handler lifetime

It is very important to un-register a notification handler object if it is destroyed before the notification source. For example, when creating a notification handler related to a CPNS::ILocalDevice, there's no need to un-register it while the local device still exists.

For example, this is the case if the application code creates various notification handler objects, then the CopperLan structure (devices, params, etc), and finally destroys the CHAI before the notification handlers. Conversely, when the application code relies on a dynamic layout, some notification handlers can be destroyed while their source object is still alive. In this case the handler must be unregistered to avoid access violation or similar exception.

Asynchronous notification handler lifetime

You must ensure that an asynchronous notification handler is not destroyed while a related async operation is running. Such notification handler is always called at the end of the async operation. It is good practice to store the CPNS::IAsync pointer returned by the ***_Async method and set the variable to NULL when the notification handler is called. If the application needs destroying the notification handler object, it should first check that the variable is NULL. If so the handler can be destroyed safely. If not, a call to CPNS::ICHAI::CancelAsync must be performed first.

Tips & tricks

It is common practice to share a notification handler amongst several notification source objects. Each notification handler's pure virtual method initiated in the application code receives a pointer to the notification source. So, while it's always possible to know the origin of the notification, it can be tedious comparing this pointer with all potential sources. Hopefully an efficient solution is provided: each CHAI object is inheriting from CPNS::IObject, and this interface allows storing user data in the object using CPNS::IObject::SetUserDataPtr and CPNS::IObject::SetUserDataUInt32. This way, you can attach a pointer to some application data container for each notification source, so it's very easy to find the context relating to a notification handler call.

Usage of CPNS::IObject_NotificationHandler is also recommended. In some cases it is interesting to make an application notification handler inheriting from CPNS::IObject_NotificationHandler in addition to the notification interface. This implies a dual notification handler registering on the notification source object, but it allows being notified when the object is about to be deleted.

Additional information

• Simple notification
• Request notification
• Asynchronous return handler
• Threading