Simple notification

In some cases, the CHAI calls the application code to report a network event.

The notification mechanism is based on a set of interface classes whose name is suffixed with NotificationHandler.

An application that needs being notified by the CHAI must implement one or more notification handlers and activate them by calling the appropriate method. A notification handler can be set or removed at any time, depending on the application needs.

Beware that removing a notification handler during the related notification call might result in unpredictable behavior!

An object accepting a notification has methods prefixed with Register or Unregister, and suffixed with NotificationHandler. The rest of the method name describes the notification purpose (see example hereafter).

Each notification handler contains at least one method, each taking as first argument a pointer to the object relating to the current notification call.

Examples of notification handler interfaces:

• CPNS::ICHAI_NotificationHandler: the general purpose notification handler related to the CPNS::ICHAI object
• CPNS::ISelectorItemList_NotificationHandler: the notification handler used by the CHAI to request Selector Item List values.

Examples of notification handlers registering methods:

//From interface CPNS::ICHAI :
void RegisterNotificationHandler(
            IN CPNS::ICHAI_NotificationHandler * const pHandler
            );
void UnregisterNotificationHandler(
            IN CPNS::ICHAI_NotificationHandler * const pHandler
            );

//From interface CPNS::IBaseLocalDevice :
void RegisterSignalNotificationHandler(
            IN CPNS::IBaseLocalDevice_SignalNotificationHandler * const pHandler
            );

void UnregisterSignalNotificationHandler(
            IN CPNS::IBaseLocalDevice_SignalNotificationHandler * const pHandler
            );

Note

A hooked object is always acquired before being passed as an argument to a notification handler, and then released on return of this handler. This is to ensure that the object will not be destroyed during the notification call. An application storing a pointer to a hooked object must acquire it, and release it once useless.