libusbK 
3.0
Library Documentation
© 2011-2021 Travis Lee Robinson. All rights reserved.
Functions
USB Core

Module for core UsbK device functions. More...

Functions

KUSB_EXP BOOL KUSB_API UsbK_Init (_out KUSB_HANDLE *InterfaceHandle, _in KLST_DEVINFO_HANDLE DevInfo)
 Creates/opens a libusbK interface handle from the device list. This is a preferred method. More...
 
KUSB_EXP BOOL KUSB_API UsbK_Free (_in KUSB_HANDLE InterfaceHandle)
 Frees a libusbK interface handle. More...
 
KUSB_EXP BOOL KUSB_API UsbK_ClaimInterface (_in KUSB_HANDLE InterfaceHandle, _in UCHAR NumberOrIndex, _in BOOL IsIndex)
 Claims the specified interface by number or index. More...
 
KUSB_EXP BOOL KUSB_API UsbK_ReleaseInterface (_in KUSB_HANDLE InterfaceHandle, _in UCHAR NumberOrIndex, _in BOOL IsIndex)
 Releases the specified interface by number or index. More...
 
KUSB_EXP BOOL KUSB_API UsbK_SetAltInterface (_in KUSB_HANDLE InterfaceHandle, _in UCHAR NumberOrIndex, _in BOOL IsIndex, _in UCHAR AltSettingNumber)
 Sets the alternate setting of the specified interface. More...
 
KUSB_EXP BOOL KUSB_API UsbK_GetAltInterface (_in KUSB_HANDLE InterfaceHandle, _in UCHAR NumberOrIndex, _in BOOL IsIndex, _out PUCHAR AltSettingNumber)
 Gets the alternate setting for the specified interface. More...
 
KUSB_EXP BOOL KUSB_API UsbK_GetDescriptor (_in KUSB_HANDLE InterfaceHandle, _in UCHAR DescriptorType, _in UCHAR Index, _in USHORT LanguageID, _out PUCHAR Buffer, _in UINT BufferLength, _outopt PUINT LengthTransferred)
 Gets the requested descriptor. This is a synchronous operation. More...
 
KUSB_EXP BOOL KUSB_API UsbK_ControlTransfer (_in KUSB_HANDLE InterfaceHandle, _in WINUSB_SETUP_PACKET SetupPacket, _refopt PUCHAR Buffer, _in UINT BufferLength, _outopt PUINT LengthTransferred, _inopt LPOVERLAPPED Overlapped)
 Transmits control data over a default control endpoint. More...
 
KUSB_EXP BOOL KUSB_API UsbK_SetPowerPolicy (_in KUSB_HANDLE InterfaceHandle, _in UINT PolicyType, _in UINT ValueLength, _in PVOID Value)
 Sets the power policy for a device. More...
 
KUSB_EXP BOOL KUSB_API UsbK_GetPowerPolicy (_in KUSB_HANDLE InterfaceHandle, _in UINT PolicyType, _ref PUINT ValueLength, _out PVOID Value)
 Gets the power policy for a device. More...
 
KUSB_EXP BOOL KUSB_API UsbK_SetConfiguration (_in KUSB_HANDLE InterfaceHandle, _in UCHAR ConfigurationNumber)
 Sets the device configuration number. More...
 
KUSB_EXP BOOL KUSB_API UsbK_GetConfiguration (_in KUSB_HANDLE InterfaceHandle, _out PUCHAR ConfigurationNumber)
 Gets the device current configuration number. More...
 
KUSB_EXP BOOL KUSB_API UsbK_ResetDevice (_in KUSB_HANDLE InterfaceHandle)
 Resets the usb device of the specified interface handle. (port cycle). More...
 
KUSB_EXP BOOL KUSB_API UsbK_Initialize (_in HANDLE DeviceHandle, _out KUSB_HANDLE *InterfaceHandle)
 Creates a libusbK handle for the device specified by a file handle. More...
 
KUSB_EXP BOOL KUSB_API UsbK_SelectInterface (_in KUSB_HANDLE InterfaceHandle, _in UCHAR NumberOrIndex, _in BOOL IsIndex)
 Selects the specified interface by number or index as the current interface. More...
 
KUSB_EXP BOOL KUSB_API UsbK_GetAssociatedInterface (_in KUSB_HANDLE InterfaceHandle, _in UCHAR AssociatedInterfaceIndex, _out KUSB_HANDLE *AssociatedInterfaceHandle)
 Retrieves a handle for an associated interface. More...
 
KUSB_EXP BOOL KUSB_API UsbK_Clone (_in KUSB_HANDLE InterfaceHandle, _out KUSB_HANDLE *DstInterfaceHandle)
 Clones the specified interface handle. More...
 
KUSB_EXP BOOL KUSB_API UsbK_QueryInterfaceSettings (_in KUSB_HANDLE InterfaceHandle, _in UCHAR AltSettingIndex, _out PUSB_INTERFACE_DESCRIPTOR UsbAltInterfaceDescriptor)
 Retrieves the interface descriptor for the specified alternate interface settings for a particular interface handle. More...
 
KUSB_EXP BOOL KUSB_API UsbK_QueryDeviceInformation (_in KUSB_HANDLE InterfaceHandle, _in UINT InformationType, _ref PUINT BufferLength, _ref PUCHAR Buffer)
 Retrieves information about the physical device that is associated with a libusbK handle. More...
 
KUSB_EXP BOOL KUSB_API UsbK_SetCurrentAlternateSetting (_in KUSB_HANDLE InterfaceHandle, _in UCHAR AltSettingNumber)
 Sets the alternate setting of an interface. More...
 
KUSB_EXP BOOL KUSB_API UsbK_GetCurrentAlternateSetting (_in KUSB_HANDLE InterfaceHandle, _out PUCHAR AltSettingNumber)
 Gets the current alternate interface setting for an interface. More...
 
KUSB_EXP BOOL KUSB_API UsbK_QueryPipe (_in KUSB_HANDLE InterfaceHandle, _in UCHAR AltSettingNumber, _in UCHAR PipeIndex, _out PWINUSB_PIPE_INFORMATION PipeInformation)
 Retrieves information about a pipe that is associated with an interface. More...
 
KUSB_EXP BOOL KUSB_API UsbK_QueryPipeEx (_in KUSB_HANDLE InterfaceHandle, _in UCHAR AltSettingNumber, _in UCHAR PipeIndex, _out PWINUSB_PIPE_INFORMATION_EX PipeInformationEx)
 Retrieves information about a pipe that is associated with an interface. More...
 
KUSB_EXP BOOL KUSB_API UsbK_GetSuperSpeedPipeCompanionDescriptor (_in KUSB_HANDLE InterfaceHandle, _in UCHAR AltSettingNumber, _in UCHAR PipeIndex, _out PUSB_SUPERSPEED_ENDPOINT_COMPANION_DESCRIPTOR PipeCompanionDescriptor)
 Retrieves a pipes super speed endpoint companion descriptor associated with an interface. More...
 
KUSB_EXP BOOL KUSB_API UsbK_SetPipePolicy (_in KUSB_HANDLE InterfaceHandle, _in UCHAR PipeID, _in UINT PolicyType, _in UINT ValueLength, _in PVOID Value)
 Sets the policy for a specific pipe associated with an endpoint on the device. This is a synchronous operation. More...
 
KUSB_EXP BOOL KUSB_API UsbK_GetPipePolicy (_in KUSB_HANDLE InterfaceHandle, _in UCHAR PipeID, _in UINT PolicyType, _ref PUINT ValueLength, _out PVOID Value)
 Gets the policy for a specific pipe (endpoint). More...
 
KUSB_EXP BOOL KUSB_API UsbK_ReadPipe (_in KUSB_HANDLE InterfaceHandle, _in UCHAR PipeID, _out PUCHAR Buffer, _in UINT BufferLength, _outopt PUINT LengthTransferred, _inopt LPOVERLAPPED Overlapped)
 Reads data from the specified pipe. More...
 
KUSB_EXP BOOL KUSB_API UsbK_WritePipe (_in KUSB_HANDLE InterfaceHandle, _in UCHAR PipeID, _in PUCHAR Buffer, _in UINT BufferLength, _outopt PUINT LengthTransferred, _inopt LPOVERLAPPED Overlapped)
 Writes data to a pipe. More...
 
KUSB_EXP BOOL KUSB_API UsbK_ResetPipe (_in KUSB_HANDLE InterfaceHandle, _in UCHAR PipeID)
 Resets the data toggle and clears the stall condition on a pipe. More...
 
KUSB_EXP BOOL KUSB_API UsbK_AbortPipe (_in KUSB_HANDLE InterfaceHandle, _in UCHAR PipeID)
 Aborts all of the pending transfers for a pipe. More...
 
KUSB_EXP BOOL KUSB_API UsbK_FlushPipe (_in KUSB_HANDLE InterfaceHandle, _in UCHAR PipeID)
 Discards any data that is cached in a pipe. More...
 
KUSB_EXP BOOL KUSB_API UsbK_IsoReadPipe (_in KUSB_HANDLE InterfaceHandle, _in UCHAR PipeID, _out PUCHAR Buffer, _in UINT BufferLength, _in LPOVERLAPPED Overlapped, _refopt PKISO_CONTEXT IsoContext)
 Reads from an isochronous pipe. More...
 
KUSB_EXP BOOL KUSB_API UsbK_IsoWritePipe (_in KUSB_HANDLE InterfaceHandle, _in UCHAR PipeID, _in PUCHAR Buffer, _in UINT BufferLength, _in LPOVERLAPPED Overlapped, _refopt PKISO_CONTEXT IsoContext)
 Writes to an isochronous pipe. More...
 
KUSB_EXP BOOL KUSB_API UsbK_GetCurrentFrameNumber (_in KUSB_HANDLE InterfaceHandle, _out PUINT FrameNumber)
 Retrieves the current USB frame number. More...
 
KUSB_EXP BOOL KUSB_API UsbK_IsochReadPipe (_in KISOCH_HANDLE IsochHandle, _inopt UINT DataLength, _refopt PUINT FrameNumber, _inopt UINT NumberOfPackets, _in LPOVERLAPPED Overlapped)
 Reads from an isochronous pipe. Supports LibusbK or WinUsb. More...
 
KUSB_EXP BOOL KUSB_API UsbK_IsochWritePipe (_in KISOCH_HANDLE IsochHandle, _inopt UINT DataLength, _ref PUINT FrameNumber, _inopt UINT NumberOfPackets, _in LPOVERLAPPED Overlapped)
 Writes to an isochronous pipe. Supports LibusbK or WinUsb. More...
 
KUSB_EXP BOOL KUSB_API UsbK_GetOverlappedResult (_in KUSB_HANDLE InterfaceHandle, _in LPOVERLAPPED Overlapped, _out PUINT lpNumberOfBytesTransferred, _in BOOL bWait)
 Retrieves the results of an overlapped operation on the specified libusbK handle. More...
 
KUSB_EXP BOOL KUSB_API UsbK_GetProperty (_in KUSB_HANDLE InterfaceHandle, _in KUSB_PROPERTY PropertyType, _ref PUINT PropertySize, _out PVOID Value)
 Gets a USB device (driver specific) property from usb handle. More...
 

Detailed Description

Module for core UsbK device functions.

Function Documentation

KUSB_EXP BOOL KUSB_API UsbK_Init ( _out KUSB_HANDLE *  InterfaceHandle,
_in KLST_DEVINFO_HANDLE  DevInfo 
)

Creates/opens a libusbK interface handle from the device list. This is a preferred method.

Parameters
[out]InterfaceHandleReceives a handle configured to the first (default) interface on the device. This handle is required by other libusbK routines that perform operations on the default interface. The handle is opaque. To release this handle, call the UsbK_Free function.
[in]DevInfoThe device list element to open.
Returns
On success, TRUE. Otherwise FALSE. Use GetLastError() to get extended error information.

UsbK_Init performs the same tasks as UsbK_Initialize with the following exceptions:

  • Uses a KLST_DEVINFO instead of a file handle created with the Windows CreateFile() API function.
  • File handles are managed internally and are closed when the last KUSB_HANDLE is closed with UsbK_Free. To obtain the internal file device handle, See UsbK_GetProperty.
Note
A KUSB_HANDLE is required by other library routines that perform operations on a device. Once initialized, it can access all interfaces/endpoints of a device. An initialized handle can be cloned with UsbK_Clone or UsbK_GetAssociatedInterface. A Cloned handle will behave just as the orignal except in will maintain it's own selected interface setting.
KUSB_EXP BOOL KUSB_API UsbK_Free ( _in KUSB_HANDLE  InterfaceHandle)

Frees a libusbK interface handle.

Parameters
[in]InterfaceHandleHandle to an interface on the device. This handle must be created by a previous call to UsbK_Init, UsbK_Initialize, UsbK_GetAssociatedInterface, or UsbK_Clone.
Returns
TRUE.

The UsbK_Free function releases resources alocated to the InterfaceHandle.

Examples:
load-driver-api.c, and xfer-stream.c.
KUSB_EXP BOOL KUSB_API UsbK_ClaimInterface ( _in KUSB_HANDLE  InterfaceHandle,
_in UCHAR  NumberOrIndex,
_in BOOL  IsIndex 
)

Claims the specified interface by number or index.

Parameters
[in]InterfaceHandleAn initialized usb handle, see UsbK_Init.
[in]NumberOrIndexInterfaces can be claimed or released by a interface index or bInterfaceNumber.
  • Interface indexes always start from 0 and continue sequentially for all interfaces of the device.
  • An interface number always represents the actual USB_INTERFACE_DESCRIPTOR::bInterfaceNumber. Interface numbers are not guaranteed to be zero based or sequential.
[in]IsIndexIf TRUE, NumberOrIndex represents an interface index.
if FALSE NumberOrIndex represents a bInterfaceNumber.
Returns
On success, TRUE. Otherwise FALSE. Use GetLastError() to get extended error information.

Claiming an interface allows applications a way to prevent other applications or multiple instances of the same application from using an interface at the same time.

When an interface is claimed with UsbK_ClaimInterface it performs the following actions:

  • Checks if the interface exists. If it does not, returns FALSE and sets last error to ERROR_NO_MORE_ITEMS.
  • The default (or current) interface for the device is changed to NumberOrIndex.
  • libusb0.sys and libusbK.sys:
    • A request to claim the interface is sent to the driver. If the interface is not claimed or already claimed by the application the request succeeds. If the interface is claimed by another application, UsbK_ClaimInterface returns FALSE and sets last error to ERROR_BUSY. In this case the The default (or current) interface for the device is still changed to NumberOrIndex.
  • WinUSB.sys: All WinUSB device interfaces are claimed when the device is opened. This function performs identically to UsbK_SelectInterface
KUSB_EXP BOOL KUSB_API UsbK_ReleaseInterface ( _in KUSB_HANDLE  InterfaceHandle,
_in UCHAR  NumberOrIndex,
_in BOOL  IsIndex 
)

Releases the specified interface by number or index.

Parameters
[in]InterfaceHandleAn initialized usb handle, see UsbK_Init.
[in]NumberOrIndexInterfaces can be claimed or released by a interface index or bInterfaceNumber.
  • Interface indexes always start from 0 and continue sequentially for all interfaces of the device.
  • An interface number always represents the actual USB_INTERFACE_DESCRIPTOR::bInterfaceNumber. Interface numbers are not guaranteed to be zero based or sequential.
[in]IsIndexIf TRUE, NumberOrIndex represents an interface index.
if FALSE NumberOrIndex represents a bInterfaceNumber.
Returns
On success, TRUE. Otherwise FALSE. Use GetLastError() to get extended error information.

When an interface is release with UsbK_ReleaseInterface it performs the following actions:

  • Checks if the interface exists. If it does not, returns FALSE and sets last error to ERROR_NO_MORE_ITEMS.
  • The default (or current) interface for the device is changed to the previously claimed interface.
  • libusb0.sys and libusbK.sys:
    • A request to release the interface is sent to the driver. If the interface is not claimed by a different application the request succeeds. If the interface is claimed by another application, UsbK_ReleaseInterface returns FALSE and sets last error to ERROR_BUSY. In this case, the default/current interface for the device is still changed to the previously claimed interface.
  • WinUSB.sys: No other action needed, returns TRUE.
Note
When an interface is released, it is moved to the bottom if an interface stack making a previously claimed interface the current. This will continue to occur regardless of whether the interface is claimed. For this reason, UsbK_ReleaseInterface can be used as a means to change the current/default interface of an InterfaceHandle without claiming the interface.
KUSB_EXP BOOL KUSB_API UsbK_SetAltInterface ( _in KUSB_HANDLE  InterfaceHandle,
_in UCHAR  NumberOrIndex,
_in BOOL  IsIndex,
_in UCHAR  AltSettingNumber 
)

Sets the alternate setting of the specified interface.

Parameters
[in]InterfaceHandleAn initialized usb handle, see UsbK_Init.
[in]NumberOrIndexInterfaces can be specified by a interface index or bInterfaceNumber.
  • Interface indexes always start from 0 and continue sequentially for all interfaces of the device.
  • An interface number always represents the actual USB_INTERFACE_DESCRIPTOR::bInterfaceNumber. Interface numbers are not guaranteed to be zero based or sequential.
[in]IsIndexIf TRUE, NumberOrIndex represents an interface index.
if FALSE NumberOrIndex represents a bInterfaceNumber.
[in]AltSettingNumberThe bAlternateSetting to activate.
Returns
On success, TRUE. Otherwise FALSE. Use GetLastError() to get extended error information.

UsbK_SetAltInterface performs the same task as UsbK_SetCurrentAlternateSetting except it provides the option of specifying which interfaces alternate setting to activate.

KUSB_EXP BOOL KUSB_API UsbK_GetAltInterface ( _in KUSB_HANDLE  InterfaceHandle,
_in UCHAR  NumberOrIndex,
_in BOOL  IsIndex,
_out PUCHAR  AltSettingNumber 
)

Gets the alternate setting for the specified interface.

Parameters
[in]InterfaceHandleAn initialized usb handle, see UsbK_Init.
[in]NumberOrIndexInterfaces can be specified by a interface index or bInterfaceNumber.
  • Interface indexes always start from 0 and continue sequentially for all interfaces of the device.
  • An interface number always represents the actual USB_INTERFACE_DESCRIPTOR::bInterfaceNumber. Interface numbers are not guaranteed to be zero based or sequential.
[in]IsIndexIf TRUE, NumberOrIndex represents an interface index.
if FALSE NumberOrIndex represents a bInterfaceNumber.
[out]AltSettingNumberOn success, returns the active bAlternateSetting.
Returns
On success, TRUE. Otherwise FALSE. Use GetLastError() to get extended error information.

UsbK_GetAltInterface performs the same task as UsbK_GetCurrentAlternateSetting except it provides the option of specifying which interfaces alternate setting is to be retrieved.

KUSB_EXP BOOL KUSB_API UsbK_GetDescriptor ( _in KUSB_HANDLE  InterfaceHandle,
_in UCHAR  DescriptorType,
_in UCHAR  Index,
_in USHORT  LanguageID,
_out PUCHAR  Buffer,
_in UINT  BufferLength,
_outopt PUINT  LengthTransferred 
)

Gets the requested descriptor. This is a synchronous operation.

Parameters
[in]InterfaceHandleAn initialized usb handle, see UsbK_Init.
[in]DescriptorTypeA 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.
[in]IndexThe descriptor index. For an explanation of the descriptor index, see the Universal Serial Bus specification (www.usb.org).
[in]LanguageIDA value that specifies the language identifier, if the requested descriptor is a string descriptor.
[out]BufferA caller-allocated buffer that receives the requested descriptor.
[in]BufferLengthThe length, in bytes, of Buffer.
[out]LengthTransferredThe number of bytes that were copied into Buffer.
Returns
On success, TRUE. Otherwise FALSE. Use GetLastError() to get extended error information.

If the device descriptor or active config descriptor is requested, UsbK_GetDescriptor retrieves cached data and this becomes a non-blocking, non I/O request.

KUSB_EXP BOOL KUSB_API UsbK_ControlTransfer ( _in KUSB_HANDLE  InterfaceHandle,
_in WINUSB_SETUP_PACKET  SetupPacket,
_refopt PUCHAR  Buffer,
_in UINT  BufferLength,
_outopt PUINT  LengthTransferred,
_inopt LPOVERLAPPED  Overlapped 
)

Transmits control data over a default control endpoint.

Parameters
[in]InterfaceHandleA valid libusbK interface handle returned by:
[in]SetupPacketThe 8-byte setup packet of type WINUSB_SETUP_PACKET.
[in,out]BufferA caller-allocated buffer that contains the data to transfer.
[in]BufferLengthThe 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.
[out]LengthTransferredA pointer to a UINT variable that receives the actual number of transferred bytes. If the application does not expect any data to be transferred during the data phase (BufferLength is zero), LengthTransferred can be NULL.
[in]OverlappedAn optional pointer to an OVERLAPPED structure, which is used for asynchronous operations. If this parameter is specified, UsbK_ControlTransfer immediately returns, and the event is signaled when the operation is complete. If Overlapped is not supplied, the UsbK_ControlTransfer function transfers data synchronously.
Returns
On success, TRUE. Otherwise FALSE. Use GetLastError() to get extended error information. If an Overlapped member is supplied and the operation succeeds this function returns FALSE and sets last error to ERROR_IO_PENDING.

A UsbK_ControlTransfer is never cached. These requests always go directly to the usb device.

Attention
This function should not be used for operations supported by the library.
e.g. UsbK_SetConfiguration, UsbK_SetAltInterface, etc..
KUSB_EXP BOOL KUSB_API UsbK_SetPowerPolicy ( _in KUSB_HANDLE  InterfaceHandle,
_in UINT  PolicyType,
_in UINT  ValueLength,
_in PVOID  Value 
)

Sets the power policy for a device.

Parameters
[in]InterfaceHandleAn initialized usb handle, see UsbK_Init.
[in]PolicyTypeA value that specifies the power policy to set. The following table describes symbolic constants that are defined in lusbk_shared.h.
  • AUTO_SUSPEND (0x81)
    • Specifies the auto-suspend policy type; the power policy parameter must be specified by the caller in the Value parameter.
    • For auto-suspend, the Value parameter must point to a UCHAR variable.
    • If Value is TRUE (nonzero), the USB stack suspends the device if the device is idle. A device is idle if there are no transfers pending, or if the only pending transfers are IN transfers to interrupt or bulk endpoints.
    • The default value is determined by the value set in the DefaultIdleState registry setting. By default, this value is TRUE.
  • SUSPEND_DELAY (0x83)
    • Specifies the suspend-delay policy type; the power policy parameter must be specified by the caller in the Value parameter.
    • For suspend-delay, Value must point to a UINT variable.
    • Value specifies the minimum amount of time, in milliseconds, that the driver must wait post transfer before it can suspend the device.
    • The default value is determined by the value set in the DefaultIdleTimeout registry setting. By default, this value is five seconds.
Parameters
[in]ValueLengthThe size, in bytes, of the buffer at Value.
[in]ValueThe new value for the power policy parameter. Data type and value for Value depends on the type of power policy passed in PolicyType. For more information, see PolicyType.
Returns
On success, TRUE. Otherwise FALSE. Use GetLastError() to get extended error information.

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 UsbK_SetPowerPolicy.
KUSB_EXP BOOL KUSB_API UsbK_GetPowerPolicy ( _in KUSB_HANDLE  InterfaceHandle,
_in UINT  PolicyType,
_ref PUINT  ValueLength,
_out PVOID  Value 
)

Gets the power policy for a device.

Parameters
[in]InterfaceHandleAn initialized usb handle, see UsbK_Init.
[in]PolicyTypeA value that specifies the power policy parameter to retrieve in Value. The following table describes symbolic constants that are defined in lusbk_shared.h.
  • AUTO_SUSPEND (0x81)
    • If the caller specifies a power policy of AUTO_SUSPEND, UsbK_GetPowerPolicy returns the value of the auto suspend policy parameter in the Value parameter.
    • If Value 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 (0x83)
    • If the caller specifies a power policy of SUSPEND_DELAY, UsbK_GetPowerPolicy 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 driver must wait after any transfer before it can suspend the device.
    • Value must point to a UINT variable.
Parameters
[in,out]ValueLengthA 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.
[out]ValueA buffer that receives the specified power policy parameter. For more information, see PolicyType.
Returns
On success, TRUE. Otherwise FALSE. Use GetLastError() to get extended error information.
KUSB_EXP BOOL KUSB_API UsbK_SetConfiguration ( _in KUSB_HANDLE  InterfaceHandle,
_in UCHAR  ConfigurationNumber 
)

Sets the device configuration number.

Parameters
[in]InterfaceHandleAn initialized usb handle, see UsbK_Init.
[in]ConfigurationNumberThe configuration number to activate.
Returns
On success, TRUE. Otherwise FALSE. Use GetLastError() to get extended error information.

UsbK_SetConfiguration is only supported with libusb0.sys. If the driver in not libusb0.sys, this function performs the following emulation actions:

  • If the requested configuration number is the current configuration number, returns TRUE.
  • If the requested configuration number is one other than the current configuration number, returns FALSE and set last error to ERROR_NO_MORE_ITEMS.

This function will fail if there are pending I/O operations or there are other libusbK interface handles referencing the device.

See Also
UsbK_Free
KUSB_EXP BOOL KUSB_API UsbK_GetConfiguration ( _in KUSB_HANDLE  InterfaceHandle,
_out PUCHAR  ConfigurationNumber 
)

Gets the device current configuration number.

Parameters
[in]InterfaceHandleAn initialized usb handle, see UsbK_Init.
[out]ConfigurationNumberOn success, receives the active configuration number.
Returns
On success, TRUE. Otherwise FALSE. Use GetLastError() to get extended error information.
KUSB_EXP BOOL KUSB_API UsbK_ResetDevice ( _in KUSB_HANDLE  InterfaceHandle)

Resets the usb device of the specified interface handle. (port cycle).

Parameters
[in]InterfaceHandleAn initialized usb handle, see UsbK_Init.
Returns
On success, TRUE. Otherwise FALSE. Use GetLastError() to get extended error information.
KUSB_EXP BOOL KUSB_API UsbK_Initialize ( _in HANDLE  DeviceHandle,
_out KUSB_HANDLE *  InterfaceHandle 
)

Creates a libusbK handle for the device specified by a file handle.

Attention
This function is supported for WinUSB API compatibility only and is not intended for new development. libusbK library users should use UsbK_Init instead. (regardless of the driver they've selected)
Parameters
[in]DeviceHandleThe handle to the device that CreateFile returned. libusbK 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 this to function properly.
[out]InterfaceHandleReceives a handle configured to the first (default) interface on the device. This handle is required by other libusbK routines that perform operations on the default interface. The handle is opaque. To release this handle, call the UsbK_Free function.
Returns
On success, TRUE. Otherwise FALSE. Use GetLastError() to get extended error information.

When UsbK_Initialize is called, the policy settings of the interface are reset to the default values.

The UsbK_Initialize call queries the underlying USB stack for various descriptors and allocates enough memory to store the retrieved descriptor data.

UsbK_Initialize first retrieves the device descriptor and then gets the associated configuration descriptor. From the configuration descriptor, the call derives the associated interface descriptors and stores them in an array. The interfaces in the array are identified by zero-based indexes. An index value of 0 indicates the first interface (the default interface), a value of 1 indicates the second associated interface, and so on. UsbK_Initialize parses the default interface descriptor for the endpoint descriptors and caches information such as the associated pipes or state specific data. The handle received in the InterfaceHandle parameter will have its default interface configured to the first interface in the array.

If an application wants to use another interface on the device, it can call UsbK_GetAssociatedInterface, or UsbK_ClaimInterface.

KUSB_EXP BOOL KUSB_API UsbK_SelectInterface ( _in KUSB_HANDLE  InterfaceHandle,
_in UCHAR  NumberOrIndex,
_in BOOL  IsIndex 
)

Selects the specified interface by number or index as the current interface.

Parameters
[in]InterfaceHandleAn initialized usb handle, see UsbK_Init.
[in]NumberOrIndexInterfaces can be claimed or released by a interface index or bInterfaceNumber.
  • Interface indexes always start from 0 and continue sequentially for all interfaces of the device.
  • An interface number always represents the actual USB_INTERFACE_DESCRIPTOR::bInterfaceNumber. Interface numbers are not guaranteed to be zero based or sequential.
[in]IsIndexIf TRUE, NumberOrIndex represents an interface index.
if FALSE NumberOrIndex represents a bInterfaceNumber.
Returns
On success, TRUE. Otherwise FALSE. Use GetLastError() to get extended error information.
See Also
UsbK_ClaimInterface
KUSB_EXP BOOL KUSB_API UsbK_GetAssociatedInterface ( _in KUSB_HANDLE  InterfaceHandle,
_in UCHAR  AssociatedInterfaceIndex,
_out KUSB_HANDLE *  AssociatedInterfaceHandle 
)

Retrieves a handle for an associated interface.

Parameters
[in]InterfaceHandleAn initialized usb handle, see UsbK_Init.
[in]AssociatedInterfaceIndexAn 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.
[out]AssociatedInterfaceHandleA handle for the associated interface. Callers must pass this interface handle to libusbK Functions exposed by libusbK.dll. To close this handle, call UsbK_Free.
Returns
On success, TRUE. Otherwise FALSE. Use GetLastError() to get extended error information.

The UsbK_GetAssociatedInterface function retrieves an opaque handle for an associated interface. This is a synchronous operation.

The first associated interface is the interface that immediately follows the current (or default) interface of the specified /c InterfaceHandle.

The handle that UsbK_GetAssociatedInterface returns must be released by calling UsbK_Free.

KUSB_EXP BOOL KUSB_API UsbK_Clone ( _in KUSB_HANDLE  InterfaceHandle,
_out KUSB_HANDLE *  DstInterfaceHandle 
)

Clones the specified interface handle.

Each cloned interface handle maintains it's own selected interface.

Parameters
[in]InterfaceHandleAn initialized usb handle, see UsbK_Init.
[out]DstInterfaceHandleOn success, the cloned return handle.
Returns
On success, TRUE. Otherwise FALSE. Use GetLastError() to get extended error information.
KUSB_EXP BOOL KUSB_API UsbK_QueryInterfaceSettings ( _in KUSB_HANDLE  InterfaceHandle,
_in UCHAR  AltSettingIndex,
_out PUSB_INTERFACE_DESCRIPTOR  UsbAltInterfaceDescriptor 
)

Retrieves the interface descriptor for the specified alternate interface settings for a particular interface handle.

Parameters
[in]InterfaceHandleAn initialized usb handle, see UsbK_Init.
[in]AltSettingIndexA value that indicates which alternate setting index to return. A value of 0 indicates the first alternate setting, a value of 1 indicates the second alternate setting, and so on.
[out]UsbAltInterfaceDescriptorA pointer to a caller-allocated USB_INTERFACE_DESCRIPTOR structure that contains information about the interface that AltSettingNumber specified.

The UsbK_QueryInterfaceSettings call searches the current/default interface array for the alternate interface specified by the caller in the AltSettingIndex. If the specified alternate interface is found, the function populates the caller-allocated USB_INTERFACE_DESCRIPTOR structure. If the specified alternate interface is not found, then the call fails with the ERROR_NO_MORE_ITEMS code.

To change the current/default interface, see UsbK_SelectInterface and UsbK_ClaimInterface

Returns
On success, TRUE. Otherwise FALSE. Use GetLastError() to get extended error information.
KUSB_EXP BOOL KUSB_API UsbK_QueryDeviceInformation ( _in KUSB_HANDLE  InterfaceHandle,
_in UINT  InformationType,
_ref PUINT  BufferLength,
_ref PUCHAR  Buffer 
)

Retrieves information about the physical device that is associated with a libusbK handle.

Parameters
[in]InterfaceHandleAn initialized usb handle, see UsbK_Init.
[in]InformationTypeA value that specifies which interface information value to retrieve. On input, InformationType must have the following value: DEVICE_SPEED (0x01).
[in,out]BufferLengthThe 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.
[in,out]BufferA caller-allocated buffer that receives the requested value. On output, Buffer indicates the device speed:
  • (0x01) low/full speed device.
  • (0x03) high speed device.
Returns
On success, TRUE. Otherwise FALSE. Use GetLastError() to get extended error information.
KUSB_EXP BOOL KUSB_API UsbK_SetCurrentAlternateSetting ( _in KUSB_HANDLE  InterfaceHandle,
_in UCHAR  AltSettingNumber 
)

Sets the alternate setting of an interface.

Parameters
[in]InterfaceHandleAn initialized usb handle, see UsbK_Init.
[in]AltSettingNumberThe value that is contained in the bAlternateSetting member of the USB_INTERFACE_DESCRIPTOR structure. This structure can be populated by the UsbK_QueryInterfaceSettings routine.
Returns
On success, TRUE. Otherwise FALSE. Use GetLastError() to get extended error information.

Sets the active bAlternateSetting for the current/default interface.

To change the default/current interface see UsbK_ClaimInterface and UsbK_ReleaseInterface

See Also
UsbK_SetAltInterface
KUSB_EXP BOOL KUSB_API UsbK_GetCurrentAlternateSetting ( _in KUSB_HANDLE  InterfaceHandle,
_out PUCHAR  AltSettingNumber 
)

Gets the current alternate interface setting for an interface.

Parameters
[in]InterfaceHandleAn initialized usb handle, see UsbK_Init.
[out]AltSettingNumberA pointer to an unsigned character that receives an integer that indicates the current alternate setting.
Returns
On success, TRUE. Otherwise FALSE. Use GetLastError() to get extended error information.

Gets the active bAlternateSetting for the current/default interface.

To change the default/current interface see UsbK_ClaimInterface and UsbK_ReleaseInterface

See Also
UsbK_GetAltInterface
KUSB_EXP BOOL KUSB_API UsbK_QueryPipe ( _in KUSB_HANDLE  InterfaceHandle,
_in UCHAR  AltSettingNumber,
_in UCHAR  PipeIndex,
_out PWINUSB_PIPE_INFORMATION  PipeInformation 
)

Retrieves information about a pipe that is associated with an interface.

Parameters
[in]InterfaceHandleAn initialized usb handle, see UsbK_Init.
[in]AltSettingNumberA value that specifies the alternate interface to return the information for.
[in]PipeIndexA 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.
[out]PipeInformationA pointer, on output, to a caller-allocated WINUSB_PIPE_INFORMATION structure that contains pipe information.
Returns
On success, TRUE. Otherwise FALSE. Use GetLastError() to get extended error information.

The UsbK_QueryPipe function does not retrieve information about the control pipe.

Each interface on the USB device can have multiple endpoints. To communicate with each of these endpoints, the bus driver creates pipes for each endpoint on the interface. The pipe indices are zero-based. Therefore for n number of endpoints, the pipes' indices are set from n-1. UsbK_QueryPipe parses the configuration descriptor to get the interface specified by the caller. It searches the interface descriptor for the endpoint descriptor associated with the caller-specified pipe. If the endpoint is found, the function populates the caller-allocated WINUSB_PIPE_INFORMATION structure with information from the endpoint descriptor.

KUSB_EXP BOOL KUSB_API UsbK_QueryPipeEx ( _in KUSB_HANDLE  InterfaceHandle,
_in UCHAR  AltSettingNumber,
_in UCHAR  PipeIndex,
_out PWINUSB_PIPE_INFORMATION_EX  PipeInformationEx 
)

Retrieves information about a pipe that is associated with an interface.

Parameters
[in]InterfaceHandleAn initialized usb handle, see UsbK_Init.
[in]AltSettingNumberA value that specifies the alternate interface to return the information for.
[in]PipeIndexA 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.
[out]PipeInformationExA pointer, on output, to a caller-allocated WINUSB_PIPE_INFORMATION_EX structure that contains pipe information.
Returns
On success, TRUE. Otherwise FALSE. Use GetLastError() to get extended error information.

The UsbK_QueryPipeEx function does not retrieve information about the control pipe.

Each interface on the USB device can have multiple endpoints. To communicate with each of these endpoints, the bus driver creates pipes for each endpoint on the interface. The pipe indices are zero-based. Therefore for n number of endpoints, the pipes' indices are set from n-1. UsbK_QueryPipeEx parses the configuration descriptor to get the interface specified by the caller. It searches the interface descriptor for the endpoint descriptor associated with the caller-specified pipe. If the endpoint is found, the function populates the caller-allocated WINUSB_PIPE_INFORMATION_EX structure with information from the endpoint descriptor.

KUSB_EXP BOOL KUSB_API UsbK_GetSuperSpeedPipeCompanionDescriptor ( _in KUSB_HANDLE  InterfaceHandle,
_in UCHAR  AltSettingNumber,
_in UCHAR  PipeIndex,
_out PUSB_SUPERSPEED_ENDPOINT_COMPANION_DESCRIPTOR  PipeCompanionDescriptor 
)

Retrieves a pipes super speed endpoint companion descriptor associated with an interface.

Parameters
[in]InterfaceHandleAn initialized usb handle, see UsbK_Init.
[in]AltSettingNumberA value that specifies the alternate interface to return the information for.
[in]PipeIndexA 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.
[out]PipeCompanionDescriptorA pointer, on output, to a caller-allocated USB_SUPERSPEED_ENDPOINT_COMPANION_DESCRIPTOR structure that contains pipe super speed companion descriptor.
Returns
On success, TRUE. Otherwise FALSE. Use GetLastError() to get extended error information.

The UsbK_GetSuperSpeedPipeCompanionDescriptor function does not retrieve information about the control pipe.

KUSB_EXP BOOL KUSB_API UsbK_SetPipePolicy ( _in KUSB_HANDLE  InterfaceHandle,
_in UCHAR  PipeID,
_in UINT  PolicyType,
_in UINT  ValueLength,
_in PVOID  Value 
)

Sets the policy for a specific pipe associated with an endpoint on the device. This is a synchronous operation.

Parameters
[in]InterfaceHandleAn initialized usb handle, see UsbK_Init.
[in]PipeIDAn 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.
[in]PolicyTypeA UINT variable that specifies the policy parameter to change. The Value parameter contains the new value for the policy parameter. See the remarks section for information about each of the pipe policies and the resulting behavior.
[in]ValueLengthThe size, in bytes, of the buffer at Value.
[in]ValueThe 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.
Returns
On success, TRUE. Otherwise FALSE. Use GetLastError() to get extended error information.

The following list describes symbolic constants that are defined in lusbk_shared.h

  • SHORT_PACKET_TERMINATE (0x01)
    • The default value is FALSE.
    • To enable SHORT_PACKET_TERMINATE, in Value pass the address of a caller-allocated UCHAR variable set to TRUE (nonzero).
    • Enabling SHORT_PACKET_TERMINATE causes the driver to send a zero-length packet at the end of every write request to the host controller.
  • AUTO_CLEAR_STALL (0x02)
    • The default value is FALSE. To enable AUTO_CLEAR_STALL, in Value pass the address of a caller-allocated UCHAR variable set to TRUE (nonzero).
    • Enabling AUTO_CLEAR_STALL causes libusbK to reset the pipe in order to automatically clear the stall condition. Data continues to flow on the bulk and interrupt IN endpoints again as soon as a new or a queued transfer arrives on the endpoint. This policy parameter does not affect control pipes.
    • Disabling AUTO_CLEAR_STALL causes all transfers (that arrive to the endpoint after the stalled transfer) to fail until the caller manually resets the endpoint's pipe by calling UsbK_ResetPipe.
  • PIPE_TRANSFER_TIMEOUT (0x03)
    • The default value is zero. To set a time-out value, in Value pass the address of a caller-allocated UINT variable that contains the time-out interval.
    • The PIPE_TRANSFER_TIMEOUT value specifies the time-out interval, in milliseconds. The host controller cancels transfers that do not complete within the specified time-out interval.
    • A value of zero (default) indicates that transfers do not time out because the host controller never cancels the transfer.
  • IGNORE_SHORT_PACKETS (0x04)
    • The default value is FALSE. To enable IGNORE_SHORT_PACKETS, in Value pass the address of a caller-allocated UCHAR variable set to TRUE (nonzero).
    • Enabling IGNORE_SHORT_PACKETS causes the host controller to not complete a read operation after it receives a short packet. Instead, the host controller completes the operation only after the host has read the specified number of bytes.
    • Disabling IGNORE_SHORT_PACKETS causes the host controller to complete a read operation when either the host has read the specified number of bytes or the host has received a short packet.
  • ALLOW_PARTIAL_READS (0x05)
    • The default value is TRUE (nonzero). To disable ALLOW_PARTIAL_READS, in Value pass the address of a caller-allocated UCHAR variable set to FALSE (zero).
    • Disabling ALLOW_PARTIAL_READS causes the read requests to fail whenever the device returns more data (on bulk and interrupt IN endpoints) than the caller requested.
    • Enabling ALLOW_PARTIAL_READS causes libusbK to save or discard the extra data when the device returns more data (on bulk and interrupt IN endpoints) than the caller requested. This behavior is defined by setting the AUTO_FLUSH value.
  • AUTO_FLUSH (0x06)
    • The default value is FALSE (zero). To enable AUTO_FLUSH, in Value pass the address of a caller-allocated UCHAR variable set to TRUE (nonzero).
    • AUTO_FLUSH must be used with ALLOW_PARTIAL_READS enabled. If ALLOW_PARTIAL_READS is TRUE, the value of AUTO_FLUSH determines the action taken by libusbK when the device returns more data than the caller requested.
    • Disabling ALLOW_PARTIAL_READS causes libusbK to ignore the AUTO_FLUSH value.
    • Disabling AUTO_FLUSH with ALLOW_PARTIAL_READS enabled causes libusbK to save the extra data, add the data to the beginning of the caller's next read request, and send it to the caller in the next read operation.
    • Enabling AUTO_FLUSH with ALLOW_PARTIAL_READS enabled causes libusbK to discard the extra data remaining from the read request.
  • RAW_IO (0x07)
    • The default value is FALSE (zero). To enable RAW_IO, in Value pass the address of a caller-allocated UCHAR variable set to TRUE (nonzero).
    • Enabling RAW_IO causes libusbK to send data directly to the USB driver stack, bypassing libusbK's queuing and error handling mechanism.
    • The buffers that are passed to UsbK_ReadPipe must be configured by the caller as follows:
      • The buffer length must be a multiple of the maximum endpoint packet size.
      • The length must be less than or equal to the value of MAXIMUM_TRANSFER_SIZE retrieved by UsbK_GetPipePolicy.
    • Disabling RAW_IO (FALSE) does not impose any restriction on the buffers that are passed to UsbK_ReadPipe.
  • RESET_PIPE_ON_RESUME (0x09)
    • The default value is FALSE (zero). To enable RESET_PIPE_ON_RESUME, in Value pass the address of a caller-allocated UCHAR variable set to TRUE (nonzero).
    • TRUE (or a nonzero value) indicates that on resume from suspend, libusbK resets the endpoint before it allows the caller to send new requests to the endpoint.
KUSB_EXP BOOL KUSB_API UsbK_GetPipePolicy ( _in KUSB_HANDLE  InterfaceHandle,
_in UCHAR  PipeID,
_in UINT  PolicyType,
_ref PUINT  ValueLength,
_out PVOID  Value 
)

Gets the policy for a specific pipe (endpoint).

Parameters
[in]InterfaceHandleAn initialized usb handle, see UsbK_Init.
[in]PipeIDAn 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.
[in]PolicyTypeA UINT variable that specifies the policy parameter to retrieve. The current value for the policy parameter is retrieved the Value parameter.
[in,out]ValueLengthA 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.
[out]ValueA pointer to a buffer that receives the specified pipe policy value.
Returns
On success, TRUE. Otherwise FALSE. Use GetLastError() to get extended error information.
KUSB_EXP BOOL KUSB_API UsbK_ReadPipe ( _in KUSB_HANDLE  InterfaceHandle,
_in UCHAR  PipeID,
_out PUCHAR  Buffer,
_in UINT  BufferLength,
_outopt PUINT  LengthTransferred,
_inopt LPOVERLAPPED  Overlapped 
)

Reads data from the specified pipe.

Parameters
[in]InterfaceHandleAn initialized usb handle, see UsbK_Init.
[in]PipeIDAn 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.
[out]BufferA caller-allocated buffer that receives the data that is read.
[in]BufferLengthThe maximum number of bytes to read. This number must be less than or equal to the size, in bytes, of Buffer.
[out]LengthTransferredA pointer to a UINT variable that receives the actual number of bytes that were copied into Buffer. For more information, see Remarks.
[in]OverlappedAn optional pointer to an overlapped structure for asynchronous operations. This can be a KOVL_HANDLE or a pointer to a standard windows OVERLAPPED structure. If this parameter is specified, UsbK_ReadPipe returns immediately rather than waiting synchronously for the operation to complete before returning. An event is signaled when the operation is complete.
Returns
On success, TRUE. Otherwise FALSE. Use GetLastError() to get extended error information.
KUSB_EXP BOOL KUSB_API UsbK_WritePipe ( _in KUSB_HANDLE  InterfaceHandle,
_in UCHAR  PipeID,
_in PUCHAR  Buffer,
_in UINT  BufferLength,
_outopt PUINT  LengthTransferred,
_inopt LPOVERLAPPED  Overlapped 
)

Writes data to a pipe.

Parameters
[in]InterfaceHandleAn initialized usb handle, see UsbK_Init.
[in]PipeIDAn 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.
[in]BufferA caller-allocated buffer the data is written from.
[in]BufferLengthThe maximum number of bytes to write. This number must be less than or equal to the size, in bytes, of Buffer.
[out]LengthTransferredA pointer to a UINT variable that receives the actual number of bytes that were transferred from Buffer. For more information, see Remarks.
[in]OverlappedAn optional pointer to an overlapped structure for asynchronous operations. This can be a KOVL_HANDLE or a pointer to a standard windows OVERLAPPED structure. If this parameter is specified, UsbK_WritePipe returns immediately rather than waiting synchronously for the operation to complete before returning. An event is signaled when the operation is complete.
Returns
On success, TRUE. Otherwise FALSE. Use GetLastError() to get extended error information.
KUSB_EXP BOOL KUSB_API UsbK_ResetPipe ( _in KUSB_HANDLE  InterfaceHandle,
_in UCHAR  PipeID 
)

Resets the data toggle and clears the stall condition on a pipe.

Parameters
[in]InterfaceHandleAn initialized usb handle, see UsbK_Init.
[in]PipeIDAn 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.
Returns
On success, TRUE. Otherwise FALSE. Use GetLastError() to get extended error information.
KUSB_EXP BOOL KUSB_API UsbK_AbortPipe ( _in KUSB_HANDLE  InterfaceHandle,
_in UCHAR  PipeID 
)

Aborts all of the pending transfers for a pipe.

Parameters
[in]InterfaceHandleAn initialized usb handle, see UsbK_Init.
[in]PipeIDAn 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.
Returns
On success, TRUE. Otherwise FALSE. Use GetLastError() to get extended error information.
KUSB_EXP BOOL KUSB_API UsbK_FlushPipe ( _in KUSB_HANDLE  InterfaceHandle,
_in UCHAR  PipeID 
)

Discards any data that is cached in a pipe.

Parameters
[in]InterfaceHandleAn initialized usb handle, see UsbK_Init.
[in]PipeIDAn 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.
Returns
On success, TRUE. Otherwise FALSE. Use GetLastError() to get extended error information.
KUSB_EXP BOOL KUSB_API UsbK_IsoReadPipe ( _in KUSB_HANDLE  InterfaceHandle,
_in UCHAR  PipeID,
_out PUCHAR  Buffer,
_in UINT  BufferLength,
_in LPOVERLAPPED  Overlapped,
_refopt PKISO_CONTEXT  IsoContext 
)

Reads from an isochronous pipe.

Parameters
[in]InterfaceHandleAn initialized usb handle, see UsbK_Init.
[in]PipeIDAn 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.
[out]BufferA caller-allocated buffer that receives the data that is read.
[in]BufferLengthThe maximum number of bytes to read. This number must be less than or equal to the size, in bytes, of Buffer.
[in]OverlappedA required pointer to an overlapped structure for asynchronous operations. This can be a KOVL_HANDLE or a pointer to a standard windows OVERLAPPED structure. If this parameter is specified, UsbK_IsoReadPipe returns immediately rather than waiting synchronously for the operation to complete before returning. An event is signaled when the operation is complete.
[in,out]IsoContextPointer to an isochronous transfer context created with IsoK_Init. If IsoContext is NULL,
Returns
On success, TRUE. Otherwise FALSE. Use GetLastError() to get extended error information.
Overlapped I/O considerations
If an Overlapped parameter is specified and the transfer is submitted successfully, the function returns FALSE and sets last error to ERROR_IO_PENDING. When using overlapped I/O, users may ignore the return results of this function and instead use the return results from one of the Overlapped I/O wait functions or from UsbK_GetOverlappedResult.
KUSB_EXP BOOL KUSB_API UsbK_IsoWritePipe ( _in KUSB_HANDLE  InterfaceHandle,
_in UCHAR  PipeID,
_in PUCHAR  Buffer,
_in UINT  BufferLength,
_in LPOVERLAPPED  Overlapped,
_refopt PKISO_CONTEXT  IsoContext 
)

Writes to an isochronous pipe.

Parameters
[in]InterfaceHandleAn initialized usb handle, see UsbK_Init.
[in]PipeIDAn 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.
[in]BufferA caller-allocated buffer that receives the data that is read.
[in]BufferLengthThe maximum number of bytes to write. This number must be less than or equal to the size, in bytes, of Buffer.
[in]OverlappedAn optional pointer to an overlapped structure for asynchronous operations. This can be a KOVL_HANDLE or a pointer to a standard windows OVERLAPPED structure. If this parameter is specified, UsbK_IsoWritePipe returns immediately rather than waiting synchronously for the operation to complete before returning. An event is signaled when the operation is complete.
[in,out]IsoContextPointer to an isochronous transfer context created with IsoK_Init. See remarks below.
Returns
On success, TRUE. Otherwise FALSE. Use GetLastError() to get extended error information.
KUSB_EXP BOOL KUSB_API UsbK_GetCurrentFrameNumber ( _in KUSB_HANDLE  InterfaceHandle,
_out PUINT  FrameNumber 
)

Retrieves the current USB frame number.

Parameters
[in]InterfaceHandleAn initialized usb handle, see UsbK_Init.
[out]FrameNumberA pointer to a location that receives the current 32-bit frame number on the USB bus (from the host controller driver).
Returns
On success, TRUE. Otherwise FALSE. Use GetLastError() to get extended error information.
KUSB_EXP BOOL KUSB_API UsbK_IsochReadPipe ( _in KISOCH_HANDLE  IsochHandle,
_inopt UINT  DataLength,
_refopt PUINT  FrameNumber,
_inopt UINT  NumberOfPackets,
_in LPOVERLAPPED  Overlapped 
)

Reads from an isochronous pipe. Supports LibusbK or WinUsb.

Parameters
[in]IsochHandleAn initialized isochronous transfer handle, see IsochK_Init.
[in]DataLengthThe number of bytes to read. This number must be less than or equal to the size in bytes, of the transfer buffer the IsochHandle was initialized with. You may pass 0 for this parameter to use the entire transfer buffer.
[in,out]FrameNumberPointer to the frame number this transfer should start on. Use UsbK_GetCurrentFrameNumber when this is unknown. When the function returns, this value will be updated to the next frame number for a subsequent transfer. This parameter is ignored if the /b ISO_ALWAYS_START_ASAP pipe policy is set and required otherwise. /sa UsbK_SetPipePolicy
// Get the current frame number
UINT StartFrameNumber;
Usb.GetCurrentFrameNumber(usbHandle, &StartFrameNumber);
// Give plenty of time to queue up all of our transfers BEFORE the bus starts consuming them
// Note that this is also the startup delay in milliseconds.
StartFrameNumber += 12
[in]NumberOfPacketsThe number of packets to read. This number must be less than or equal to the MaxNumberOfPackets value that the /b IsochHandle was initialized with. You may pass 0 for this parameter to use MaxNumberOfPackets.
[in]OverlappedA required pointer to an overlapped structure for asynchronous operations. This can be a KOVL_HANDLE or a pointer to a standard windows OVERLAPPED structure.
Returns
This function always returns FALSE. You must use GetLastError() after calling this function. If GetLastError() returns ERROR_IO_PENDING, then the transfer was started successfully and is in progress. Any other error code indicates a failure. See /ref OvlK_wait or UsbK_GetOverlappedResult
KUSB_EXP BOOL KUSB_API UsbK_IsochWritePipe ( _in KISOCH_HANDLE  IsochHandle,
_inopt UINT  DataLength,
_ref PUINT  FrameNumber,
_inopt UINT  NumberOfPackets,
_in LPOVERLAPPED  Overlapped 
)

Writes to an isochronous pipe. Supports LibusbK or WinUsb.

Parameters
[in]IsochHandleAn initialized isochronous transfer handle, see IsochK_Init.
[in]DataLengthThe number of bytes to write. This number must be less than or equal to the size in bytes, of the transfer buffer the IsochHandle was initialized with. You may pass 0 for this parameter to use the entire transfer buffer.
[in,out]FrameNumberPointer to the frame number this transfer should start on. Use UsbK_GetCurrentFrameNumber when this is unknown. When the function returns, this value will be updated to the next frame number for a subsequent transfer. This parameter is ignored if the /b ISO_ALWAYS_START_ASAP pipe policy is set and required otherwise. /sa UsbK_SetPipePolicy
// Get the current frame number
UINT StartFrameNumber;
Usb.GetCurrentFrameNumber(usbHandle, &StartFrameNumber);
// Give plenty of time to queue up all of our transfers BEFORE the bus starts consuming them
// Note that this is also the startup delay in milliseconds.
StartFrameNumber += 12
[in]NumberOfPacketsThe number of packets to write. This number must be less than or equal to the MaxNumberOfPackets value that the /b IsochHandle was initialized with. You may pass 0 for this parameter to use MaxNumberOfPackets.
[in]OverlappedA required pointer to an overlapped structure for asynchronous operations. This can be a KOVL_HANDLE or a pointer to a standard windows OVERLAPPED structure.
Returns
This function always returns FALSE. You must use GetLastError() after calling this function. If GetLastError() returns ERROR_IO_PENDING, then the transfer was started successfully and is in progress. Any other error code indicates a failure. See /ref OvlK_wait or UsbK_GetOverlappedResult
KUSB_EXP BOOL KUSB_API UsbK_GetOverlappedResult ( _in KUSB_HANDLE  InterfaceHandle,
_in LPOVERLAPPED  Overlapped,
_out PUINT  lpNumberOfBytesTransferred,
_in BOOL  bWait 
)

Retrieves the results of an overlapped operation on the specified libusbK handle.

Parameters
[in]InterfaceHandleAn initialized usb handle, see UsbK_Init.
[in]OverlappedA pointer to a standard windows OVERLAPPED structure that was specified when the overlapped operation was started.
[out]lpNumberOfBytesTransferredA pointer to a variable that receives the number of bytes that were actually transferred by a read or write operation.
[in]bWaitIf this parameter is TRUE, the function does not return until the operation has been completed. If this parameter is FALSE and the operation is still pending, the function returns FALSE and the GetLastError function returns ERROR_IO_INCOMPLETE.
Returns
On success, TRUE. Otherwise FALSE. Use GetLastError() to get extended error information.

This function is like the Win32 API routine, GetOverlappedResult, with one difference; instead of passing a file handle that is returned from CreateFile, the caller passes an interface handle that is returned from UsbK_Initialize, UsbK_Init, or UsbK_GetAssociatedInterface. The caller can use either API routine, if the appropriate handle is passed. The UsbK_GetOverlappedResult function extracts the file handle from the interface handle and then calls GetOverlappedResult.
The results that are reported by the UsbK_GetOverlappedResult function are those from the specified handle's last overlapped operation to which the specified standard windows OVERLAPPED structure was provided, and for which the operation's results were pending. A pending operation is indicated when the function that started the operation returns FALSE, and the GetLastError routine returns ERROR_IO_PENDING. When an I/O operation is pending, the function that started the operation resets the hEvent member of the standard windows OVERLAPPED structure to the nonsignaled state. Then when the pending operation has been completed, the system sets the event object to the signaled state.
The caller can specify that an event object is manually reset in the standard windows OVERLAPPED structure. If an automatic reset event object is used, the event handle must not be specified in any other wait operation in the interval between starting the overlapped operation and the call to UsbK_GetOverlappedResult. For example, the event object is sometimes specified in one of the wait routines to wait for the operation to be completed. When the wait routine returns, the system sets an auto-reset event's state to nonsignaled, and a successive call to UsbK_GetOverlappedResult with the bWait parameter set to TRUE causes the function to be blocked indefinitely.

If the bWait parameter is TRUE, UsbK_GetOverlappedResult determines whether the pending operation has been completed by waiting for the event object to be in the signaled state.

If the hEvent member of the standard windows OVERLAPPED structure is NULL, the system uses the state of the file handle to signal when the operation has been completed. Do not use file handles for this purpose. It is better to use an event object because of the confusion that can occur when multiple concurrent overlapped operations are performed on the same file. In this situation, you cannot know which operation caused the state of the object to be signaled.

KUSB_EXP BOOL KUSB_API UsbK_GetProperty ( _in KUSB_HANDLE  InterfaceHandle,
_in KUSB_PROPERTY  PropertyType,
_ref PUINT  PropertySize,
_out PVOID  Value 
)

Gets a USB device (driver specific) property from usb handle.

Parameters
[in]InterfaceHandleUSB handle of the property to retrieve.
[in]PropertyTypeThe propety type to retrieve.
[in,out]PropertySizeSize in bytes of Value.
[out]ValueOn success, receives the proprty data.
Returns
On success, TRUE. Otherwise FALSE. Use GetLastError() to get extended error information.
  • Generated on Mon Jul 19 2021 10:42:37 by doxygen 1.8.6