'\" te
.\" Copyright (c) 2004, Sun Microsystems, Inc., All Rights Reserved
.TH usb_pipe_get_state 9F "5 Jan 2004" "SunOS 5.11" "Kernel Functions for Drivers"
.SH NAME
usb_pipe_get_state \- Return USB pipe state
.SH SYNOPSIS
.LP
.nf
#include <sys/usb/usba.h>

\fBint\fR \fBusb_pipe_get_state\fR(\fBusb_pipe_handle_t\fR \fIpipe_handle\fR, 
     \fBusb_pipe_state_t *\fR\fIpipe_state\fR, \fBusb_flags_t\fR \fIusb_flags\fR);
.fi

.SH INTERFACE LEVEL
.sp
.LP
Solaris DDI specific (Solaris DDI)
.SH PARAMETERS
.sp
.ne 2
.mk
.na
\fB\fIpipe_handle\fR\fR
.ad
.RS 15n
.rt  
Handle of the pipe to retrieve the state.
.RE

.sp
.ne 2
.mk
.na
\fB\fIpipe_state\fR\fR
.ad
.RS 15n
.rt  
Pointer to where pipe state is returned.
.RE

.sp
.ne 2
.mk
.na
\fB\fIusb_flags\fR\fR
.ad
.RS 15n
.rt  
No flags are recognized. Reserved for future expansion.
.RE

.SH DESCRIPTION
.sp
.LP
The \fBusb_pipe_get_state()\fR function retrieves the state of the pipe referred to by \fIpipe_handle\fR into the location pointed to by \fIpipe_state\fR. 
.sp
.LP
Possible pipe states are:
.sp
.ne 2
.mk
.na
\fBUSB_PIPE_STATE_CLOSED\fR
.ad
.RS 26n
.rt  
Pipe is closed.
.RE

.sp
.ne 2
.mk
.na
\fBUSB_PIPE_STATE_ACTIVE\fR
.ad
.RS 26n
.rt  
Pipe is active and can send/receive data. Polling is active for isochronous and interrupt pipes.
.RE

.sp
.ne 2
.mk
.na
\fBUSB_PIPE_STATE_IDLE\fR
.ad
.RS 26n
.rt  
Polling is stopped for isochronous and interrupt-IN pipes.
.RE

.sp
.ne 2
.mk
.na
\fBUSB_PIPE_STATE_ERROR\fR
.ad
.RS 26n
.rt  
An error occurred. Client must call \fBusb_pipe_reset()\fR. Note that this status is not seen by a client driver if USB_ATTRS_AUTOCLEARING is set in the request attributes.
.RE

.sp
.ne 2
.mk
.na
\fBUSB_PIPE_STATE_CLOSING\fR
.ad
.RS 26n
.rt  
Pipe is being closed. Requests are being drained from the pipe and other cleanup is in progress.
.RE

.SH RETURN VALUES
.sp
.ne 2
.mk
.na
\fBUSB_SUCCESS\fR
.ad
.RS 20n
.rt  
Pipe state returned in second argument.
.RE

.sp
.ne 2
.mk
.na
\fBUSB_INVALID_ARGS\fR
.ad
.RS 20n
.rt  
Pipe_state argument is \fBNULL\fR.
.RE

.sp
.ne 2
.mk
.na
\fBUSB_INVALID_PIPE\fR
.ad
.RS 20n
.rt  
Pipe_handle argument is \fBNULL\fR.
.RE

.SH CONTEXT
.sp
.LP
May be called from user, kernel or interrupt context. 
.SH EXAMPLES
.sp
.in +2
.nf
    usb_pipe_handle_t pipe;
    usb_pipe_state_t state;

    /* Recover if the pipe is in an error state. */
    if ((usb_pipe_get_state(pipe, &state, 0) == USB_SUCCESS) &&
        (state == USB_PIPE_STATE_ERROR)) {
            cmn_err (CE_WARN, "%s%d: USB Pipe error.",
                ddi_driver_name(dip), ddi_get_instance(dip));
            do_recovery();
    }
            
.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_cfg\fR(9F). \fBusb_get_status\fR(9F), \fBusb_pipe_close\fR(9F), \fBusb_pipe_ctrl_xfer\fR(9F), \fBusb_pipe_open\fR(9F). \fBusb_pipe_reset\fR(9F)