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#
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 |
---|---|
| Returns status for the specified recipient. |
| Clear or disable a specific feature. |
| Set or enable a specific feature. |
| Set the device address for all future device accesses. |
| Return the specified descriptor if the descriptor exists. |
| Update existing descriptors or new descriptors may be added. |
| Return the current device configuration value. |
| Set the device configuration. |
| Return the selected alternate setting for the specified interface. |
| Select an alternate setting for the specified interface. |
| 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
andw_index
arguments vary according to the specific request defined byb_request
argument.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 |
| This parameters are used to build the Setup packet sent by the host to the device. |
Data |
| If no data stage is required, you just need to set |
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 toUSBDev_API
library using thecallback
argument.USBDev_API
library allows to queue several asynchronous IN transfers for the same pipe.