'\" te
.\" Copyright (c) 2004, Sun Microsystems, Inc., All Rights Reserved
.TH usb_get_status 9F "5 Jan 2004" "SunOS 5.11" "Kernel Functions for Drivers"
.SH NAME
usb_get_status \- Get status of a USB device/endpoint/interface
.SH SYNOPSIS
.LP
.nf
#include <sys/usb/usba.h>

\fBint\fR \fBusb_get_status\fR(\fBdev_info_t *\fR\fIdip\fR, \fBusb_pipe_handle_t\fR \fIpipe_handle\fR,
     \fBuint_t\fR \fIrequest_type\fR, \fBuint_t\fR \fIwhich\fR, \fBuint16_t *\fR\fIstatus\fR, 
     \fBusb_flags_t\fR \fIflags\fR);
.fi

.SH INTERFACE LEVEL
.sp
.LP
Solaris DDI specific (Solaris DDI)
.SH PARAMETERS
.sp
.ne 2
.mk
.na
\fB\fIdip\fR\fR
.ad
.RS 16n
.rt  
Pointer to device's dev_info structure.
.RE

.sp
.ne 2
.mk
.na
\fB\fIpipe_handle\fR\fR
.ad
.RS 16n
.rt  
Default control pipe handle on which request is made.
.RE

.sp
.ne 2
.mk
.na
\fB\fIrequest_type\fR\fR
.ad
.RS 16n
.rt  
bmRequestType. Either:
.sp
USB_DEV_REQ_RCPT_DEV \(em Get device status.
.sp
USB_DEV_REQ_RCPT_IF \(em Get interface status.
.sp
USB_DEV_REQ_RCPT_EP \(em Get endpoint status.
.RE

.sp
.ne 2
.mk
.na
\fB\fIwhich\fR\fR
.ad
.RS 16n
.rt  
Device, interface or endpoint from which to get status.  Either  number of interface or endpoint, or  0 if device status requested.
.RE

.sp
.ne 2
.mk
.na
\fB\fIstatus\fR\fR
.ad
.RS 16n
.rt  
Address into which the status is written.
.RE

.sp
.ne 2
.mk
.na
\fB\fIflags\fR\fR
.ad
.RS 16n
.rt  
None are recognized.
.RE

.SH DESCRIPTION
.sp
.LP
The \fBusb_get_status()\fR function returns the status of a device, interface or endpoint.  All status requests use the default control pipe. Length of data returned is USB_GET_STATUS_LEN bytes.  Always block and wait for resources if not available, regardless of the flags argument.
.sp
.LP
When the \fIrequest_type\fR recipient is USB_DEV_REQ_RCPT_DEV, device status is requested. Status returned includes bits for USB_DEV_SLF_PWRD_STATUS (device is  currently  self-powered) and USB_DEV_RWAKEUP_STATUS (device has remote  wakeup enabled). A set bit indicates the corresponding status.
.sp
.LP
When the \fIrequest_type\fR is USB_DEV_REQ_RCPT_EP, endpoint status is requested. Status returned includes bits for USB_EP_HALT_STATUS (endpoint is halted). A set bit indicates the corresponding status.
.sp
.LP
When the \fIrequest_type\fR is USB_DEV_REQ_RCPT_IF, interface status is requested and USB_IF_STATUS (zero) is returned.
.SH RETURN VALUES
.sp
.ne 2
.mk
.na
\fBUSB_SUCCESS\fR
.ad
.RS 20n
.rt  
Status returned successfully in the status argument.
.RE

.sp
.ne 2
.mk
.na
\fBUSB_INVALID_ARGS\fR
.ad
.RS 20n
.rt  
Status pointer and/or dip argument is NULL.
.RE

.sp
.ne 2
.mk
.na
\fBUSB_INVALID_PIPE\fR
.ad
.RS 20n
.rt  
Pipe handle is NULL.
.RE

.sp
.ne 2
.mk
.na
\fBUSB_FAILURE\fR
.ad
.RS 20n
.rt  
Status not returned successfully.
.RE

.SH CONTEXT
.sp
.LP
May be called from user or kernel context.
.SH EXAMPLES
.sp
.in +2
.nf
  uint16_t status;

  if (usb_get_status(
      dip, pipe_handle, USB_DEV_REQ_RCPT_DEV, 0 &status, 0) ==
      USB_SUCCESS) {
          if (status & USB_DEV_SLF_PWRD_STATUS) {
                  cmn_err (CE_WARN,
                      "%s%d: USB device is running on its own power.",
                      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), \fBusb_clr_feature\fR(9F), \fBusb_get_alt_if\fR(9F), \fBusb_pipe_get_state\fR(9F), \fBusb_get_cfg\fR(9F),