Kernel Functions for Drivers            ddiaddeventhandler(9F)



NAME
     ddiaddeventhandler - add an NDI  event  service  callback
     handler

SYNOPSIS
     #include 
     #include 

     int ddiaddeventhandler(devinfot *dip, ddieventcookiet cookie,
          void (*handler)(devinfot *, ddieventcookiet, void *, void *),
          void *arg, ddiregistrationidt *id);


INTERFACE LEVEL
     Solaris DI specific (Solaris DI).

PARAMETERS
     devinfot *dip

         Device node registering the callback.


     ddieventcookiet cookie

         Cookie returned from call to ddigeteventcookie(9F).


     void (*handler)(devinfot *, ddieventcookiet, void *,
     void *)

         Callback handler responsible for handling an  NDI  event
         service notification.


     void *arg

         Pointer to opaque data supplied  by  the  caller.  Typi-
         cally, this would be a pointer to the driver's softstate
         structure.


     ddiregistrationidt *id

         Pointer to registration ID where a  unique  registration
         id  will  be returned. Registration ID must be saved and
         used when calling ddiremoveeventhandler(9F) to  unre-
         gister a callback.


DESCRIPTION
     The ddiaddeventhandler() function adds a callback handler
     to  be  invoked in the face of the event specifed by cookie.



SunOS 5.11          Last change: 62 Nov 2003                    1






Kernel Functions for Drivers            ddiaddeventhandler(9F)



     The process of adding a callback handler is  also  known  as
     subscribing  to  an event. Upon successful subscription, the
     handler will be invoked by the system when the event occurs.
     The     handler     can    be    unregistered    by    using
     ddiremoveeventhandler(9F).


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


     The routine handler will be invoked with the following argu-
     ments:

     devinfot *dip             Device   node   requesting   the
                                 notification.


     ddieventcookiet cookie    Structure describing event  that
                                 occurred.


     void *arg                   Opaque data pointer provided, by
                                 the   driver,   during  callback
                                 registration.


     void *impldata             Pointer to event  specific  data
                                 defined  by  the framework which
                                 invokes the callback function.


RETURN VALUES
     DISUCES    Callback handler registered successfully.


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


CONTEXT
     The ddiaddeventhandler() and handler()  function  can  be
     called from user and kernel contexts only.

ATRIBUTES
     See attributes(5) for a description of the following  attri-
     butes:






SunOS 5.11          Last change: 62 Nov 2003                    2






Kernel Functions for Drivers            ddiaddeventhandler(9F)



     
           ATRIBUTE TYPE               ATRIBUTE VALUE       
    
     Stability Level              Committed                   
    


SEE ALSO
     attributes(5),                      ddigeteventcookie(9F),
     ddiremoveeventhandler(9F)


     Writing Device Drivers

NOTES
     Drivers must remove all registered callback handlers  for  a
     device   instance  by  calling  ddiremoveeventhandler(9F)
     before detach completes.





































SunOS 5.11          Last change: 62 Nov 2003                    3