(v13) Notification events

This page applies to Harlequin v13.1r0 and later; both Harlequin Core and Harlequin MultiRIP

The simplest use for events is as a notification signal, allowing other systems to react to your system's actions without any direct linkage between them. For example, the RIP notifies interested parties of a job interpretation error with one line:

SwEvent(SWEVT_INTERPRET_ERROR, &error, sizeof(error)) ;

The HHR skin registers a handler for this Event in skinkit.c:

static sw_event_handlers error_handlers[] = {
        {job_error_handler, NULL, 0, SWEVT_INTERPRET_ERROR, SW_EVENT_DEFAULT},
        ...
};
...
        SwRegisterHandlers(error_handlers, NUM_ARRAY_ITEMS(error_handlers) ;

When it receives the notification Event, it extracts the details of the error:

static sw_event_result HQNCALL job_error_handler(void *context, sw_event *event)
{
        SWMSG_ERROR *msg = event->message;
        UNUSED_PARAM(void *, context);
        if (msg == NULL || event->length < sizeof(*msg))
                return SW_EVENT_CONTINUE;
        if (msg->fail_job && !controlData.fConfigJobFailed) {
                /* Capture error detail */
                controlData.fConfigJobFailed = TRUE;
                controlData.jobError.monuid = msg->error_monuid;
                ...
        }
        return SW_EVENT_CONTINUE;
}

Note that SW_EVENT_CONTINUE should usually be used by handlers of notification Events if the handler were to return SW_EVENT_HANDLED, no further handlers would be notified of the Event. This is likely to be a protocol error for a notification type Event as all handlers would need to know about it.