Kernel Functions for Drivers                   usbpipeclose(9F)



NAME
     usbpipeclose - Close and cleanup a USB device pipe

SYNOPSIS
     #include 



     void usbpipeclose(devinfot *dip, usbpipehandlet pipehandle,
          usbflagst flags,
          void (*callback)(usbpipehandlet pipehandle,
          usbopaquet arg, int rval,
          usbcbflagst flags), usbopaquet callbackarg);


INTERFACE LEVEL
     Solaris DI specific (Solaris DI)

PARAMETERS
     dip             Pointer to the device's devinfo structure.


     pipehandle     Handle of pipe to close. Cannot be a  handle
                     to the default control pipe.


     flags           USBFLAGSLEP is the only flag recognized.
                     Set  it  to  wait for resources, for pipe to
                     become free, and  for  all  pending  request
                     callbacks to complete.


     callback        This function is called on completion if the
                     USBFLAGSLEP  flag is not specified. Man-
                     datory if the USBFLAGSLEP flag  has  not
                     been specified.


     callbackarg    Second argument to callback function.


DESCRIPTION
     The usbpipeclose() function closes the pipe pointed to  by
     pipehandle,  releases  all related resources and then frees
     the pipe handle. This function stops polling if the pipe  to
     be  closed  is  an  interrupt-IN or isochronous-IN pipe. The
     default control pipe cannot be closed.


     Pipe cleanup includes waiting for the all  pending  requests
     in  the  pipe to finish, and then flushing residual requests
     remaining after  waiting  for  several  seconds.   Exception



SunOS 5.11           Last change: 5 Jan 2004                    1






Kernel Functions for Drivers                   usbpipeclose(9F)



     handlers  of  flushed  requests are called with a completion
     reason of USBCRFLUSHED.


     If USBFLAGSLEP is  specified  in  flags,  wait  for  all
     cleanup  operations  to complete before calling the callback
     handler and returning.


     If USBFLAGSLEP is not specified in flags,  an  asynchro-
     nous  close  (to be done in a separate thread) is requested.
     Return immediately. The callback handler is called after all
     pending operations are completed.


     The callback parameter is the callback handler and takes the
     following arguments:

     usbpipehandlet pipehandle

         Handle of the pipe to close.


     usbopaquet callbackarg

         Callbackarg specified to usbpipeclose().


     int rval

         Return value of close operation


     usbcbflagst callbackflags

         Status of queueing operation. Can be:

         USBCBNOINFO             Callback was uneventful.


         USBCBASYNCREQFAILED    Error  starting  asynchronous
                                    request.



RETURN VALUES
     Status is returned to the caller via the callback  handler's
     rval argument. Possible callback hander rval argument values
     are:

     USBINVALIDPIPE       Pipe handle specifies a pipe which is
                            closed or closing.



SunOS 5.11           Last change: 5 Jan 2004                    2






Kernel Functions for Drivers                   usbpipeclose(9F)



     USBINVALIDARGS       dip  or  pipehandle  arguments   are
                            NUL.


     USBINVALIDCONTEXT    Called from interrupt context.


     USBINVALIDPERM       Pipe handle  specifies   the  default
                            control pipe.


     USBFAILURE            Asynchronous resources  are  unavail-
                            able.       In       this       case,
                            USBCBASYNCREQFAILED is passed  in
                            as  the  callbackflags  arg  to  the
                            callback hander.



     Exception handlers of any queued requests which were flushed
     are  called  with  a  completion  reason  of USBCRFLUSHED.
     Exception handlers of periodic pipe requests which were ter-
     minated  are called with USBCRPIPECLOSING.


     Note that messages mirroring the above errors are logged  to
     the  console  logfile  on  error.  (This provides status for
     calls which otherwise could provide status).

CONTEXT
     May be called from user  or  kernel  context  regardless  of
     arguments.  May  not  be called from a callback executing in
     interrupt     context. Please see usbcallbackflags(9S) for
     more information on callbacks.


     If   the   USBCBASYNCREQFAILED   bit   is    clear    in
     usbcbflagst, the callback, if supplied, can block because
     it is executing in kernel context.  Otherwise  the  callback
     cannot  block.  Please  see  usbcallbackflags(9S) for more
     information on callbacks.

EXAMPLES
       /* Synchronous close of pipe. */
       usbpipeclose(dip, pipe, USBFLAGSLEP, NUL, NUL);

           --------

       /* Template callback. */
       void closecallback(usbpipehandlet, usbopaquet, usbcbflagst);

       /* Asynchronous close of pipe. */



SunOS 5.11           Last change: 5 Jan 2004                    3






Kernel Functions for Drivers                   usbpipeclose(9F)



       usbpipeclose(dip, pipe, 0, closecallback, callbackarg);



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



     
           ATRIBUTE TYPE               ATRIBUTE VALUE       
    
     Architecture                 PCI-based systems           
    
     Interface stability          Committed                   
    
     Availability                 SUNWusb                     
    


SEE ALSO
     attributes(5), usbgetstatus(9F),  usbpipedrainreqs(9F),
     usbpipegetstate(9F),                   usbpipeopen(9F),
     usbpipereset(9F), usbcallbackflags(9S)






























SunOS 5.11           Last change: 5 Jan 2004                    4