ddi_add_event_handler(9f)

1ddi_add_event_handler(9F)Kernel Functions for Driversddi_add_event_handler(9F)
2
3
4

NAME

6       ddi_add_event_handler - add an NDI event service callback handler
7

SYNOPSIS

9       #include <sys/dditypes.h>
10       #include <sys/sunddi.h>
11
12       int ddi_add_event_handler(dev_info_t *dip, ddi_eventcookie_t cookie,
13            void (*handler)(dev_info_t *, ddi_eventcookie_t, void *, void *),
14            void *arg, ddi_registration_id_t *id);
15
16

INTERFACE LEVEL

18       Solaris DDI specific (Solaris DDI).
19

PARAMETERS

21       dev_info_t *dip
22
23           Device node registering the callback.
24
25
26       ddi_eventcookie_t cookie
27
28           Cookie returned from call to ddi_get_eventcookie(9F).
29
30
31       void (*handler)(dev_info_t *, ddi_eventcookie_t, void *, void *)
32
33           Callback  handler  responsible  for  handling  an NDI event service
34           notification.
35
36
37       void *arg
38
39           Pointer to opaque data supplied  by  the  caller.  Typically,  this
40           would be a pointer to the driver's softstate structure.
41
42
43       ddi_registration_id_t *id
44
45           Pointer  to  registration ID where a unique registration id will be
46           returned. Registration ID must  be  saved  and  used  when  calling
47           ddi_remove_event_handler(9F) to unregister a callback.
48
49

DESCRIPTION

51       The  ddi_add_event_handler()  function  adds  a  callback handler to be
52       invoked in the face of the event specifed by  cookie.  The  process  of
53       adding  a  callback  handler  is also known as subscribing to an event.
54       Upon successful subscription, the handler will be invoked by the system
55       when  the  event  occurs.  The  handler  can  be  unregistered by using
56       ddi_remove_event_handler(9F).
57
58
59       An instance of a driver can register multiple handlers for an event  or
60       a single handler for multiple events. Callback order is not defined and
61       should assumed to be random.
62
63
64       The routine handler will be invoked with the following arguments:
65
66       dev_info_t *dip             Device node requesting the notification.
67
68
69       ddi_eventcookie_t cookie    Structure describing event that occurred.
70
71
72       void *arg                   Opaque  data  pointer  provided,   by   the
73                                   driver, during callback registration.
74
75
76       void *impl_data             Pointer  to  event specific data defined by
77                                   the framework which  invokes  the  callback
78                                   function.
79
80

RETURN VALUES

82       DDI_SUCCESS    Callback handler registered successfully.
83
84
85       DDI_FAILURE    Failed  to  register  callback handler. Possible reasons
86                      include lack of resources or a bad cookie.
87
88

CONTEXT

90       The ddi_add_event_handler() and handler() function can be  called  from
91       user and kernel contexts only.
92

ATTRIBUTES

94       See attributes(5) for a description of the following attributes:
95
96
97
98
99       ┌─────────────────────────────┬─────────────────────────────┐
100       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
101       ├─────────────────────────────┼─────────────────────────────┤
102       │Stability Level              │Committed                    │
103       └─────────────────────────────┴─────────────────────────────┘
104

NOTES

112       Drivers  must  remove  all  registered  callback  handlers for a device
113       instance by calling  ddi_remove_event_handler(9F)  before  detach  com‐
114       pletes.
115
116
117
118SunOS 5.11                        62 Nov 2003        ddi_add_event_handler(9F)