B.4 USB Functions

B.4 USB Functions
	Appendix B WinDriver USB PC Host API Reference

The functions described in this section are declared in the
WinDriver/include/wdu_lib.h header file.

B.4.1 WDU_Init

PURPOSE

• Starts listening to devices matching input criteria and registers notification callbacks for these devices.

PROTOTYPE

DWORD WDU_Init(
    WDU_DRIVER_HANDLE *phDriver,
    WDU_MATCH_TABLE *pMatchTables,
    DWORD dwNumMatchTables,
    WDU_EVENT_TABLE *pEventTable,
    const char *sLicense,
    DWORD dwOptions);

PARAMETERS

Name	Type	Input/Output
phDriver	WDU_DRIVER_HANDLE *	Output
pMatchTables	WDU_MATCH_TABLE*	Input
dwNumMatchTables	DWORD	Input
pEventTable	WDU_EVENT_TABLE*	Input
sLicense	const char*	Input
dwOptions	DWORD	Input

DESCRIPTION

Name	Description
phDriver	Handle to the registration of events & criteria
pMatchTables	Array of match tables [B.5.2.1] defining the devices' criteria
dwNumMatchTables	Number of elements in pMatchTables
pEventTable	Pointer to an event table structure [B.5.2.2], which holds the addresses of the user-mode device status change notification callback functions [B.3] and the data to pass to the callbacks
sLicense	WinDriver's license string
dwOptions	Can be zero or : • `WD_ACKNOWLEDGE` – the user can seize control over the device when returning value in `WDU_ATTACH_CALLBACK` [B.3.1]

RETURN VALUE

Returns WD_STATUS_SUCCESS(0) on success, or an appropriate error code otherwise [B.8].

B.4.2 WDU_SetInterface

PURPOSE

• Sets the alternate setting for the specified interface.

PROTOTYPE

DWORD WDU_SetInterface(
    WDU_DEVICE_HANDLE hDevice,
    DWORD dwInterfaceNum,
    DWORD dwAlternateSetting);

PARAMETERS

Name	Type	Input/Output
hDevice	WDU_DEVICE_HANDLE	Input
dwInterfaceNum	DWORD	Input
dwAlternateSetting	DWORD	Input

DESCRIPTION

Name	Description
hDevice	A unique identifier for the device/interface
dwInterfaceNum	The interface's number
dwAlternateSetting	The desired alternate setting value

RETURN VALUE

Returns WD_STATUS_SUCCESS(0) on success, or an appropriate error code otherwise [B.8].

REMARKS

On Windows CE – as opposed to Windows 7/Vista/Server 2008/Server 2003/XP/2000 – WDU_SetInterface attempts to open all the pipes of the specified alternate setting, even if not all pipes are currently required. The reason for this is that Windows CE limits the total number of pipes that can be opened simultaneously on a device, to 16 (see http://msdn.microsoft.com/en-us/library/ms919318.aspx). By opening all the pipes, the driver ensures that the pipes will be available for use, when needed.
The pipes are opened using the Windows CE USB host controller driver's LPOPEN_PIPE callback. On some Mobile devices, the call to this callback fails, causing WDU_SetInterface to fail as well. To resolve such problems, upgrade the device's USB host controller driver.

B.4.3 WDU_GetDeviceAddr

PURPOSE

• Gets the USB address for a given device.

PROTOTYPE

DWORD WDU_GetDeviceAddr(
    WDU_DEVICE_HANDLE hDevice, 
    ULONG *pAddress);

PARAMETERS

Name	Type	Input/Output
hDevice	WDU_DEVICE_HANDLE	Input
pAddress	ULONG	Output

DESCRIPTION

Name	Description
hDevice	A unique identifier for a device/interface
pAddress	A pointer to the address number returned by the function

RETURN VALUE

Returns WD_STATUS_SUCCESS(0) on success, or an appropriate error code otherwise [B.8].

REMARKS

This function is supported only on Windows 2000 and higher.

B.4.4 WDU_GetDeviceRegistryProperty

PURPOSE

• Gets the specified registry property of a given USB device.

PROTOTYPE

DWORD DLLCALLCONV WDU_GetDeviceRegistryProperty(
    WDU_DEVICE_HANDLE hDevice,
    PVOID pBuffer, 
    PDWORD pdwSize, 
    WD_DEVICE_REGISTRY_PROPERTY property);

PARAMETERS

Name	Type	Input/Output
hDevice	WDU_DEVICE_HANDLE	Input
pBuffer	PVOID	Output
pdwSize	PDWORD	Input/Output
property	WD_DEVICE_REGISTRY_PROPERTY	Input

DESCRIPTION

Name	Description
hDevice	A unique identifier of the device/interface
pBuffer	Pointer to a user allocated buffer to be filled with the requested registry property. The function will fill the buffer only if the buffer size, as indicated in the input value of the `pdwSize` parameter, is sufficient – i.e. >= the property's size, as returned via `pdwSize`. `pBuffer` can be set to `NULL` when using the function only to retrieve the size of the registry property (see `pdwSize`).
pdwSize	As input, points to a value indicating the size of the user-supplied buffer (`pBuffer` ); if `pBuffer` is set to `NULL`, the input value of this parameter is ignored. As output, points to a value indicating the required buffer size for storing the registry property.
property	The ID of the registry property to be retrieved – see the description of the `WD_DEVICE_REGISTRY_PROPERTY` enumeration [B.5.1]. Note: String registry properties are in WCHAR format.

RETURN VALUE

Returns WD_STATUS_SUCCESS(0) on success, or an appropriate error code otherwise [B.8].

REMARKS

When the size of the provided user buffer (pBuffer ) – *pdwSize (input) – is not sufficient to hold the requested registry property, the function returns WD_INVALID_PARAMETER.
This function is supported only on Windows 2000 and higher.

B.4.5 WDU_GetDeviceInfo

PURPOSE

• Gets configuration information from a device, including all the device descriptors.

NOTE: The caller to this function is responsible for calling WDU_PutDeviceInfo [B.4.6] in order to free the *ppDeviceInfo pointer returned by the function.

PROTOTYPE

DWORD WDU_GetDeviceInfo(
    WDU_DEVICE_HANDLE hDevice,
    WDU_DEVICE **ppDeviceInfo);

PARAMETERS

Name	Type	Input/Output
hDevice	WDU_DEVICE_HANDLE	Input
ppDeviceInfo	WDU_DEVICE**	Output

DESCRIPTION

Name	Description
hDevice	A unique identifier for a device/interface
ppDeviceInfo	Pointer to pointer to a USB device information structure [B.5.2.3]

RETURN VALUE

Returns WD_STATUS_SUCCESS(0) on success, or an appropriate error code otherwise [B.8].

B.4.6 WDU_PutDeviceInfo

PURPOSE

• Receives a device information pointer, allocated with a previous WDU_GetDeviceInfo [B.4.5] call, in order to perform the necessary cleanup.

PROTOTYPE

void WDU_PutDeviceInfo(WDU_DEVICE *pDeviceInfo);

PARAMETERS

Name	Type	Input/Output
pDeviceInfo	WDU_DEVICE*	Input

DESCRIPTION

Name	Description
pDeviceInfo	Pointer to a USB device information structure [B.5.2.3], as returned by a previous call to `WDU_GetDeviceInfo` [B.4.5]

RETURN VALUE

None

B.4.7 WDU_Uninit

PURPOSE

• Stops listening to devices matching a given criteria and un-registers the notification callbacks for these devices.

PROTOTYPE

void WDU_Uninit(WDU_DRIVER_HANDLE hDriver);

PARAMETERS

Name	Type	Input/Output
hDriver	WDU_DRIVER_HANDLE	Input

DESCRIPTION

Name	Description
hDriver	Handle to the registration received from `WDU_Init` [B.4.1]

RETURN VALUE

None

B.4.8 Single Blocking Transfer Functions

This section describes WinDriver's single blocking data transfer functions.
For more information, refer to 9.3.2 of the manual.

B.4.8.1 WDU_Transfer

PURPOSE

• Transfers data to or from a device.

PROTOTYPE

DWORD WDU_Transfer(
    WDU_DEVICE_HANDLE hDevice,
    DWORD dwPipeNum,
    DWORD fRead,
    DWORD dwOptions,
    PVOID pBuffer,
    DWORD dwBufferSize,
    PDWORD pdwBytesTransferred,
    PBYTE pSetupPacket,
    DWORD dwTimeout);

PARAMETERS

Name	Type	Input/Output
hDevice	WDU_DEVICE_HANDLE	Input
dwPipeNum	DWORD	Input
fRead	DWORD	Input
dwOptions	DWORD	Input
pBuffer	PVOID	Input
dwBufferSize	DWORD	Input
pdwBytesTransferred	PDWORD	Output
pSetupPacket	PBYTE	Input
dwTimeout	DWORD	Input

DESCRIPTION

Name	Description
hDevice	A unique identifier for the device/interface received from `WDU_Init` [B.4.1]
dwPipeNum	The number of the pipe through which the data is transferred
fRead	`TRUE` for read, `FALSE` for write
dwOptions	A bit-mask, which can consist of a combination of any of the following flags: • `USB_ISOCH_NOASAP` – For isochronous data transfers. Setting this option instructs the lower USB stack driver (usbd.sys) to use a preset frame number (instead of the next available frame) while performing the data transfer. Use this flag if you notice unused frames during the transfer, on low-speed or full-speed devices (USB 1.1 only) and only on Windows (excluding Windows CE). • `USB_ISOCH_RESET` – Resets the isochronous pipe before the data transfer. It also resets the pipe after minor errors, consequently allowing to transfer to continue. • `USB_ISOCH_FULL_PACKETS_ONLY` – Prevents transfers of less than the packet size on isochronous pipes. • `USB_BULK_INT_URB_SIZE_OVERRIDE_128K` – Limits the size of the USB Request Block (URB) to 128KB.
pBuffer	Address of the data buffer
dwBufferSize	Number of bytes to transfer. The buffer size is not limited to the device's maximum packet size; therefore, you can use larger buffers by setting the buffer size to a multiple of the maximum packet size. Use large buffers to reduce the number of context switches and thereby improve performance.
pdwBytesTransferred	Number of bytes actually transferred
pSetupPacket	An 8-byte packet to transfer to control pipes
dwTimeout	Maximum time, in milliseconds (ms), to complete a transfer. A value of zero indicates no timeout (infinite wait).

RETURN VALUE

Returns WD_STATUS_SUCCESS(0) on success, or an appropriate error code otherwise [B.8].

REMARKS

The resolution of the timeout (the dwTimeout parameter) is according to the operating system scheduler's time slot. For example, in Windows the timeout's resolution is 10 milliseconds (ms).

B.4.8.2 WDU_HaltTransfer

PURPOSE

• Halts the transfer on the specified pipe (only one simultaneous transfer per pipe is allowed by WinDriver).

PROTOTYPE

DWORD WDU_HaltTransfer(
    WDU_DEVICE_HANDLE hDevice,
    DWORD dwPipeNum);

PARAMETERS

Name	Type	Input/Output
hDevice	WDU_DEVICE_HANDLE	Input
dwPipeNum	DWORD	Input

DESCRIPTION

Name	Description
hDevice	A unique identifier for the device/interface
dwPipeNum	The number of the pipe

RETURN VALUE

status

B.4.8.3 WDU_TransferDefaultPipe

PURPOSE

• Transfers data to or from a device through the default pipe.

PROTOTYPE

DWORD WDU_TransferDefaultPipe(
    WDU_DEVICE_HANDLE hDevice,
    DWORD fRead,
    DWORD dwOptions,
    PVOID pBuffer,
    DWORD dwBufferSize,
    PDWORD pdwBytesTransferred,
    PBYTE pSetupPacket,
    DWORD dwTimeout);

PARAMETERS

See parameters of WDU_Transfer [B.4.8.1].
Note that dwPipeNum is not a parameter of this function.

DESCRIPTION

See description of WDU_Transfer [B.4.8.1].

RETURN VALUE

Returns WD_STATUS_SUCCESS(0) on success, or an appropriate error code otherwise [B.8].

B.4.8.4 WDU_TransferBulk

PURPOSE

• Performs bulk data transfer to or from a device.

PROTOTYPE

DWORD WDU_TransferBulk(
    WDU_DEVICE_HANDLE hDevice,
    DWORD dwPipeNum,
    DWORD fRead,
    DWORD dwOptions,
    PVOID pBuffer,
    DWORD dwBufferSize,
    PDWORD pdwBytesTransferred,
    DWORD dwTimeout);

PARAMETERS

See parameters of WDU_Transfer [B.4.8.1].
Note that pSetupPacket is not a parameter of this function.

DESCRIPTION

See description of WDU_Transfer [B.4.8.1].

RETURN VALUE

Returns WD_STATUS_SUCCESS(0) on success, or an appropriate error code otherwise [B.8].

B.4.8.5 WDU_TransferIsoch

PURPOSE

• Performs isochronous data transfer to or from a device.

PROTOTYPE

DWORD WDU_TransferIsoch(
    WDU_DEVICE_HANDLE hDevice,
    DWORD dwPipeNum,
    DWORD fRead,
    DWORD dwOptions,
    PVOID pBuffer,
    DWORD dwBufferSize,
    PDWORD pdwBytesTransferred,
    DWORD dwTimeout);

PARAMETERS

See parameters of WDU_Transfer [B.4.8.1].
Note that pSetupPacket is not a parameter of this function.

DESCRIPTION

See description of WDU_Transfer [B.4.8.1].

RETURN VALUE

Returns WD_STATUS_SUCCESS(0) on success, or an appropriate error code otherwise [B.8].

B.4.8.6 WDU_TransferInterrupt

PURPOSE

• Performs interrupt data transfer to or from a device.

PROTOTYPE

DWORD WDU_TransferInterrupt(
    WDU_DEVICE_HANDLE hDevice,
    DWORD dwPipeNum,
    DWORD fRead,
    DWORD dwOptions,
    PVOID pBuffer,
    DWORD dwBufferSize,
    PDWORD pdwBytesTransferred,
    DWORD dwTimeout);

PARAMETERS

See parameters of WDU_Transfer [B.4.8.1].
Note that pSetupPacket is not a parameter of this function.

DESCRIPTION

See description of WDU_Transfer [B.4.8.1].

RETURN VALUE

Returns WD_STATUS_SUCCESS(0) on success, or an appropriate error code otherwise [B.8].

B.4.9 Streaming Data Transfer Functions

This section describes WinDriver's streaming data transfer functions.
For a detailed explanation regarding stream transfers and their implementation with Windriver, refer to 9.3.3 of the manual.


	The streaming APIs are currently supported on Windows and Windows CE.

The streaming APIs are currently supported on Windows and Windows CE.

B.4.9.1 WDU_StreamOpen

PURPOSE

• Opens a new stream for the specified pipe.
A stream can be associated with any pipe except for the control pipe (Pipe 0). The stream's data transfer direction – read/write – is derived from the direction of its pipe.

PROTOTYPE

DWORD DLLCALLCONV WDU_StreamOpen(
    WDU_DEVICE_HANDLE hDevice,
    DWORD dwPipeNum, 
    DWORD dwBufferSize,
    DWORD dwRxSize,
    BOOL  fBlocking,
    DWORD dwOptions, 
    DWORD dwRxTxTimeout,
    WDU_STREAM_HANDLE *phStream);

PARAMETERS

Name	Type	Input/Output
hDevice	WDU_DEVICE_HANDLE	Input
dwPipeNum	DWORD	Input
dwBufferSize	DWORD	Input
dwRxSize	DWORD	Input
fBlocking	BOOL	Input
dwOptions	DWORD	Input
dwRxTxTimeout	DWORD	Input
phStream	WDU_STREAM_HANDLE*	Output

DESCRIPTION

Name	Description
hDevice	A unique identifier for the device/interface
dwPipeNum	The number of the pipe for which to open the stream
dwBufferSize	The size, in bytes, of the stream's data buffer
dwRxSize	The size, in bytes, of the data blocks that the stream reads from the device. This parameter is relevant only for read streams, and must not exceed the value of the `dwBufferSize` parameter. Note: When setting the `USB_STREAM_MAX_TRANSFER_SIZE_OVERWRITE` `dwOptions` flag, this is also the maximum transfer size.
fBlocking	• `TRUE` for a blocking stream, which performs blocked I/O; • `FALSE` for a non-blocking stream, which performs non-blocking I/O. For additional information, refer to 9.3.3.1.
dwOptions	A bit-mask, which can consists of a combination of any of the following flags: • `USB_ISOCH_NOASAP` – For isochronous data transfers. Setting this option instructs the lower USB stack driver (usbd.sys) to use a preset frame number (instead of the next available frame) while performing the data transfer. Use this flag if you notice unused frames during the transfer, on low- or full-speed USB 1.1 devices. This flag is applicable only on Windows, and is ignored on Windows CE. • `USB_ISOCH_FULL_PACKETS_ONLY` – Prevents transfers of less than the packet size on isochronous pipes. • `USB_BULK_INT_URB_SIZE_OVERRIDE_128K` – Limits the size of the USB Request Block (URB) to 128KB. This flag is applicable only on Windows. • `USB_STREAM_OVERWRITE_BUFFER_WHEN_FULL` – When there is not enough free space in a read stream's data buffer to complete the transfer, overwrite old data in the buffer. This flag is applicable only to read streams. • `USB_STREAM_MAX_TRANSFER_SIZE_OVERRIDE` – Overrides the default maximum transfer size with the `dwRxSize` transfer size, on Windows CE. Note that setting a large `dwRxSize` value when using this flag, may cause the transfers to fail due to host controller limitations. This flag is applicable only to read streams on Windows CE.
dwRxTxTimeout	Maximum time, in milliseconds (ms), for the completion of a data transfer between the stream and the device. A value of zero indicates no timeout (infinite wait).
phStream	Pointer to a unique identifier for the stream, to be returned by the function and passed to the other `WDU_StreamXXX` functions

RETURN VALUE

Returns WD_STATUS_SUCCESS(0) on success, or an appropriate error code otherwise [B.8].

B.4.9.2 WDU_StreamStart

PURPOSE

• Starts a stream, i.e. starts transfers between the stream and the device.
Data will be transferred according to the stream's direction – read/write.

PROTOTYPE

DWORD DLLCALLCONV WDU_StreamStart(
    WDU_STREAM_HANDLE hStream);

PARAMETERS

Name	Type	Input/Output
hStream	WDU_STREAM_HANDLE	Input

DESCRIPTION

Name	Description
hStream	A unique identifier for the stream, as returned by `WDU_StreamOpen`

RETURN VALUE

Returns WD_STATUS_SUCCESS(0) on success, or an appropriate error code otherwise [B.8].

B.4.9.3 WDU_StreamRead

PURPOSE

• Reads data from a read stream to the application.

For a blocking stream (fBlocking=TRUE – see WDU_StreamOpen), the call to this function is blocked until the specified amount of data (bytes ) is read, or until the stream's attempt to read from the device times out (i.e. the timeout period for transfers between the stream and the device, as set in the dwRxTxTimeout WDU_StreamOpen parameter [B.4.9.1], expires).

For a non-blocking stream (fBlocking=FALSE), the function transfers to the application as much of the requested data as possible, subject to the amount of data currently available in the stream's data buffer, and returns immediately.

For both blocking and non-blocking transfers, the function returns the amount of bytes that were actually read from the stream within the pdwBytesRead parameter.

PROTOTYPE

DWORD DLLCALLCONV WDU_StreamRead(
    HANDLE hStream, 
    PVOID pBuffer, 
    DWORD bytes,
    DWORD *pdwBytesRead);

PARAMETERS

Name	Type	Input/Output
hStream	WDU_STREAM_HANDLE	Input
pBuffer	PVOID	Output
bytes	DWORD	Input
pdwBytesRead	DWORD*	Output

DESCRIPTION

Name	Description
hStream	A unique identifier for the stream, as returned by `WDU_StreamOpen`
pBuffer	Pointer to a data buffer to be filled with the data read from the stream
bytes	Number of bytes to read from the stream
pdwBytesRead	Pointer to a value indicating the number of bytes actually read from the stream

RETURN VALUE

Returns WD_STATUS_SUCCESS(0) on success, or an appropriate error code otherwise [B.8].

B.4.9.4 WDU_StreamWrite

PURPOSE

• Writes data from the applciation to a write stream.

For a blocking stream (fBlocking=TRUE – see WDU_StreamOpen), the call to this function is blocked until the entire data is written to the stream, or until the stream's attempt to write to the device times out (i.e. the timeout period for transfers between the stream and the device, as set in the dwRxTxTimeout WDU_StreamOpen parameter [B.4.9.1], expires).

For a non-blocking stream (fBlocking=FALSE), the function writes as much data as currently possible to the stream's data buffer, and returns immediately.

For both blocking and non-blocking transfers, the function returns the amount of bytes that were actually written to the stream within the pdwBytesWritten parameter.

PROTOTYPE

DWORD DLLCALLCONV WDU_StreamWrite(
    HANDLE hStream, 
    const PVOID pBuffer, 
    DWORD bytes, 
    DWORD *pdwBytesWritten);

PARAMETERS

Name	Type	Input/Output
hStream	WDU_STREAM_HANDLE	Input
pBuffer	const PVOID	Input
bytes	DWORD	Input
pdwBytesWritten	DWORD*	Output

DESCRIPTION

Name	Description
hStream	A unique identifier for the stream, as returned by `WDU_StreamOpen`
pBuffer	Pointer to a data buffer containing the data to write to the stream
bytes	Number of bytes to write to the stream
pdwBytesWritten	Pointer to a value indicating the number of bytes actually written to the stream

RETURN VALUE

Returns WD_STATUS_SUCCESS(0) on success, or an appropriate error code otherwise [B.8].

B.4.9.5 WDU_StreamFlush

PURPOSE

• Flushes a write stream, i.e. writes the entire contents of the stream's data buffer to the device.
• Blocks until the completion of all pending I/O on the stream.


	This function can be called for both blocking and non-blocking streams.

This function can be called for both blocking and non-blocking streams.

PROTOTYPE

DWORD DLLCALLCONV WDU_StreamFlush(
    WDU_STREAM_HANDLE hStream);

PARAMETERS

Name	Type	Input/Output
hStream	WDU_STREAM_HANDLE	Input

DESCRIPTION

Name	Description
hStream	A unique identifier for the stream, as returned by `WDU_StreamOpen`

RETURN VALUE

Returns WD_STATUS_SUCCESS(0) on success, or an appropriate error code otherwise [B.8].

B.4.9.6 WDU_StreamGetStatus

PURPOSE

• Returns a stream's current status.

PROTOTYPE

DWORD DLLCALLCONV WDU_StreamGetStatus(
    WDU_STREAM_HANDLE hStream, 
    BOOL *pfIsRunning,
    DWORD *pdwLastError,
    DWORD *pdwBytesInBuffer);

PARAMETERS

Name	Type	Input/Output
hStream	WDU_STREAM_HANDLE	Input
pfIsRunning	BOOL*	Output
pdwLastError	DWORD*	Output
pdwBytesInBuffer	DWORD*	Output

DESCRIPTION

Name	Description
hStream	A unique identifier for the stream, as returned by `WDU_StreamOpen`
pfIsRunning	Pointer to a value indicating the stream's current state: • `TRUE` – the stream is currently running • `FALSE` – the stream is currently stopped
pdwLastError	Pointer to the last error associated with the stream. Note: Calling the function also resets the stream's last error.
pdwBytesInBuffer	Pointer to the current bytes count in the stream's data buffer

RETURN VALUE

Returns WD_STATUS_SUCCESS(0) on success, or an appropriate error code otherwise [B.8].

B.4.9.7 WDU_StreamStop

PURPOSE

• Stops an active stream, i.e. stops transfers between the stream and the device.
In the case of a write stream, the function flushes the stream – i.e. writes its contents to the device – before stopping it.

PROTOTYPE

DWORD DLLCALLCONV WDU_StreamStop(
    WDU_STREAM_HANDLE hStream);

PARAMETERS

Name	Type	Input/Output
hStream	WDU_STREAM_HANDLE	Input

DESCRIPTION

Name	Description
hStream	A unique identifier for the stream, as returned by `WDU_StreamOpen`

RETURN VALUE

Returns WD_STATUS_SUCCESS(0) on success, or an appropriate error code otherwise [B.8].

B.4.9.8 WDU_StreamClose

PURPOSE

• Closes an open stream.
The function stops the stream, including flushing its data to the device (in the case of a write stream), before closing it.

PROTOTYPE

DWORD DLLCALLCONV WDU_StreamClose(
    WDU_STREAM_HANDLE hStream);

PARAMETERS

Name	Type	Input/Output
hStream	WDU_STREAM_HANDLE	Input

DESCRIPTION

Name	Description
hStream	A unique identifier for the stream, as returned by `WDU_StreamOpen`

RETURN VALUE

Returns WD_STATUS_SUCCESS(0) on success, or an appropriate error code otherwise [B.8].

B.4.10 WDU_ResetPipe

PURPOSE

• Resets a pipe by clearing both the halt condition on the host side of the pipe and the stall condition on the endpoint. This function is applicable for all pipes except pipe00.

PROTOTYPE

DWORD WDU_ResetPipe(
    WDU_DEVICE_HANDLE hDevice,
    DWORD dwPipeNum);

PARAMETERS

Name	Type	Input/Output
hDevice	WDU_DEVICE_HANDLE	Input
dwPipeNum	DWORD	Input

DESCRIPTION

Name	Description
hDevice	A unique identifier for the device/interface
dwPipeNum	The pipe's number

RETURN VALUE

status

REMARKS

This function should be used if a pipe is halted, in order to clear the halt.

B.4.11 WDU_ResetDevice

PURPOSE

• Resets a device.

PROTOTYPE

DWORD WDU_ResetDevice(
    WDU_DEVICE_HANDLE hDevice,
    DWORD dwOptions);

PARAMETERS

Name	Type	Input/Output
hDevice	WDU_DEVICE_HANDLE	Input
dwOptions	DWORD	Input

DESCRIPTION

Name Description

hDevice A unique identifier for the device/interface.

dwOptions Can be either zero or:
• WD_USB_HARD_RESET – reset the device even if it is not disabled. After using this option it is advised to set the interface device using WDU_SetInterface [B.4.2].
• WD_USB_CYCLE_PORT – simulate unplugging and replugging of the device, prompting the operating system to re-enumerate the device without resetting it.
This option is supported only on Windows XP and higher.

RETURN VALUE

Returns WD_STATUS_SUCCESS(0) on success, or an appropriate error code otherwise [B.8].

REMARKS

WDU_ResetDevice is supported only on Windows and Windows CE, beginning with Windows CE 5.0.
The WD_USB_CYCLE_PORT option is supported on Windows XP and higher.
The function issues a request from the Windows USB driver to reset a hub port, provided the Windows USB driver supports this feature.

B.4.12 WDU_SelectiveSuspend

PURPOSE

• Submits a request to suspend a given device (selective suspend), or cancels a previous suspend request.

PROTOTYPE

DWORD DLLCALLCONV WDU_SelectiveSuspend(
    WDU_DEVICE_HANDLE hDevice, 
    DWORD dwOptions);

PARAMETERS

Name	Type	Input/Output
hDevice	WDU_DEVICE_HANDLE	Input
dwOptions	DWORD	Input

DESCRIPTION

Name	Description
hDevice	A unique identifier for the device/interface.
dwOptions	Can be set to either of the following `WDU_SELECTIVE_SUSPEND_OPTIONS` values: • `WDU_SELECTIVE_SUSPEND_SUBMIT` – submit a request to suspend the device. • `WDU_SELECTIVE_SUSPEND_CANCEL` – cancel a previous request to suspend the device.

RETURN VALUE

Returns WD_STATUS_SUCCESS(0) on success, or an appropriate error code otherwise [B.8]. If the device is busy when a suspend request is submitted (dwOptions=WDU_SELECTIVE_SUSPEND_SUBMIT), the function returns WD_OPERATION_FAILED.

REMARKS

WDU_SelectiveSuspend is supported on Windows XP and higher.

B.4.13 WDU_Wakeup

PURPOSE

• Enables/Disables the wakeup feature.

PROTOTYPE

DWORD WDU_Wakeup(
    WDU_DEVICE_HANDLE hDevice,
    DWORD dwOptions);

PARAMETERS

Name	Type	Input/Output
hDevice	WDU_DEVICE_HANDLE	Input
dwOptions	DWORD	Input

DESCRIPTION

Name	Description
hDevice	A unique identifier for the device/interface
dwOptions	Can be either: • `WDU_WAKEUP_ENABLE` – enable wakeup OR: • `WDU_WAKEUP_DISABLE` – disable wakeup

RETURN VALUE

Returns WD_STATUS_SUCCESS(0) on success, or an appropriate error code otherwise [B.8].

B.4.14 WDU_GetLangIDs

PURPOSE

• Reads a list of supported language IDs and/or the number of supported language IDs from a device.

PROTOTYPE

DWORD DLLCALLCONV WDU_GetLangIDs(
    WDU_DEVICE_HANDLE hDevice, 
    PBYTE pbNumSupportedLangIDs,
    WDU_LANGID *pLangIDs,
    BYTE bNumLangIDs);

PARAMETERS

Name	Type	Input/Output
hDevice	WDU_DEVICE_HANDLE	Input
pbNumSupportedLangIDs	PBYTE	Output
pLangIDs	WDU_LANGID*	Output
bNumLangIDs	BYTE	Input

DESCRIPTION

Name	Description
hDevice	A unique identifier for the device/interface
pbNumSupportedLangIDs	Parameter to receive number of supported language IDs
pLangIDs	Array of language IDs. If `bNumLangIDs` is not zero the function will fill this array with the supported language IDs for the device.
bNumLangIDs	Number of IDs in the pLangIDs array

RETURN VALUE

Returns WD_STATUS_SUCCESS(0) on success, or an appropriate error code otherwise [B.8].

REMARKS

If dwNumLangIDs is zero the function will return only the number of supported language IDs (in pbNumSupportedLangIDs ) but will not update the language IDs array (pLangIDs ) with the actual IDs. For this usage pLangIDs can be NULL (since it is not referenced) but pbNumSupportedLangIDs must not be NULL.
pbNumSupportedLangIDs can be NULL if the user only wants to receive the list of supported language IDs and not the number of supported IDs.
In this case bNumLangIDs cannot be zero and pLangIDs cannot be NULL.
If the device does not support any language IDs the function will return success. The caller should therefore check the value of *pbNumSupportedLangIDs after the function returns.
If the size of the pLangIDs array (bNumLangIDs ) is smaller than the number of IDs supported by the device (*pbNumSupportedLangIDs ), the function will read and return only the first bNumLangIDs supported language IDs.

B.4.15 WDU_GetStringDesc

PURPOSE

• Reads a string descriptor from a device by string index.

PROTOTYPE

DWORD DLLCALLCONV WDU_GetStringDesc(
    WDU_DEVICE_HANDLE hDevice, 
    BYTE bStrIndex, 
    PBYTE pbBuf, 
    DWORD dwBufSize, 
    WDU_LANGID langID, 
    PDWORD pdwDescSize);

PARAMETERS

Name	Type	Input/Output
hDevice	WDU_DEVICE_HANDLE	Input
bStrIndex	BYTE	Input
pbBuf	PBYTE	Output
dwBufSize	DWORD	Input
langID	WDU_LANGID	Input
pdwDescSize	PDWORD	Output

DESCRIPTION

Name	Description
hDevice	A unique identifier for the device/interface
bStrIndex	The index of the string descriptor to read
pbBuf	Pointer to a buffer to be filled with the string descriptor
dwBufSize	The size of the `pbBuf` buffer, in bytes
langID	The language ID to be used in the get string descriptor request. If this parameter is 0, the request will use the first supported language ID returned by the device.
pdwDescSize	An optional DWORD pointer to be filled with the size of the string descriptor read from the device. If `NULL`, the size of the string descriptor will not be returned.

RETURN VALUE

Returns WD_STATUS_SUCCESS(0) on success, or an appropriate error code otherwise [B.8].

REMARKS

If the size of the pbBuf buffer is smaller than the size of the string descriptor (dwBufSize*pdwDescSize ), the returned descriptor will be truncated to the provided buffer size (dwBufSize ).