ddi_get_eventcookie(9f) [sunos man page]

ddi_get_eventcookie(9F) 				   Kernel Functions for Drivers 				   ddi_get_eventcookie(9F)

NAME

       ddi_get_eventcookie - retrieve a NDI event service cookie handle

SYNOPSIS

       #include <sys/dditypes.h>
       #include <sys/sunddi.h>

       int ddi_get_eventcookie(dev_info_t *dip, char *name, ddi_eventcookie_t *event_cookiep);

INTERFACE LEVEL

       Solaris DDI specific (Solaris DDI).

PARAMETERS

       dev_info_t *dip

	   Child device node requesting the cookie.

       char *name

	   NULL-terminated string containing the name of the event.

       ddi_eventcookie_t *event_cookiep

	   Pointer to cookie where event cookie will be returned.

DESCRIPTION

       The  ddi_get_eventcookie()  function  queries  the  device  tree for a cookie matching the given event name and returns a reference to that
       cookie. The search is performed by a calling up the device tree hierarchy until the request is satisfied by a bus nexus driver, or the  top
       of the dev_info tree is reached.

       The cookie returned by this function can be used to register a callback handler, unregister a callback handler, or post an event.

RETURN VALUES

       DDI_SUCCESS

	   Cookie handle is returned.

       DDI_FAILURE

	   Request was not serviceable by any nexus driver in the driver's ancestral device tree hierarchy.

CONTEXT

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

ATTRIBUTES

       See attributes(5) for a description of the following attributes:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Stability Level 	     |Evolving			   |
       +-----------------------------+-----------------------------+

SEE ALSO

       attributes(5), ddi_add_event_handler(9F), ddi_remove_event_handler(9F)

       Writing Device Drivers

SunOS 5.10							    6 Nov 2003						   ddi_get_eventcookie(9F)

ldi_add_event_handler(9F)				   Kernel Functions for Drivers 				 ldi_add_event_handler(9F)

NAME

       ldi_add_event_handler - Add an NDI event service callback handler

SYNOPSIS

       #include <sys/sunldi.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

       Solaris DDI Specific (Solaris DDI).

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

       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_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.

SunOS 5.10							    9 Feb 2004						 ldi_add_event_handler(9F)