Current File : //usr/share/man/man9f/usb_register_hotplug_cbs.9f

'\" te
.\" Copyright (c) 2004, Sun Microsystems, Inc., All Rights Reserved
.TH usb_register_hotplug_cbs 9F "17 Aug 2004" "SunOS 5.11" "Kernel Functions for Drivers"
.SH NAME
usb_register_hotplug_cbs, usb_unregister_hotplug_cbs \- Register/unregister for notification of device hotplug events
.SH SYNOPSIS
.LP
.nf
#include <sys/usb/usba.h>

\fB\fR\fBint\fR \fBusb_register_hotplug_cbs\fR(\fBdev_info_t *\fR\fIdip\fR, 
     \fBint\fR \fI(*disconnection_event_handler)\fR(dev_info_t *\fIdip\fR,
     \fBint\fR \fI(*reconnection_event_handler)\fR(dev_info_t *\fIdip\fR);
.fi

.LP
.nf
 \fBvoid\fR \fB\fR\fBusb_unregister_hotplug_cbs\fR(\fBdev_info_t *\fR\fIdip\fR);
.fi

.SH INTERFACE LEVEL
.sp
.LP
Solaris DDI specific (Solaris DDI)
.SH PARAMETERS
.sp
.LP
For \fBusb_register_hotplug_cbs()\fR
.sp
.ne 2
.mk
.na
\fB\fIdip\fR\fR
.ad
.sp .6
.RS 4n
Pointer to the device's \fBdev_info\fR structure.
.RE

.sp
.ne 2
.mk
.na
\fB\fIdisconnection_event_handler\fR\fR
.ad
.sp .6
.RS 4n
Called when device is disconnected. This handler takes a dev_info_t as an argument (representing the device being disconnected) and always returns USB_SUCCESS.
.RE

.sp
.ne 2
.mk
.na
\fB\fIreconnection_event_handler\fR\fR
.ad
.sp .6
.RS 4n
Called when device is reconnected. This handler takes a dev_info_t as an argument (representing the device being reconnected) and always returns USB_SUCCESS.
.RE

.sp
.LP
For \fBusb_unregister_hotplug_cbs()\fR:
.sp
.ne 2
.mk
.na
\fB\fIdip\fR\fR
.ad
.RS 7n
.rt  
Pointer to the device's \fBdev_info\fR structure.
.RE

.SH DESCRIPTION
.sp
.LP
The \fBusb_register_hotplug_cbs()\fR function registers callbacks to be executed when the USB device represented by \fIdip\fR is hotplugged or removed.
.sp
.LP
The \fBusb_unregister_hotplug_cbs()\fR function unregisters or disengages callbacks from executing when the USB device represented by \fIdip\fR is hotplugged or removed.
.SH RETURN VALUES
.sp
.LP
For \fBusb_register_hotplug_cbs()\fR:
.sp
.ne 2
.mk
.na
\fBUSB_SUCCESS\fR
.ad
.RS 15n
.rt  
Callbacks were successfully registered.
.RE

.sp
.ne 2
.mk
.na
\fBUSB_FAILURE\fR
.ad
.RS 15n
.rt  
One or more arguments were NULL.
.sp
Callbacks could not be successfully registered.
.RE

.sp
.LP
For \fBusb_unregister_hotplug_cbs()\fR: None
.SH CONTEXT
.sp
.LP
The \fBusb_register_hotplug_cbs()\fR function may be called only from \fBattach\fR(9E).
.sp
.LP
The \fBusb_unregister_hotplug_cbs()\fR function may be called only from \fBdetach\fR(9E).
.sp
.LP
Registered callback handlers requiring the use of any DDI (section 9F) function (except ddi_taskq_* functions), should launch a separate thread using ddi_taskq_* routines for processing their event, to avoid deadlocks. The new thread can then safely call any DDI function it needs to handle the event.
.sp
.LP
The registered callback handlers execute in kernel context.
.SH EXAMPLES
.sp
.in +2
.nf
   
    int remove_device(dev_info_t *)
    {
            ...
            ...
            return (USB_SUCCESS);
    }

    int accommodate_device(dev_info_t *)
    {
            ...
            ...
            return (USB_SUCCESS);
    }

    if (usb_register_hotplug_cbs(
        dip, remove_device, accommodate_device) == USB_FAILURE) {
            cmn_err (CE_WARN,
                "%s%d: Could not register hotplug handlers.",
                ddi_driver_name(dip), ddi_get_instance(dip));
    }
            
.fi
.in -2

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes: 
.sp

.sp
.TS
tab() box;
cw(2.75i) |cw(2.75i) 
lw(2.75i) |lw(2.75i) 
.
ATTRIBUTE TYPEATTRIBUTE VALUE
_
ArchitecturePCI-based systems
_
Interface StabilityCommitted
_
Availabilitysystem/io/usb
.TE

.SH SEE ALSO
.sp
.LP
\fBattributes\fR(5), \fBattach\fR(9E), \fBdetach\fR(9E), \fBusb_get_status\fR(9F)