ldi_add_event_handler

- add NDI event service callback handler

Synopsis

#include <sys/ddi_obsolete.h>

int ldi_add_event_handler(ldi_handle_t lh, ddi_eventcookie_t ec, 
     void (*handler)(ldi_handle_t, ddi_eventcookie_t,
     void *, void *) void *arg, ldi_callback_id_t *id);

Interface Level

Obsolete

Parameters

ldi_handle_t lh

Layered handle representing event notification device.

ddi_eventcookie_t ec

Cookie returned from call to ldi_get_eventcookie(9F).

void (*handler)(ldi_handle_t, ddi_eventcookie_t, void *, void *)

Callback handler for NDI event service notification.

void *arg

Pointer to opaque data supplied by caller. Typically, this is a pointer to the layered driver's softstate structure.

ldi_callback_id_t *id

Pointer to registration id, where a unique registration id is returned. Registration id must be saved and used when calling ldi_remove_event_handler(9F) to unregister a callback handler.

Description

This function is obsolete and is only maintained for compatibility. Use of this function is strongly discouraged. For equivalent functionality provided by new interfaces, see ldi_ev_get_cookie(9F) and ldi_ev_register_callbacks(9F).

The ldi_add_event_handler() function adds a callback handler to be invoked at the occurance of the event specified by the cookie. Adding a callback handler is also known as subscribing to an event. Upon successful subscription, the handler is invoked when the event occurs. You can unregister the handler by using ldi_remove_event_handler(9F).

An instance of a layered driver can register multiple handlers for an event or a single handler for multiple events. Callback order is not defined and should be assumed to be random.

The routine handler is invoked with the following arguments:

ldi_handle_t lh

Layered handle representing the device for which the event notification is requested.

ddi_eventcookie_t ec

Structure describing event that occurred.

void *arg

Opaque data pointer provided by the driver during callback registration.

void *impl_data

Pointer to event specific data defined by the framework that invokes the callback function.

Return Values

DDI_SUCCESS

Callback handler registered successfully.

DDI_FAILURE

Failed to register callback handler. Possible reasons include lack of resources or a bad cookie.

Context

The ldi_add_event_handler() function can be called from user and kernel contexts only.

See Also

ldi_ev_get_cookie(9F), ldi_ev_register_callbacks(9F), ldi_get_eventcookie(9F), ldi_remove_event_handler(9F)

Writing Device Drivers

Notes

Layered drivers must remove all registered callback handlers for a device instance, represented by the layered handle, by calling ldi_remove_event_handler(9F) before the layered driver's detach(9E) routine completes.