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

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.