Previous

Next

Function RTUSendSetup

RTUSendSetup performs a complete 2- or 3-stage Control transaction on a pipe to a Control endpoint. The request can be a standard request, a class-specific request, or a device-specific request:

int RTUSendSetup(RTUPipeHandle ControlPipe, 
                 BYTE          bmRequestType, 
                 BYTE          bRequest, 
                 WORD          wValue, 
                 WORD          wIndex, 
                 WORD          wLength, 
                 void        * Data);

Parameters

ControlPipe

Pipe to a Control endpoint. Typically, this will be a handle to the default Control endpoint 0 created with RTUOpenPipe(Device, NULL, 1), but it could also be a pipe to a different Control endpoint.

bmRequestType

Bitmap flags specifying characteristics of the request. The value to be supplied is documented in the USB spec, the class spec, or the technical documentation of the device.

bRequest

The request number. This value is documented in the USB spec, the class spec, or the technical documentation of the device.

wValue

16-bit value to send to the device. The interpretation of this value is request-specific.

wIndex

16-bit index value to send to the device. The interpretation of this value is request-specific.

wLength

16-bit length of the data to be transmitted in the optional data stage. If this value is 0, parameter Data can be NULL and no data stage is performed. RTUSB-32 does not support wLength values greater than 4096.

Data

Pointer to a buffer of at least wLength bytes size. Depending on the particular request, this buffer holds data to be transferred to the device, data to be received from the device, or can be NULL if wLength is 0.

return value

If the function succeeds, the number of bytes actually transferred in the data stage is returned, or a negative error code on failure. If the request times out, RTU_CANCELED is returned.

RTUSendSetup sends a setup packet as defined by the USB specification to the device. If wLength is greater 0, the data is transferred to or from the device (as indicated by the control bits in bmRequestType). Finally, a status stage is performed in the opposite direction as the data stage (or from the device to the host if there was no data stage).

What bRequest and bmRequestType values are supported is device-specific. The USB specification defines a few standard requests which all devices must support. For example, RTUSB-32 uses the following call to retrieve a device descriptor:

Result = RTUSendSetup(ControlPipe, 
                      RTU_BMRT_DEVICE | RTU_BMRT_STANDARD | RTU_BMRT_DEVICE_TO_HOST, 
                      RTU_GET_DESCRIPTOR, 
                      RTU_DEVICE_DESCRIPTOR << 8, 
                      0, 
                      sizeof(RTUDeviceDescriptor), 
                      &DevDescr);

Each USB class specification and many custom devices define additional requests. The respective class or device specification document the required bRequest, bmRequestType, wValue, wIndex, wLength, and Data parameters.

RTUSendSetup applies a timeout specified with RTUSetPipeOption for the pipe. If RTUSetPipeOption was never called for the given pipe, RTUSBConfig.ControlTimeout (default: 1 second) is used instead. If the transaction times out, it is canceled.

Function RTUSetPipeOption

Function RTUStartIO