USBDev_CtrlReq

Description

Send control data over the default control endpoint.

Files

usbdev_api.c

Prototype

ULONG  USBDev_CtrlReq (HANDLE   dev,
                       UCHAR    bm_req_type,
                       UCHAR    b_request,
                       USHORT   w_value,
                       USHORT   w_index,
                       UCHAR   *p_buf,
                       USHORT   buf_len,
                       DWORD   *p_err);

Arguments

dev

General handle to device

bm_req_type

Variable representing bmRequestType of setup packet. bmRequestType is a bitmap with the following characteristics:

D7

Data transfer direction:

‘0’: USB_DIR_HOST_TO_DEVICE

‘1’: USB_DIR_DEVICE_TO_HOST

D6...5

Request type:

‘00’: USB_REQUEST_TYPE_STD (standard)

‘01’: USB_REQUEST_TYPE_CLASS

‘10’: USB_REQUEST_TYPE_VENDOR

D4...0

Recipient:

‘0000’: USB_RECIPIENT_DEV (device)

‘0001’: USB_RECIPIENT_IF (interface)

‘0010’: USB_RECIPIENT_ENDPOINT

b_request

Variable representing bRequest of setup packet. Possible values are:

bRequest	Description
`GET_STATUS`	Returns status for the specified recipient.
`CLEAR_FEATURE`	Clear or disable a specific feature.
`SET_FEATURE`	Set or enable a specific feature.
`SET_ADDRESS`	Set the device address for all future device accesses.
`GET_DESCRIPTOR`	Return the specified descriptor if the descriptor exists.
`SET_DESCRIPTOR`	Update existing descriptors or new descriptors may be added.
`GET_CONFIGURATION`	Return the current device configuration value.
`SET_CONFIGURATION`	Set the device configuration.
`GET_INTERFACE`	Return the selected alternate setting for the specified interface.
`SET_INTERFACE`	Select an alternate setting for the specified interface.
SYNCH_FRAME	Set and then report an endpoint’s synchronization frame.

w_value

Variable representing wValue of setup packet.

w_index

Variable representing wIndex of setup packet.

p_buf

Pointer to transmit or receive buffer for data phase of control transfer.

buf_len

Length of transmit or receive buffer.

p_err

Pointer to variable that will receive the return error code from this function:

ERROR_SUCCESS

ERROR_INVALID_HANDLE

ERROR_NOT_ENOUGH_MEMORY

ERROR_GEN_FAILURE

Returned Value

None

Callers

Application.

Notes / Warnings

The value of w_value and w_index arguments vary according to the specific request defined by b_request argument.
1. When the request's recipient is an interface or an endpoint, w_index must be properly configured. For an interface recipient, w_index will contain the interface number. For an endpoint recipient, w_index will contain the endpoint address. This one can be retrieved using the function USBDev_PipeAddrGet().

The following code shows an example using USBDev_CtrlReq() to send the SET_INTERFACE request:

DWORD   err;
                            /* Select alternate setting #1 for default interface. */
USBDev_CtrlReq ( dev_handle,
                (USB_DIR_HOST_TO_DEVICE | USB_REQUEST_TYPE_STD | USB_RECIPIENT_IF),
                 SET_INTERFACE,
                 1,         /* Alternate setting #1.                              */
                 0,         /* Interface #0 inside active configuration.          */
                 0,         /* No data phase.                                     */
                 0,
                &err);
if (err != ERROR_SUCCESS) {
    printf("[ERROR #%d] SET_INTERFACE(1) request failed.\n", err);
}

More details about USB device requests can be found in “Universal Serial Bus Specification, Revision 2.0, April 27, 2000”, section 9.3.

A control transfer is composed of 3 stages: Setup, Data (IN, OUT or no data stage) and Status. The table below presents the parameters of USBDev_CtrlReq() involved in each specific stage.

Control Transfer Stage	Parameter Involved	Note
Setup	`bm_req_type` `b_request` `w_value` `w_index`	This parameters are used to build the Setup packet sent by the host to the device.
Data	`p_buf` `buf_len`	If no data stage is required, you just need to set `p_buf` to null pointer and `buf_len` to the value 0.
Status	None	NO parameter is involved for the Status stage. It is managed automatically by the Windows Host stack.