WDK中的Usermode USB Routine

WinUsb_WritePipe

The WinUsb_WritePipe function writes data to a pipe.

BOOL __stdcall
  WinUsb_WritePipe (
    IN WINUSB_INTERFACE_HANDLE  InterfaceHandle,
    IN UCHAR  PipeID,
    IN PUCHAR  Buffer,
    IN ULONG  BufferLength,
    OUT PULONG  LengthTransferred,
    IN LPOVERLAPPED  Overlapped
  );

Parameters

InterfaceHandle

The interface handle that WinUsb_Initialize returned.

 

PipeID

An 8-bit value that consists of a 7-bit address and a direction bit. This parameter corresponds to the bEndpointAddress field in the endpoint descriptor.

 

Buffer

A caller-allocated buffer that contains the data to write.

 

BufferLength

The number of bytes to write. This number must be less than or equal to the size, in bytes, of Buffer.

 

LengthTransferred

A pointer to a ULONG variable that receives the actual number of bytes that were written to the pipe.

 

Overlapped

An optional pointer to an OVERLAPPED structure, which is used for asynchronous operations. If this parameter is specified, WinUsb_WritePipe immediately returns, and the event is signaled when the operation is complete.

 

Return Value

WinUsb_WritePipe returns TRUE if the operation succeeds. Otherwise, this routine returns FALSE, and the caller can retrieve the logged error by calling GetLastError.

WinUsb_SetPipePolicy

The WinUsb_SetPipePolicy function sets the policy for a specific pipe (endpoint).

BOOL __stdcall
  WinUsb_SetPipePolicy (
    IN WINUSB_INTERFACE_HANDLE  InterfaceHandle,
    IN UCHAR  PipeID,
    IN ULONG  PolicyType,
    IN ULONG  ValueLength,
    IN PVOID  Value
  );

Parameters

InterfaceHandle

The interface handle that WinUsb_Initialize returned.

 

PipeID

An 8-bit value that consists of a 7-bit address and a direction bit. This parameter corresponds to the bEndpointAddress field in the endpoint descriptor.

 

PolicyType

A value that specifies the policy parameter to change. The following table describes symbolic constants that are defined in winusbio.h.

Policy parameter	Description
SHORT_PACKET_TERMINATE (0x01)	If the caller specifies a policy of SHORT_PACKET_TERMINATE in PolicyType, WinUsb_SetPipePolicy sets the short packet terminate policy parameter to the value that the caller specifies in Value. If the short packet terminate policy parameter is TRUE (that is, nonzero), every write request that is a multiple of the maximum packet size for the endpoint is terminated with a zero-length packet. The default value of the short packet terminate policy parameter is FALSE. The Value parameter must point to a UCHAR variable.
AUTO_CLEAR_STALL (0x02)	If the caller specifies a policy of AUTO_CLEAR_STALL in PolicyType, WinUsb_SetPipePolicy sets the auto clear stall policy parameter to the value that the caller specifies in Value. If the auto clear stall policy parameter is TRUE (that is, nonzero), the driver fails stalled data transfers, but the driver clears the stall condition automatically, and data continues to flow on the pipe. This policy parameter does not affect control pipes. The default value for the auto clear stall policy parameter is FALSE. Value must point to a UCHAR variable.
PIPE_TRANSFER_TIMEOUT (0x03)	If the caller specifies a policy of PIPE_TRANSFER_TIMEOUT in PolicyType, WinUsb_SetPipePolicy sets the pipe transfer timeout policy parameter to the value that the caller specifies in Value. The pipe transfer timeout policy parameter specifies the time-out interval, in milliseconds. The host cancels transfers that do not complete within the time-out interval. A value of zero means that transfers do not time out. By default, the time-out value is zero, and the host never cancels a transfer because of a time-out. The Value parameter must point to a ULONG variable.
IGNORE_SHORT_PACKETS (0x04)	If the caller specifies a policy of IGNORE_SHORT_PACKETS in PolicyType, WinUsb_SetPipePolicy sets the ignore short packets policy parameter to the value that the caller specifies in Value. If the ignore short packets policy parameter is TRUE (that is, nonzero), the host does not complete a read operation after it receives a short packet. Instead, the the host completes the operation only after the host has read the specified number of bytes. If the ignore short packets policy parameter is FALSE, the host completes a read operation when either the host has read the specified number of bytes or the host has received a short packet. The default value of the ignore short packets policy parameter is FALSE. Value must point to a UCHAR variable.
ALLOW_PARTIAL_READS (0x05)	If the caller specifies a policy of ALLOW_PARTIAL_READS in PolicyType, WinUsb_SetPipePolicy sets the short packet terminate policy parameter to the value that the caller specifies in Value. If the allow partial reads policy parameter is FALSE (that is, zero), the read request fails whenever the device returns more data than the client requested. If the allow partial reads policy parameter is TRUE, the WinUSB driver saves the extra data and sends the extra data to the client during the client's next read. The default value of the allow partial reads policy parameter is TRUE. Value must point to a UCHAR variable.
AUTO_FLUSH (0x06)	If the caller specifies a policy of AUTO_FLUSH in PolicyType, WinUsb_SetPipePolicy sets the auto flush policy parameter to the value that the caller specifies in Value. The auto flush policy parameter works with allow partial reads. If allow partial reads is FALSE, the WinUSB driver ignores the value of auto flush. If allow partial reads is TRUE, the value of auto flush determines what the WinUSB driver does when the device returns more data than the client requested. If both allow partial reads and auto flush policy parameters are TRUE (that is, nonzero) and the device returns more data than the client requested, the remaining data is discarded. If allow partial reads is TRUE, but auto flush is FALSE, the WinUSB driver caches the extra data and sends it to the client in the next read operation. The default value of the auto flush policy parameter is FALSE. Value must point to a UCHAR variable.
RAW_IO (0x07)	If the caller specifies a policy of RAW_IO in PolicyType, WinUsb_SetPipePolicy sets the raw i/o policy parameter to the value that the caller specifies in Value. If the raw i/o policy parameter is TRUE (that is, nonzero), calls to WinUsb_ReadPipe and WinUsb_WritePipe for the specified endpoint must satisfy the following conditions: The buffer length must be a multiple of the maximum endpoint packet size. The length must be less than what the host controller supports. If the preceding conditions are met, WinUSB sends data directly to the USB driver stack, bypassing WinUSB's queuing and error handling. If the raw i/o policy parameter is FALSE, no restrictions are imposed on the buffers that are passed to WinUsb_ReadPipe and WinUsb_WritePipe. The default value of the raw i/o policy parameter is FALSE. Value must point to a UCHAR variable.

 

 

 

ValueLength

The size, in bytes, of the buffer at Value .

 

Value

The new value for the policy parameter that PolicyType specifies. The size of this input parameter depends on the policy to change. For information about the size of this parameter, see the description of the PolicyType parameter.

 

Return Value

WinUsb_SetPipePolicy returns TRUE if the operation succeeds. Otherwise, this routine returns FALSE, and the caller can retrieve the logged error by calling GetLastError.

WinUsb_SetInterfacePowerPolicy

The WinUsb_SetInterfacePowerPolicy routine sets the power policy for a device.

BOOL __stdcall
  WinUsb_SetInterfacePowerPolicy (
    WINUSB_INTERFACE_HANDLE  InterfaceHandle,
    ULONG  PolicyType,
    ULONG  ValueLength,
    PVOID  Value
  );

Parameters

InterfaceHandle

The interface handle that WinUsb_Initialize returned.

 

PolicyType

A value that specifies the power policy to set. The following table describes symbolic constants that are defined in winusbio.h.

Policy parameter	Description
AUTO_SUSPEND (0x01)	If the caller specifies a policy of AUTO_SUSPEND in PolicyType, WinUsb_SetInterfacePowerPolicy sets the auto suspend policy parameter to the value that the caller specifies in Value. If the auto suspend policy parameter is TRUE (that is, nonzero), the USB stack suspends the device when no transfers are pending. The default value for the AUTO_SUSPEND policy parameter is TRUE. The Value parameter must point to a UCHAR variable.
ENABLE_WAKE (0x02)	If the caller specifies a policy of ENABLE_WAKE in PolicyType, WinUsb_SetInterfacePowerPolicy sets the enable wake policy parameter to the value that the caller specifies in Value. If the enable wake policy parameter is TRUE (that is, nonzero), remote wake is enabled on the device. The default value of the ENABLE_WAKE policy parameter is FALSE (that is, zero). Value must point to a UCHAR variable.
SUSPEND_DELAY (0x03)	If the caller specifies a policy of SUSPEND_DELAY in PolicyType, WinUsb_SetInterfacePowerPolicy sets the suspend delay policy parameter to the value that the caller specifies in Value. The suspend delay policy parameter specifies the minimum amount of time, in milliseconds, that the WinUSB driver must wait after any transfer before it can suspend the device. Value must point to a UCHAR variable.

 

 

 

ValueLength

The size, in bytes, of the buffer at Value.

 

Value

The new value for the policy parameter that PolicyType specifies.

 

Return Value

WinUsb_SetInterfacePowerPolicy returns TRUE if the operation succeeds. Otherwise, this routine returns FALSE, and the caller can retrieve the logged error by calling GetLastError.

Comments

The following list summarizes the effects of changes to power management states:

• All pipe handles, interface handles, locks, and alternate settings are preserved across power management events.

   

• Any transfers that are in progress are suspended when a device transfers to a low power state, and they are resumed when the device is restored to a working state.

   

   

• The device and system must be in a working state before the client can restore a device-specific configuration. Clients can determine whether the device and system are in a working state from the WM_POWERBROADCAST message.

   

   

• The client can indicate that an interface is idle by calling WinUsb_SetInterfacePowerPolicy. The caller can specify that the device should be enabled for a remote wakeup while idle.

WinUsb_SetCurrentAlternateSetting

The WinUsb_SetCurrentAlternateSetting routine sets the alternate setting of an interface.

BOOL __stdcall
  WinUsb_SetCurrentAlternateInterface (
    IN WINUSB_INTERFACE_HANDLE  InterfaceHandle,
    IN UCHAR  AlternateSetting
  );

Parameters

InterfaceHandle

The interface handle that WinUsb_Initialize returned.

 

AlternateSetting

The value that is contained in the bAlternateSetting member of the USB_INTERFACE_DESCRIPTOR structure. This structure is populated by the WinUsb_QueryInterfaceSettings routine.

 

Return Value

WinUsb_SetCurrentAlternateSetting returns TRUE if the operation succeeds. Otherwise, this routine returns FALSE, and the caller can retrieve the logged error by calling GetLastError.

Comments

WinUsb_SetCurrentAlternateSetting fails if there are outstanding I/O requests on the interface.

WinUsb_ResetPipe

The WinUsb_ResetPipe routine resets the data toggle and clears the stall condition on a pipe.

BOOL __stdcall
  WinUsb_ResetPipe (
    IN WINUSB_INTERFACE_HANDLE  InterfaceHandle,
    IN UCHAR  PipeID
  );

Parameters

InterfaceHandle

The interface handle that WinUsb_Initialize returned.

 

PipeID

The identifier (ID) of the control pipe. The PipeID parameter is an 8-bit value that consists in a 7-bit address and a direction bit. This parameter corresponds to the bEndpointAddress field in the endpoint descriptor.

 

Return Value

WinUsb_ResetPipe returns TRUE if the operation succeeds. Otherwise, this routine returns FALSE, and the caller can retrieve the logged error by calling GetLastError.

WinUsb_ReadPipe

The WinUsb_ReadPipe function reads data from a pipe.

BOOL __stdcall
  WinUsb_ReadPipe (
    IN WINUSB_INTERFACE_HANDLE  InterfaceHandle,
    IN UCHAR  PipeID,
    IN PUCHAR  Buffer,
    IN ULONG  BufferLength,
    OUT PULONG  LengthTransferred,
    IN LPOVERLAPPED  Overlapped
  );

Parameters

InterfaceHandle

The interface handle that WinUsb_Initialize returned.

 

PipeID

An 8-bit value that consists of a 7-bit address and a direction bit. This parameter corresponds to the bEndpointAddress field in the endpoint descriptor.

 

Buffer

A caller-allocated buffer that receives the data that is read.

 

BufferLength

The maximum number of bytes to read. This number must be less than or equal to the size, in bytes, of Buffer.

 

LengthTransferred

A pointer to a ULONG variable that receives the actual number of bytes that were copied into Buffer.

 

Overlapped

An optional pointer to an OVERLAPPED structure that is used for asynchronous operations. If this parameter is specified, WinUsb_ReadPipe returns immediately rather than waiting synchronously for the operation to complete before returning. An event is signaled when the operation is complete.

 

Return Value

WinUsb_ReadPipe returns TRUE if the operation succeeds. Otherwise, this routine returns FALSE, and the caller can retrieve the logged error by calling GetLastError.

WinUsb_QueryPipe

The WinUsb_QueryPipe routine returns information about a pipe that is associated with an interface.

BOOL __stdcall
  WinUsb_QueryPipe (
    IN WINUSB_INTERFACE_HANDLE  InterfaceHandle,
    IN UCHAR  AlternateInterfaceNumber,
    IN UCHAR  PipeIndex,
    OUT PWINUSB_PIPE_INFORMATION  PipeInformation
  );

Parameters

InterfaceHandle

The interface handle that WinUsb_Initialize returned.

 

AlternateInterfaceNumber

A value that specifies the alternate interface to return the information for.

 

PipeIndex

A value that specifies the pipe to return information about. This value is not the same as the bEndpointAddress field in the endpoint descriptor. A PipeIndex value of 0 signifies the first endpoint that is associated with the interface, a value of 1 signifies the second endpoint, and so on. PipeIndex must be less than the value in the bNumEndpoints field of the interface descriptor.

 

PipeInformation

A pointer, on output, to a caller-allocated WINUSB_PIPE_INFORMATION structure that contains pipe information.

 

Return Value

WinUsb_QueryPipe returns TRUE if the operation succeeds. Otherwise, this routine returns FALSE, and the caller can retrieve the logged error by calling GetLastError.

Comments

The WinUsb_QueryPipe routine does not retrieve information about the control pipe.

WinUsb_QueryInterfaceSettings

The WinUsb_QueryInterfaceSettings function returns the interface descriptor for the specified alternate interface settings for a particular interface handle.

BOOL __stdcall
  WinUsb_QueryInterfaceSettings (
    IN WINUSB_INTERFACE_HANDLE  InterfaceHandle,
    IN UCHAR  AlternateSettingNumber,
    OUT PUSB_INTERFACE_DESCRIPTOR  UsbAltInterfaceDescriptor
  );

Parameters

InterfaceHandle

The interface handle that WinUsb_Initialize returned.

 

AlternateSettingNumber

A value that indicates which alternate settings to return. A value of 0 indicates the first alternate setting, a value of 1 indicates the second alternate setting, and so on.

 

UsbAltInterfaceDescriptor

A pointer to a caller-allocated USB_INTERFACE_DESCRIPTOR structure that contains information about the interface that AlternateSettingNumber specified.

 

Return Value

WinUsb_QueryInterfaceSettings returns TRUE if the operation succeeds. Otherwise, it returns FALSE, and the caller can retrieve the logged error by calling GetLastError.

WinUsb_QueryDeviceInformation

The WinUsb_QueryDeviceInformation routine returns information about the physical device that is associated with a WinUSB interface.

BOOL __stdcall
  WinUsb_QueryDeviceInformation (
    IN WINUSB_INTERFACE_HANDLE  InterfaceHandle,
    IN ULONG  InformationType,
    IN OUT PULONG  BufferLength,
    OUT PVOID  Buffer
  );

Parameters

InterfaceHandle

The interface handle that WinUsb_Initialize returned.

 

InformationType

A value that specifies which interface information value to retrieve.

On input, InformationType must have the following value: DEVICE_SPEED (0x01).

On output, InformationType has one of the following values: LowSpeed (0x01), FullSpeed (0x02), or HighSpeed (0x03).

 

BufferLength

The maximum number of bytes to read. This number must be less than or equal to the size, in bytes, of Buffer. On output, BufferLength is set to the actual number of bytes that were copied into Buffer.

 

Buffer

A caller-allocated buffer that receives the requested value.

 

Return Value

WinUsb_QueryDeviceInformation returns TRUE if the operation succeeds. Otherwise, this routine returns FALSE, and the caller can retrieve the logged error by calling GetLastError.

WinUsb_GetPipePolicy

The WinUsb_GetPipePolicy function retrieves the policy for a specific pipe (endpoint).

BOOL __stdcall
  WinUsb_GetPipePolicy (
    IN WINUSB_INTERFACE_HANDLE  InterfaceHandle,
    IN UCHAR  PipeID,
    IN ULONG  PolicyType,
    IN OUT PULONG  ValueLength,
    OUT PVOID  Value
  );

Parameters

InterfaceHandle

The interface handle that WinUsb_Initialize returned.

 

PipeID

An 8-bit value that consists of a 7-bit address and a direction bit. This parameter corresponds to the bEndpointAddress field in the endpoint descriptor.

 

PolicyType

A value that specifies the pipe policy parameter to retrieve. The following table describes symbolic constants that are defined in winusbio.h.

Policy parameter	Description
ALLOW_PARTIAL_READS (0x05)	If the caller specifies a policy of ALLOW_PARTIAL_READS, WinUsb_GetPipePolicy returns the value of the allow partial reads policy parameter in Value. If the allow partial reads policy parameter is FALSE (that is, zero), the read request fails whenever the device returns more data than the client requested. If the allow partial reads policy parameter is TRUE, the WinUSB driver saves the extra data; and the next time the client does a read, the first data that the WinUSB driver sends to the client is the extra data that remained from the previous read. The default value of the allow partial reads policy parameter is TRUE. The Value parameter must point to a UCHAR variable.
AUTO_CLEAR_STALL (0x02)	If the caller specifies a policy of AUTO_CLEAR_STALL, WinUsb_GetPipePolicy returns the value of the auto clear stall policy parameter in Value. If the auto clear stall policy parameter is TRUE (that is, nonzero), the driver fails stalled data transfers, but the driver clears the stall condition automatically. The transfer that caused the stall is completed with a failure, and but data starts to flow on the pipe again automatically, as soon as a new transfer arrives (this can include a transfer that was in the queue when the stall occurred). This policy parameter does not affect control pipes. The default value for the auto clear stall policy parameter is FALSE. Value must point to a UCHAR variable.
AUTO_FLUSH (0x06)	If the caller specifies a policy of AUTO_FLUSH, WinUsb_GetPipePolicy returns the value of the auto flush policy parameter in Value. The auto flush policy parameter works with allow partial reads. If allow partial reads is FALSE, the WinUSB driver ignores the value of auto flush. If allow partial reads is TRUE, the value of auto flush determines what the WinUSB driver does when the device returns more data than the client requested. If both allow partial reads and auto flush policy parameters are TRUE (that is, nonzero) and the device returns more data than the client requested, the remaining data is discarded. If allow partial reads is TRUE, but auto flush is FALSE, the WinUSB driver caches the extra data and sends it to the client in the next read operation. The default value of the auto flush policy parameter is FALSE. Value must point to a UCHAR variable.
IGNORE_SHORT_PACKETS (0x04)	If the caller specifies a policy of IGNORE_SHORT_PACKETS, WinUsb_GetPipePolicy returns the value of the ignore short packets policy parameter in Value. If the ignore short packets policy parameter is TRUE (that is, nonzero), the host does not complete a read operation after it receives a short packet. Instead, the the host completes the operation only after the host has read the specified number of bytes. If the ignore short packets policy parameter is FALSE, the host completes a read operation when either the host has read the specified number of bytes or the host has received a short packet. The default value of the ignore short packets policy parameter is FALSE. Value must point to a UCHAR variable.
PIPE_TRANSFER_TIMEOUT (0x03)	If the caller specifies a policy of PIPE_TRANSFER_TIMEOUT, WinUsb_GetPipePolicy returns the value of the pipe transfer timeout policy parameter in Value. The pipe transfer timeout policy parameter specifies the time-out interval, in milliseconds. A value of zero means that transfers do not time out. The host cancels transfers that do not complete within the time-out interval. The host calculates the timeout interval from the moment that the USB stack receives the transfer request. However, in Windows Vista, for all transfers, except raw transfers, the winusb.sys driver queues the request until all previous transfers on the destination endpoint have completed. The host does not include the queueing time in the calculation of the timeout interval. With raw I/O, the winusb.sys driver does not queue the request. Instead, winusb.sys passes the request directly to the USB stack, whether the USB stack is busy with other transfers or not. If the USB stack is busy processing previous transfers, it can delay the processing of the new request, and this can cause a timeout. By default, the time-out value is zero, and the host never cancels a transfer because of a time-out. Value must point to a ULONG variable.
RAW_IO (0x07)	If the caller specifies a policy of RAW_IO, WinUsb_GetPipePolicy returns the value of the raw I/O policy parameter in Value. If the raw I/O policy parameter is TRUE (that is, nonzero), calls to WinUsb_ReadPipe and WinUsb_WritePipe for the specified endpoint must satisfy the following conditions: The buffer length must be a multiple of the maximum endpoint packet size. The length must be less than the maximum transfer size for the pipe. If the preceding conditions are satisfied, WinUSB sends data directly to the USB driver stack, bypassing the queuing and error handling of WinUSB. If the raw I/O policy parameter is FALSE, no restrictions are imposed on the buffers that are passed to te WinUsb_ReadPipe and WinUsb_WritePipe routines. The default value of the raw I/O policy parameter is FALSE. Value must point to a UCHAR variable.
SHORT_PACKET_TERMINATE (0x01)	If the caller specifies a policy of SHORT_PACKET_TERMINATE, WinUsb_GetPipePolicy returns the value of the short packet terminate policy parameter in Value. If the short packet terminate policy parameter is TRUE (that is, nonzero), every write request that is a multiple of the maximum packet size for the endpoint is terminated with a zero-length packet. The default value of the short packet terminate policy parameter is FALSE. The Value parameter must point to a UCHAR variable.

 

 

 

ValueLength

A pointer to the size, in bytes, of the buffer that Value points to. On output, ValueLength receives the size, in bytes, of the data that was copied into the Value buffer.

 

Value

A pointer to a buffer that receives the specified pipe policy value.

 

Return Value

WinUsb_GetPipePolicy returns TRUE if the operation succeeds. Otherwise, this routine returns FALSE, and the caller can retrieve the logged error by calling GetLastError.

WinUsb_GetInterfacePowerPolicy

The WinUsb_GetInterfacePowerPolicy routine retrieves the power policy for a device.

BOOL __stdcall
  WinUsb_GetInterfacePowerPolicy (
    IN WINUSB_INTERFACE_HANDLE  InterfaceHandle,
    IN ULONG  PolicyType,
    IN OUT PULONG  ValueLength,
    OUT PVOID  Value
  );

Parameters

InterfaceHandle

The interface handle that WinUsb_Initialize returned.

 

PolicyType

A value that specifies the power policy parameter to retrieve in Value. The following table describes symbolic constants that are defined in winusbio.h.

Policy type	Description
AUTO_SUSPEND (0x01)	If the caller specifies a power policy of AUTO_SUSPEND, WinUsb_GetInterfacePowerPolicy returns the value of the auto suspend policy parameter in Value. If the auto suspend policy parameter is TRUE (that is, nonzero), the USB stack suspends the device when no transfers are pending or the only transfers pending are IN transfers on an interrupt or bulk endpoint. The value of the DefaultIdleState registry value determines the default value of the auto suspend policy parameter. The Value parameter must point to a UCHAR variable.
SUSPEND_DELAY (0x03)	If the caller specifies a power policy of SUSPEND_DELAY, WinUsb_GetInterfacePowerPolicy returns the value of the suspend delay policy parameter in Value. The suspend delay policy parameter specifies the minimum amount of time, in milliseconds, that the WinUSB driver must wait after any transfer before it can suspend the device. Value must point to a UCHAR variable.

 

 

 

ValueLength

A pointer to the size of the buffer that Value. On output, ValueLength receives the size of the data that was copied into the Value buffer.

 

Value

A buffer that receives the specified power policy value.

 

Return Value

WinUsb_GetInterfacePowerPolicy returns TRUE if the operation succeeds. Otherwise, this routine returns FALSE, and the caller can retrieve the logged error by calling GetLastError.

WinUsb_GetDescriptor

The WinUsb_GetDescriptor routine returns a requested descriptor.

BOOL __stdcall
  WinUsb_GetDescriptor (
    IN WINUSB_INTERFACE_HANDLE  InterfaceHandle,
    IN UCHAR  DescriptorType,
    IN UCHAR  Index,
    IN USHORT  LanguageID,
    OUT PUCHAR  Buffer,
    IN ULONG  BufferLength,
    OUT PULONG  LengthTransferred
  );

Parameters

InterfaceHandle

The interface handle that WinUsb_Initialize returned.

 

DescriptorType

A value that specifies the type of descriptor to return. This parameter corresponds to the bDescriptorType field of a standard device descriptor, whose values are described in the Universal Serial Bus specification. Some of these values are listed in the description of the DescriptorType member of the _URB_CONTROL_DESCRIPTOR_REQUEST structure.

 

Index

The descriptor index. For an explanation of the descriptor index, see the Universal Serial Bus specification (www.usb.org).

 

LanguageID

A value that specifies the language identifier, if the requested descriptor is a string descriptor.

 

Buffer

A caller-allocated buffer that receives the requested descriptor.

 

BufferLength

The length, in bytes, of Buffer.

 

LengthTransferred

The number of bytes that were copied into Buffer.

 

Return Value

WinUsb_GetDescriptor returns TRUE if the operation succeeds. Otherwise, this routine returns FALSE, and the caller can retrieve the logged error by calling GetLastError.

WinUsb_GetCurrentAlternateSetting

The WinUsb_GetCurrentAlternateSetting routine gets the current alternate interface setting for an interface.

BOOL __stdcall
  WinUsb_GetCurrentAlternateSetting (
    IN WINUSB_INTERFACE_HANDLE  InterfaceHandle,
    OUT PUCHAR  AlternateSetting
  );

Parameters

InterfaceHandle

The interface handle that WinUsb_Initialize returned.

 

AlternateSetting

A pointer to an unsigned character that receives an integer that indicates the current alternate setting.

 

Return Value

WinUsb_GetCurrentAlternateSetting returns TRUE if the operation succeeds. Otherwise, this routine returns FALSE, and the caller can retrieve the logged error by calling GetLastError.

WinUsb_GetAssociatedInterface

The WinUsb_GetAssociatedInterface routine retrieves a handle for an associated interface.

BOOL __stdcall
  WinUsb_GetAssociatedInterface (
    IN WINUSB_INTERFACE_HANDLE  InterfaceHandle,
    IN UCHAR  AssociatedInterfaceIndex,
    OUT PWINUSB_INTERFACE_HANDLE  AssociatedInterfaceHandle
  )

Parameters

InterfaceHandle

The interface handle that WinUsb_Initialize returned.

 

AssociatedInterfaceIndex

An index that specifies the associated interface to retrieve. A value of 0 indicates the first associated interface, a value of 1 indicates the second associated interface, and so on.

 

AssociatedInterfaceHandle

A handle for the associated interface. Callers must pass this interface handle to to the routines that winusb.dll exposes.

 

Return Value

WinUsb_GetAssociatedInterface returns TRUE if the operation succeeds. Otherwise, this routine returns FALSE, and the caller can retrieve the logged error by calling GetLastError.

The following list describes some of the possible errors:

ERROR_NO_MORE_ITEMS

An interface does not exist for the specified AssociatedInterfaceIndex value .

ERROR_ALREADY_EXISTS

WinUsb_GetAssociatedInterface has already returned a handle for the interface that AssociatedInterfaceIndex specifies.

Comments

The WinUsb_GetAssociatedInterface routine retrieves an opaque handle.

The first associated interface is the interface that immediately follows the interface whose handle the WinUsb_Initialize routine retrieves.

The handle that WinUsb_GetAssociatedInterface returns must be released by calling WinUsb_Free.

Callers of WinUsb_GetAssociatedInterface can retrieve only one handle for each interface. If a caller attempts to retrieve more than one handle for the same interface, the routine will fail with an error of ERROR_ALREADY_EXISTS.

WinUsb_Free

The WinUsb_Free function frees all of the resources that WinUsb_Initialize allocated.

BOOL __stdcall
  WinUsb_Free (
    IN WINUSB_INTERFACE_HANDLE  InterfaceHandle
  );

Parameters

InterfaceHandle

The interface handle that WinUsb_Initialize returned.

 

Return Value

WinUsb_Free returns TRUE if the operation succeeds. Otherwise, this routine returns FALSE, and the caller can retrieve the logged error by calling GetLastError

WinUsb_FlushPipe

The WinUsb_FlushPipe routine discards any data that is cached in a pipe.

BOOL __stdcall
  WinUsb_FlushPipe (
    IN WINUSB_INTERFACE_HANDLE  InterfaceHandle,
    IN UCHAR  PipeID
  );

Parameters

InterfaceHandle

The interface handle that WinUsb_Initialize returned.

 

PipeID

The identifier (ID) of the control pipe. The PipeID parameter is an 8-bit value that consists of a 7-bit address and a direction bit. This parameter corresponds to the bEndpointAddress field in the endpoint descriptor.

 

Return Value

WinUsb_FlushPipe returns TRUE if the operation succeeds. Otherwise, this routine returns FALSE, and the caller can retrieve the logged error by calling GetLastError.

WinUsb_Initialize

The WinUsb_Initialize routine retrieves a handle for the interface that is associated with the indicated device.

BOOL __stdcall
  WinUsb_Initialize (
    IN HANDLE  DeviceHandle,
    OUT  PWINUSB_INTERFACE_HANDLE  InterfaceHandle
  );

Parameters

DeviceHandle

The handle to the device that CreateFile returned. WinUSB uses overlapped I/O, so FILE_FLAG_OVERLAPPED must be specified in the dwFlagsAndAttributes parameter of CreateFile call for DeviceHandle to have the characteristics necessary for WinUsb_Initialize to function properly.

 

InterfaceHandle

The interface handle that WinUsb_Initialize returns. All other WinUSB routines require this handle as input. The handle is opaque.

 

Return Value

WinUsb_Initialize returns TRUE if the operation succeeds. Otherwise, this routine returns FALSE, and the caller can retrieve the logged error by calling GetLastError.

Comments

The policy settings of the interface are reset to the default values when WinUsb_Initialize is called. 

WinUsb_AbortPipe

The WinUsb_AbortPipe routine aborts all of the pending transfers for a pipe.

BOOL __stdcall
  WinUsb_AbortPipe (
    IN WINUSB_INTERFACE_HANDLE  InterfaceHandle,
    IN UCHAR  PipeID
  );

Parameters

InterfaceHandle

The interface handle that WinUsb_Initialize returned.

 

PipeID

The identifier (ID) of the control pipe. The PipeID parameter is an 8-bit value that consists of a 7-bit address and a direction bit. This parameter corresponds to the bEndpointAddress field in the endpoint descriptor.

 

Return Value

WinUsb_AbortPipe returns TRUE if the operation succeeds. Otherwise, this routine returns FALSE, and the caller can retrieve the logged error by calling GetLastError.

WinUsb_ControlTransfer

The WinUsb_ControlTransfer routine transmits control data over a default control endpoint.

BOOL __stdcall
  WinUsb_ControlTransfer (
    IN WINUSB_INTERFACE_HANDLE  InterfaceHandle,
    IN WINUSB_SETUP_PACKET  SetupPacket,
    IN PUCHAR  Buffer,
    IN ULONG  BufferLength,
    OUT PULONG  LengthTransferred,
    IN LPOVERLAPPED  Overlapped
  );

Parameters

InterfaceHandle

The interface handle that WinUsb_Initialize returned.

 

SetupPacket

The 8-byte setup packet of type WINUSB_SETUP_PACKET.

 

Buffer

A caller-allocated buffer that contains the data to transfer.

 

BufferLength

The number of bytes to transfer, not including the setup packet. This number must be less than or equal to the size, in bytes, of Buffer.

 

LengthTransferred

A pointer to a ULONG variable that receives the actual number of transferred bytes.

 

Overlapped

An optional pointer to an OVERLAPPED structure, which is used for asynchronous operations. If this parameter is specified, WinUsb_ControlTransfer immediately returns, and the event is signaled when the operation is complete.

 

Return Value

WinUsb_ControlTransfer returns TRUE if the operation succeeds. Otherwise, this routine returns FALSE, and the caller can retrieve the logged error by calling GetLastError.