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
);
-
The interface handle that
WinUsb_Initialize returned.
-
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.
-
A caller-allocated buffer that contains the data to write.
-
The number of bytes to write. This number must be less than or equal to the size, in bytes, of
Buffer.
-
A pointer to a ULONG variable that receives the actual number of bytes that were written to the pipe.
-
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.
Parameters
InterfaceHandleReturn 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
);
-
The interface handle that
WinUsb_Initialize returned.
-
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.
-
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 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 .
-
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.
Parameters
InterfaceHandleReturn 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
);
-
The interface handle that
WinUsb_Initialize returned.
-
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.
-
The new value for the policy parameter that
PolicyType specifies.
Parameters
InterfaceHandleReturn 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
);
-
The interface handle that
WinUsb_Initialize returned.
-
The value that is contained in the
bAlternateSetting member of the
USB_INTERFACE_DESCRIPTOR structure. This structure is populated by the
WinUsb_QueryInterfaceSettings routine.
Parameters
InterfaceHandleReturn 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
);
-
The interface handle that
WinUsb_Initialize returned.
-
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.
Parameters
InterfaceHandleReturn 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
);
-
The interface handle that
WinUsb_Initialize returned.
-
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.
-
A caller-allocated buffer that receives the data that is read.
-
The maximum number of bytes to read. This number must be less than or equal to the size, in bytes, of
Buffer.
-
A pointer to a ULONG variable that receives the actual number of bytes that were copied into
Buffer.
-
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.
Parameters
InterfaceHandleReturn 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
);
-
The interface handle that
WinUsb_Initialize returned.
-
A value that specifies the alternate interface to return the information for.
-
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.
-
A pointer, on output, to a caller-allocated
WINUSB_PIPE_INFORMATION structure that contains pipe information.
Parameters
InterfaceHandleReturn 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
);
-
The interface handle that
WinUsb_Initialize returned.
-
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.
-
A pointer to a caller-allocated
USB_INTERFACE_DESCRIPTOR structure that contains information about the interface that
AlternateSettingNumber specified.
Parameters
InterfaceHandleReturn 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
);
-
The interface handle that
WinUsb_Initialize returned.
-
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.
-
A caller-allocated buffer that receives the requested value.
Parameters
InterfaceHandleReturn 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
);
-
The interface handle that
WinUsb_Initialize returned.
-
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.
-
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 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.
-
A pointer to a buffer that receives the specified pipe policy value.
Parameters
InterfaceHandleReturn 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
);
-
The interface handle that
WinUsb_Initialize returned.
-
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.
-
A buffer that receives the specified power policy value.
Parameters
InterfaceHandleReturn 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
);
-
The interface handle that
WinUsb_Initialize returned.
-
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.
-
The descriptor index. For an explanation of the descriptor index, see the
Universal Serial Bus specification (www.usb.org).
-
A value that specifies the language identifier, if the requested descriptor is a string descriptor.
-
A caller-allocated buffer that receives the requested descriptor.
-
The length, in bytes, of
Buffer.
-
The number of bytes that were copied into
Buffer.
Parameters
InterfaceHandleReturn 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
);
-
The interface handle that
WinUsb_Initialize returned.
-
A pointer to an unsigned character that receives an integer that indicates the current alternate setting.
Parameters
InterfaceHandleReturn 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
)
-
The interface handle that
WinUsb_Initialize returned.
-
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.
-
A handle for the associated interface. Callers must pass this interface handle to to the routines that
winusb.dll exposes.
Parameters
InterfaceHandleReturn 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
);
-
The interface handle that
WinUsb_Initialize returned.
Parameters
InterfaceHandleReturn 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
);
-
The interface handle that
WinUsb_Initialize returned.
-
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.
Parameters
InterfaceHandleReturn 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
);
-
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.
-
The interface handle that
WinUsb_Initialize returns. All other WinUSB routines require this handle as input. The handle is opaque.
Parameters
DeviceHandleReturn 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
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
);
-
The interface handle that
WinUsb_Initialize returned.
-
The 8-byte setup packet of type
WINUSB_SETUP_PACKET.
-
A caller-allocated buffer that contains the data to transfer.
-
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.
-
A pointer to a ULONG variable that receives the actual number of transferred bytes.
-
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.
Parameters
InterfaceHandleReturn 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.