USBDev_API API#

USBDev_API is a library implemented under Windows operating system. Functions return values and parameters use Windows data types such as DWORD, HANDLE, ULONG.

Refer to MSDN online documentation for more details about Windows data types (http://msdn.microsoft.com/en-us/library/aa383751(v=VS.85).aspx ).

USBDev_DevQtyGet
USBDev_Open
USBDev_Close
USBDev_AltSettingQtyGet
USBDev_AssociatedIF_QtyGet
USBDev_AltSettingSet
USBDev_AltSettingCurGet
USBDev_IsHighSpeed
USBDev_BulkIn_Open
USBDev_BulkOut_Open
USBDev_IntrIn_Open
USBDev_IntrOut_Open
USBDev_PipeAddrGet
USBDev_PipeClose
USBDev_PipeStall
USBDev_PipeAbort
USBDev_CtrlReq
USBDev_PipeWr
USBDev_PipeWrExt
USBDev_PipeRd
USBDev_PipeRdAsync

USBDev_DevQtyGet#

Description#

Get number of devices belonging to the specified GUID.

Files#

usbdev_api.c

Prototype#

DWORD  USBDev_DevQtyGet (const  GUID    guid_dev_if,
                                DWORD  *p_err);

Arguments#

guid_dev_if

Device interface class GUID.

p_err

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

ERROR_SUCCESS

Returned Value#

Number of devices for the provided GUID, if NO error(s).
0, otherwise.

Callers#

Application.

Notes / Warnings#

The function USBDev_DevQtyGet() uses the concept of device information set. A device information set consists of device information elements for all the devices that belong to some device setup class or device interface class. The GUID passed to USBDev_DevQtyGet() function is a device interface class. Internally by using some control options the function retrieves the device information set which represents a list of all devices present in the system and registered under the specified GUID. More details about the device information set can be found at http://msdn.microsoft.com/en-us/library/ff541247(VS.85).aspx .

USBDev_Open#

Description#

Open a device by retrieving a general device handle.

Files#

usbdev_api.c

Prototype#

HANDLE  USBDev_Open (const  GUID    guid_dev_if,
                            DWORD   dev_nbr,
                            DWORD  *p_err);

Arguments#

guid_dev_if

Device interface class GUID.

dev_nbr

Device number.

p_err

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

ERROR_SUCCESS
ERROR_INVALID_PARAMETER
ERROR_NOT_ENOUGH_MEMORY
ERROR_BAD_DEVICE

Returned Value#

Handle to device, if NO error(s).
INVALID_HANDLE_VALUE, otherwise.

Callers#

Application.

Notes / Warnings#

None.

USBDev_Close#

Description#

Close a device by freeing any allocated resources and by releasing any created handles.

Files#

usbdev_api.c

Prototype#

void  USBDev_Close (HANDLE   dev,
                    DWORD   *p_err);

Arguments#

dev

General handle to device.

p_err

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

ERROR_SUCCESS
ERROR_INVALID_HANDLE

Returned Value#

None.

Callers#

Application.

Notes / Warnings#

USBDev_Close() closes any remaining open pipes. The open pipes are usually closed from the application by calling the function USBDev_PipeClose.

USBDev_AltSettingQtyGet#

Description#

Get number of alternate settings for the specified interface.

Files#

usbdev_api.c

Prototype#

UCHAR  USBDev_AltSettingQtyGet (HANDLE   dev,
                                UCHAR    if_nbr,
                                DWORD   *p_err);

Arguments#

dev

General handle to device.

if_nbr

Interface number.

p_err

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

ERROR_SUCCESS
ERROR_INVALID_HANDLE
ERROR_INVALID_PARAMETER

Returned Value#

Number of alternate setting, if NO error(s).
0, otherwise.

Callers#

Application.

Notes / Warnings#

An interface may include alternate settings that allow the endpoints and/or their characteristics to be varied after the device has been configured. The default setting for an interface is always alternate setting zero. Alternate settings allow a portion of the device configuration to be varied while other interfaces remain in operation.
The number of alternate settings gotten can be used to open a pipe associated with a certain alternate interface.

USBDev_AssociatedIF_QtyGet#

Description#

Get number of associated interfaces with the default interface. That is all the interfaces besides the default interface managed by WinUSB.sys and registered under the same GUID.

Files#

usbdev_api.c

Prototype#

UCHAR  USBDev_AssociatedIF_QtyGet (HANDLE   dev,
                                   DWORD   *p_err);

Arguments#

dev

General handle to device.

p_err

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

ERROR_SUCCESS
ERROR_INVALID_HANDLE

Returned Value#

Number of associated interfaces, if NO error(s).
0, otherwise.

Callers#

Application.

Notes / Warnings#

Let’s assume that a device has three interfaces managed by WinUSB.sys driver and belonging to the same GUID: Interface #0, #1 and #2. Interface #0 is the default interface. Interfaces #1 and #2 are the associated interfaces. In that example calling USBDev_AssociatedIF_QtyGet() will return 2 associated interfaces.

USBDev_AltSettingSet#

Description#

Set the alternate setting of an interface.

Files#

usbdev_api.c

Prototype#

void  USBDev_AltSettingSet (HANDLE   dev,
                            UCHAR    if_nbr,
                            UCHAR    alt_set,
                            DWORD   *p_err);

Arguments#

dev

General handle to device.

if_nbr

Interface number.

alt_set

Alternate setting number.

p_err

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

ERROR_SUCCESS
ERROR_INVALID_HANDLE
ERROR_INVALID_PARAMETER

Returned Value#

None.

Callers#

Application.

Notes / Warnings#

This function sends a SET_INTERFACE request to the device to set the alternate setting number and updates the one used internally by WinUSB.

USBDev_AltSettingCurGet#

Description#

Get the current alternate setting for the specified interface.

Files#

usbdev_api.c

Prototype#

UCHAR  USBDev_AltSettingCurGet (HANDLE   dev,
                                UCHAR    if_nbr,
                                DWORD   *p_err);

Arguments#

dev

General handle to device.

if_nbr

Interface number.

p_err

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

ERROR_SUCCESS
ERROR_INVALID_HANDLE
ERROR_INVALID_PARAMETER

Returned Value#

Current alternate setting number, if NO error(s).
0, otherwise.

Callers#

Application.

Notes / Warnings#

This function gets the current alternate setting number used internally by WinUSB and gets the one from the device by sending a GET_INTERFACE request. Both alternate setting numbers are compared. If they match, the current alternate setting is returned.

USBDev_IsHighSpeed#

Description#

Specify if the device attached to PC is high speed or not.

Files#

usbdev_api.c

Prototype#

BOOL  USBDev_IsHighSpeed (HANDLE   dev,
                          DWORD   *p_err);

Arguments#

dev

General handle to device.

p_err

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

ERROR_SUCCESS
ERROR_INVALID_HANDLE
ERROR_INVALID_PARAMETER

Returned Value#

TRUE, if device is high-speed.
FALSE, otherwise.

Callers#

Application.

Notes / Warnings#

None.

USBDev_BulkIn_Open#

Description#

Open a Bulk IN pipe.

Files#

usbdev_api.c

Prototype#

HANDLE  USBDev_BulkIn_Open (HANDLE   dev,
                            UCHAR    if_nbr,
                            UCHAR    alt_set,
                            DWORD   *p_err);

Arguments#

dev

General handle to device.

if_nbr

Interface number.

alt_set

Alternate setting number for specified interface.

p_err

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

ERROR_SUCCESS
ERROR_INVALID_HANDLE
ERROR_NO_MORE_ITEMS

Returned Value#

Handle to Bulk IN pipe, if NO error(s).
INVALID_HANDLE_VALUE, otherwise.

Callers#

Application.

Notes / Warnings#

None.

USBDev_BulkOut_Open#

Description#

Open a Bulk OUT pipe.

Files#

usbdev_api.c

Prototype#

HANDLE  USBDev_BulkOut_Open (HANDLE   dev,
                             UCHAR    if_nbr,
                             UCHAR    alt_set,
                             DWORD   *p_err);

Arguments#

dev

General handle to device.

if_nbr

Interface number.

alt_set

Alternate setting number for specified interface.

p_err

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

ERROR_SUCCESS
ERROR_INVALID_HANDLE
ERROR_NO_MORE_ITEMS

Returned Value#

Handle to Bulk OUT pipe, if NO error(s).
INVALID_HANDLE_VALUE, otherwise.

Callers#

Application.

Notes / Warnings#

None.

USBDev_IntrIn_Open#

Description#

Open a Interrupt IN pipe.

Files#

usbdev_api.c

Prototype#

HANDLE  USBDev_IntrIn_Open (HANDLE   dev,
                            UCHAR    if_nbr,
                            UCHAR    alt_set,
                            DWORD   *p_err);

Arguments#

dev

General handle to device.

if_nbr

Interface number.

alt_set

Alternate setting number for specified interface.

p_err

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

ERROR_SUCCESS
ERROR_INVALID_HANDLE
ERROR_NO_MORE_ITEMS

Returned Value#

Handle to Interrupt IN pipe, if NO error(s).
INVALID_HANDLE_VALUE, otherwise.

Callers#

Application.

Notes / Warnings#

None.

USBDev_IntrOut_Open#

Description#

Open a Interrupt OUT pipe.

Files#

usbdev_api.c

Prototype#

HANDLE  USBDev_IntrOut_Open (HANDLE   dev,
                             UCHAR    if_nbr,
                             UCHAR    alt_set,
                             DWORD   *p_err);

Arguments#

dev

General handle to device.

if_nbr

Interface number.

alt_set

Alternate setting number for specified interface.

p_err

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

ERROR_SUCCESS
ERROR_INVALID_HANDLE
ERROR_NO_MORE_ITEMS

Returned Value#

Handle to Interrupt OUT pipe, if NO error(s).
INVALID_HANDLE_VALUE, otherwise.

Callers#

Application.

Notes / Warnings#

None.

USBDev_PipeAddrGet#

Description#

Get pipe address.

Files#

usbdev_api.c

Prototype#

UCHAR  USBDev_PipeAddrGet (HANDLE   pipe,
                           DWORD   *p_err);

Arguments#

pipe

Pipe handle.

p_err

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

ERROR_SUCCESS
ERROR_INVALID_HANDLE

Returned Value#

Pipe address, if NO error(s).
0, otherwise.

Callers#

Application.

Notes / Warnings#

The pipe address is composed of the pipe direction and the pipe logical address. The pipe direction is located at bit 7. A value of '1' indicates an IN pipe and '0' an OUT pipe. The pipe logical address sits in bit 3 to bit 0.

USBDev_PipeClose#

Description#

Close a pipe.

Files#

usbdev_api.c

Prototype#

void  USBDev_PipeClose (HANDLE   pipe,
                        DWORD   *p_err);

Arguments#

pipe

Pipe handle.

p_err

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

ERROR_SUCCESS
ERROR_INVALID_HANDLE

Returned Value#

None

Callers#

Application.

Notes / Warnings#

None.

USBDev_PipeStall#

Description#

Stall a pipe or clear the stall condition of a pipe.

Files#

usbdev_api.c

Prototype#

void  USBDev_PipeStall (HANDLE   pipe,
                        BOOL     stall,
                        DWORD   *p_err);

Arguments#

pipe

Pipe handle.

stall

Indicate which action to do:

TRUE
Stall pipe.
FALSE
Clear stall condition of the pipe.

p_err

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

ERROR_SUCCESS
ERROR_INVALID_HANDLE
ERROR_NOT_ENOUGH_MEMORY

Returned Value#

None.

Callers#

Application.

Notes / Warnings#

The SET_FEATURE standard request is sent to the device to stall the pipe. The CLEAR_FEATURE standard request is sent to the device to clear the stall condition of the pipe.

USBDev_PipeAbort#

Description#

Aborts all of the pending transfers for a pipe.

Files#

usbdev_api.c

Prototype#

void  USBDev_PipeAbort (HANDLE   pipe,
                        DWORD   *p_err);

Arguments#

pipe

Pipe handle.

p_err

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

ERROR_SUCCESS
ERROR_INVALID_HANDLE

Returned Value#

None.

Callers#

Application.

Notes / Warnings#

None.

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.

USBDev_PipeWr#

Description#

Write data to device over the specified pipe.

Files#

usbdev_api.c

Prototype#

DWORD  USBDev_PipeWr (HANDLE   pipe,
                      UCHAR   *p_buf,
                      DWORD    buf_len,
                      DWORD    timeout,
                      DWORD   *p_err);

Arguments#

pipe

Pipe handle.

p_buf

Pointer to transmit buffer.

buf_len

Transmit buffer length.

timeout

Timeout in milliseconds. A value of 0 indicates a wait forever.

p_err

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

ERROR_SUCCESS
ERROR_INVALID_HANDLE
ERROR_INVALID_USER_BUFFER
ERROR_BAD_PIPE
ERROR_INVALID_PARAMETER
ERROR_NOT_ENOUGH_MEMORY
ERROR_SEM_TIMEOUT

Returned Value#

Number of bytes written, if NO error(s).
0, otherwise.

Callers#

Application.

Notes / Warnings#

None.

USBDev_PipeWrExt#

Description#

Write data to device over the specified pipe.

Files#

usbdev_api.cs

Prototype#

DWORD  USBDev_PipeWrExt (HANDLE   pipe,
                         UCHAR   *p_buf,
                         DWORD    buf_len,
                         BOOL     end,
                         DWORD    timeout,
                         DWORD   *p_err);

Arguments#

pipe

Pipe handle.

p_buf

Pointer to transmit buffer.

buf_len

Transmit buffer length.

end

End-of-transfer flag (see Note #1).

timeout

Timeout in milliseconds. A value of 0 indicates a wait forever.

p_err

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

ERROR_SUCCESS
ERROR_INVALID_HANDLE
ERROR_INVALID_USER_BUFFER
ERROR_BAD_PIPE
ERROR_INVALID_PARAMETER
ERROR_NOT_ENOUGH_MEMORY
ERROR_SEM_TIMEOUT

Returned Value#

Number of bytes written, if NO error(s).
0, otherwise.

Callers#

Application.

Notes / Warnings#

If end-of-transfer is set and transfer length is multiple of maximum packet size, a zero-length packet is transferred to indicate a short transfer to the device.

USBDev_PipeRd#

Description#

Read data from device over the specified pipe.

Files#

usbdev_api.c

Prototype#

DWORD  USBDev_PipeRd (HANDLE   pipe,
                      UCHAR   *p_buf,
                      DWORD    buf_len,
                      DWORD    timeout,
                      DWORD   *p_err);

Arguments#

pipe

Pipe handle.

p_buf

Pointer to receive buffer.

buf_len

Receive buffer length.

timeout

Timeout in milliseconds. A value of 0 indicates a wait forever.

p_err

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

ERROR_SUCCESS
ERROR_INVALID_HANDLE
ERROR_INVALID_USER_BUFFER
ERROR_BAD_PIPE
ERROR_INVALID_PARAMETER
ERROR_NOT_ENOUGH_MEMORY
ERROR_SEM_TIMEOUT7

Returned Value#

Number of bytes received, if NO error(s).
0, otherwise.

Callers#

Application.

Notes / Warnings#

None.

USBDev_PipeRdAsync#

Description#

Read data from device over the specified pipe. This function returns immediately if data is not present. The data will be retrieved later.

Files#

usbdev_api.c

Prototype#


void  USBDev_PipeRdAsync (HANDLE                    pipe,
                          UCHAR                    *p_buf,
                          DWORD                     buf_len,
                          USBDEV_PIPE_RD_CALLBACK   callback,
                          void                     *p_callback_arg,
                          DWORD                    *p_err);

Arguments#

pipe

Pipe handle.

p_buf

Pointer to receive buffer.

buf_len

Receive buffer length.

callback

Pointer to application callback called by Asynchronous thread upon completion.

p_callback_arg

Pointer to argument which can carry private information passed by application. This argument is used when the callback is called.

p_err

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

ERROR_SUCCESS
ERROR_INVALID_HANDLE
ERROR_INVALID_USER_BUFFER
ERROR_BAD_PIPE
ERROR_NOT_ENOUGH_MEMORY
ERROR_SEM_TIMEOUT

Returned Value#

None.

Callers#

Application.

Notes / Warnings#

When a IN pipe is open with one of the open functions USBDev_xxxxIn_Open(), a thread is automatically created. This thread is in charge of informing the application about a completed asynchronous IN transfer. Upon completion of an asynchronous transfer, the thread is waken up and calls the application callback provided to USBDev_API library using the callback argument.
USBDev_API library allows to queue several asynchronous IN transfers for the same pipe.