B.4. USB Functions

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
NameTypeInput/Output
phDriverWDU_DRIVER_HANDLE *Output
pMatchTablesWDU_MATCH_TABLE*Input
dwNumMatchTablesDWORDInput
pEventTableWDU_EVENT_TABLE*Input
sLicenseconst char*Input
dwOptionsDWORDInput
Description
NameDescription
phDriverHandle to the registration of events & criteria
pMatchTables Array of match tables [B.5.2.1] defining the devices' criteria
dwNumMatchTablesNumber 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
sLicenseWinDriver'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
NameTypeInput/Output
hDeviceWDU_DEVICE_HANDLEInput
dwInterfaceNumDWORDInput
dwAlternateSettingDWORDInput
Description
NameDescription
hDeviceA unique identifier for the device/interface
dwInterfaceNumThe interface's number
dwAlternateSettingThe desired alternate setting value
Return Value

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

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
NameTypeInput/Output
hDeviceWDU_DEVICE_HANDLEInput
pAddressULONGOutput
Description
NameDescription
hDeviceA unique identifier for a device/interface
pAddressA 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 and Linux.

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
NameTypeInput/Output
hDeviceWDU_DEVICE_HANDLEInput
pBufferPVOIDOutput
pdwSizePDWORDInput/Output
propertyWD_DEVICE_REGISTRY_PROPERTYInput
Description
NameDescription
hDeviceA 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 and Linux. On Linux, only WdDevicePropertyAddress and WdDevicePropertyBusNumber properties are supported.

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
NameTypeInput/Output
hDeviceWDU_DEVICE_HANDLEInput
ppDeviceInfoWDU_DEVICE**Output
Description
NameDescription
hDeviceA 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
NameTypeInput/Output
pDeviceInfoWDU_DEVICE*Input
Description
NameDescription
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 unregisters the notification callbacks for these devices.

Prototype
void WDU_Uninit(WDU_DRIVER_HANDLE hDriver);
Parameters
NameTypeInput/Output
hDriverWDU_DRIVER_HANDLEInput
Description
NameDescription
hDriverHandle 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 Section 8.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
NameTypeInput/Output
hDeviceWDU_DEVICE_HANDLEInput
dwPipeNumDWORDInput
fReadDWORDInput
dwOptionsDWORDInput
pBufferPVOIDInput
dwBufferSizeDWORDInput
pdwBytesTransferredPDWORDOutput
pSetupPacketPBYTEInput
dwTimeoutDWORDInput
Description
NameDescription
hDevice A unique identifier for the device/interface received from WDU_Init() [B.4.1]
dwPipeNumThe number of the pipe through which the data is transferred
fReadTRUE for read, FALSE for write
dwOptions A bit-mask of USB transfer options, which can consist of a combination of any of the following flags:
USB_ISOCH_NOASAP — Instructs the lower USB stack driver (usbd.sys) to use a preset frame number (instead of the next available frame) for an isochronous data transfer.
It is recommended that you use this flag for isochronous write (OUT) transfers, and if you notice unused frames during transfers on low-speed or full-speed USB 1.1 devices.
This flag is available only for Windows.
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 available only for Windows.
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.
pBufferAddress 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.
pdwBytesTransferredNumber of bytes actually transferred
pSetupPacketAn 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
NameTypeInput/Output
hDeviceWDU_DEVICE_HANDLEInput
dwPipeNumDWORDInput
Description
NameDescription
hDeviceA unique identifier for the device/interface
dwPipeNumThe number of the pipe
Return Value

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

B.4.8.3. WDU_TransferDefaultPipe

Purpose

Transfers data to or from a device through the default control pipe (pipe 0).

Prototype
DWORD WDU_TransferDefaultPipe(
    WDU_DEVICE_HANDLE hDevice,
    DWORD fRead,
    DWORD dwOptions,
    PVOID pBuffer,
    DWORD dwBufferSize,
    PDWORD pdwBytesTransferred,
    PBYTE pSetupPacket,
    DWORD dwTimeout);
[Note]
Refer to the WDU_Transfer() parameters documentation [B.4.8.1], except for dwPipeNum (N/A).
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);
[Note]
Refer to the WDU_Transfer() parameters documentation [B.4.8.1], except for pSetupPacket (N/A).
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);
[Note]
Refer to the WDU_Transfer() parameters documentation [B.4.8.1], except for pSetupPacket (N/A).
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);
[Note]
Refer to the WDU_Transfer() parameters documentation [B.4.8.1], except for pSetupPacket (N/A).
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 Section 8.3.3 of the manual.

[Note]
The streaming APIs are currently supported on Windows.

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
NameTypeInput/Output
hDeviceWDU_DEVICE_HANDLEInput
dwPipeNumDWORDInput
dwBufferSizeDWORDInput
dwRxSizeDWORDInput
fBlockingBOOLInput
dwOptionsDWORDInput
dwRxTxTimeoutDWORDInput
phStreamWDU_STREAM_HANDLE*Output
Description
NameDescription
hDeviceA unique identifier for the device/interface
dwPipeNumThe number of the pipe for which to open the stream
dwBufferSizeThe 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.
fBlockingTRUE 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 Section 8.3.3.1.
dwOptions A bit-mask of USB transfer options, which can consist of a combination of any of the following flags:
USB_ISOCH_NOASAP — Instructs the lower USB stack driver (usbd.sys) to use a preset frame number (instead of the next available frame) for an isochronous data transfer.
It is recommended that you use this flag for isochronous write (OUT) transfers, and if you notice unused frames during transfers on low-speed or full-speed USB 1.1 devices.
This flag is available only for Windows.
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 available only for 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.
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
NameTypeInput/Output
hStreamWDU_STREAM_HANDLEInput
Description
NameDescription
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
NameTypeInput/Output
hStreamWDU_STREAM_HANDLEInput
pBufferPVOIDOutput
bytesDWORDInput
pdwBytesReadDWORD*Output
Description
NameDescription
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
bytesNumber 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 WD_OPERATION_FAILED on failure.
In case of failure, call WDU_StreamGetStatus() [B.4.9.6] to get the current stream status.

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
NameTypeInput/Output
hStreamWDU_STREAM_HANDLEInput
pBufferconst PVOIDInput
bytesDWORDInput
pdwBytesWrittenDWORD*Output
Description
NameDescription
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
bytesNumber 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 WD_OPERATION_FAILED on failure.
In case of failure, call WDU_StreamGetStatus() [B.4.9.6] to get the current stream status.

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.
The function blocks until the completion of all pending I/O on the stream.

[Note]
This function can be called for both blocking and non-blocking streams.
Prototype
DWORD DLLCALLCONV WDU_StreamFlush(
    WDU_STREAM_HANDLE hStream);
Parameters
NameTypeInput/Output
hStreamWDU_STREAM_HANDLEInput
Description
NameDescription
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
NameTypeInput/Output
hStreamWDU_STREAM_HANDLEInput
pfIsRunningBOOL*Output
pdwLastErrorDWORD*Output
pdwBytesInBufferDWORD*Output
Description
NameDescription
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
NameTypeInput/Output
hStreamWDU_STREAM_HANDLEInput
Description
NameDescription
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
NameTypeInput/Output
hStreamWDU_STREAM_HANDLEInput
Description
NameDescription
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 the control pipe (pipe 0).

Prototype
DWORD WDU_ResetPipe(
    WDU_DEVICE_HANDLE hDevice,
    DWORD dwPipeNum);
Parameters
NameTypeInput/Output
hDeviceWDU_DEVICE_HANDLEInput
dwPipeNumDWORDInput
Description
NameDescription
hDeviceA unique identifier for the device/interface
dwPipeNumThe pipe's number
Return Value

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

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
NameTypeInput/Output
hDeviceWDU_DEVICE_HANDLEInput
dwOptionsDWORDInput
Description
NameDescription
hDeviceA 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 7 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.
    The WD_USB_CYCLE_PORT option is supported on Windows 7 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
NameTypeInput/Output
hDeviceWDU_DEVICE_HANDLEInput
dwOptionsDWORDInput
Description
NameDescription
hDeviceA 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 7 and higher.

B.4.13. WDU_Wakeup

Purpose

Enables/Disables the wakeup feature.

Prototype
DWORD WDU_Wakeup(
    WDU_DEVICE_HANDLE hDevice,
    DWORD dwOptions);
Parameters
NameTypeInput/Output
hDeviceWDU_DEVICE_HANDLEInput
dwOptionsDWORDInput
Description
NameDescription
hDeviceA 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
NameTypeInput/Output
hDeviceWDU_DEVICE_HANDLEInput
pbNumSupportedLangIDsPBYTEOutput
pLangIDsWDU_LANGID*Output
bNumLangIDsBYTEInput
Description
NameDescription
hDeviceA unique identifier for the device/interface
pbNumSupportedLangIDsParameter 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.
bNumLangIDsNumber 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
NameTypeInput/Output
hDeviceWDU_DEVICE_HANDLEInput
bStrIndexBYTEInput
pbBufPBYTEOutput
dwBufSizeDWORDInput
langIDWDU_LANGIDInput
pdwDescSizePDWORDOutput
Description
NameDescription
hDeviceA unique identifier for the device/interface
bStrIndexThe index of the string descriptor to read
pbBufPointer to a buffer to be filled with the string descriptor
dwBufSizeThe 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 ).