libusbK 
3.0
Library Documentation
© 2011-2021 Travis Lee Robinson. All rights reserved.
Device List

Module for USB device discovery and enumeration. More...

Data Structures

struct  KLST_DEV_COMMON_INFO
 Common usb device information structure. More...
 
struct  KLST_DEVINFO
 Semi-opaque device information structure of a device list. More...
 
struct  KLST_PATTERN_MATCH
 Device list/hot-plug pattern match structure. More...
 

Macros

#define KLST_STRING_MAX_LEN   256
 Allocated length for all strings in a KLST_DEVINFO structure.
 

Typedefs

typedef KLST_DEV_COMMON_INFOPKLST_DEV_COMMON_INFO
 Pointer to a KLST_DEV_COMMON_INFO structure.
 
typedef KLST_DEVINFOKLST_DEVINFO_HANDLE
 Pointer to a KLST_DEVINFO structure. (semi-opaque)
 
typedef KLST_PATTERN_MATCHPKLST_PATTERN_MATCH
 Pointer to a KLST_PATTERN_MATCH structure.
 
typedef BOOL KUSB_API KLST_ENUM_DEVINFO_CB (_in KLST_HANDLE DeviceList, _in KLST_DEVINFO_HANDLE DeviceInfo, _in PVOID Context)
 Device list enumeration function callback typedef. More...
 

Enumerations

enum  KLST_SYNC_FLAG {
  KLST_SYNC_FLAG_NONE = 0L,
  KLST_SYNC_FLAG_UNCHANGED = 0x0001,
  KLST_SYNC_FLAG_ADDED = 0x0002,
  KLST_SYNC_FLAG_REMOVED = 0x0004,
  KLST_SYNC_FLAG_CONNECT_CHANGE = 0x0008,
  KLST_SYNC_FLAG_MASK = 0x000F
}
 Device list sync flags. More...
 
enum  KLST_FLAG {
  KLST_FLAG_NONE = 0L,
  KLST_FLAG_INCLUDE_RAWGUID = 0x0001,
  KLST_FLAG_INCLUDE_DISCONNECT = 0x0002
}
 Device list initialization flags. More...
 

Functions

KUSB_EXP BOOL KUSB_API LstK_Init (_out KLST_HANDLE *DeviceList, _in KLST_FLAG Flags)
 Initializes a new usb device list containing all supported devices. More...
 
KUSB_EXP BOOL KUSB_API LstK_InitEx (_out KLST_HANDLE *DeviceList, _in KLST_FLAG Flags, _in PKLST_PATTERN_MATCH PatternMatch)
 Initializes a new usb device list containing only devices matching a specific class GUID. More...
 
KUSB_EXP BOOL KUSB_API LstK_Free (_in KLST_HANDLE DeviceList)
 Frees a usb device list. More...
 
KUSB_EXP BOOL KUSB_API LstK_Enumerate (_in KLST_HANDLE DeviceList, _in KLST_ENUM_DEVINFO_CB *EnumDevListCB, _inopt PVOID Context)
 Enumerates KLST_DEVINFO elements of a KLST_HANDLE. More...
 
KUSB_EXP BOOL KUSB_API LstK_Current (_in KLST_HANDLE DeviceList, _out KLST_DEVINFO_HANDLE *DeviceInfo)
 Gets the KLST_DEVINFO element for the current position. More...
 
KUSB_EXP BOOL KUSB_API LstK_MoveNext (_in KLST_HANDLE DeviceList, _outopt KLST_DEVINFO_HANDLE *DeviceInfo)
 Advances the device list current KLST_DEVINFO position. More...
 
KUSB_EXP VOID KUSB_API LstK_MoveReset (_in KLST_HANDLE DeviceList)
 Sets the device list to its initial position, which is before the first element in the list. More...
 
KUSB_EXP BOOL KUSB_API LstK_FindByVidPid (_in KLST_HANDLE DeviceList, _in INT Vid, _in INT Pid, _out KLST_DEVINFO_HANDLE *DeviceInfo)
 Find a device by vendor and product id. More...
 
KUSB_EXP BOOL KUSB_API LstK_Count (_in KLST_HANDLE DeviceList, _ref PUINT Count)
 Counts the number of device info elements in a device list. More...
 

Detailed Description

Module for USB device discovery and enumeration.

Typedef Documentation

typedef BOOL KUSB_API KLST_ENUM_DEVINFO_CB(_in KLST_HANDLE DeviceList, _in KLST_DEVINFO_HANDLE DeviceInfo, _in PVOID Context)

Device list enumeration function callback typedef.

Parameters
DeviceListThe device list DeviceInfo belongs to
DeviceInfoDevice information
ContextUser context that was passed into LstK_Enumerate

Use this typedef as a prototype for an enumeration function with LstK_Enumerate.

Enumeration Type Documentation

Device list sync flags.

These sync flags are also use by the hot plug module to indicate device arrival/removal notifications:

  • DeviceArrival = KLST_SYNC_FLAG_ADDED
  • DeviceRemoval = KLST_SYNC_FLAG_REMOVED
Enumerator
KLST_SYNC_FLAG_NONE 

Cleared/invalid state.

KLST_SYNC_FLAG_UNCHANGED 

Unchanged state,.

KLST_SYNC_FLAG_ADDED 

Added (Arrival) state,.

KLST_SYNC_FLAG_REMOVED 

Removed (Unplugged) state,.

KLST_SYNC_FLAG_CONNECT_CHANGE 

Connect changed state.

KLST_SYNC_FLAG_MASK 

All states.

enum KLST_FLAG

Device list initialization flags.

Enumerator
KLST_FLAG_NONE 

No flags (or 0)

KLST_FLAG_INCLUDE_RAWGUID 

Enable listings for the raw device interface GUID only. {A5DCBF10-6530-11D2-901F-00C04FB951ED}.

KLST_FLAG_INCLUDE_DISCONNECT 

List all libusbK devices including those not currently connected.

Function Documentation

KUSB_EXP BOOL KUSB_API LstK_Init ( _out KLST_HANDLE DeviceList,
_in KLST_FLAG  Flags 
)

Initializes a new usb device list containing all supported devices.

Parameters
[out]DeviceListPointer reference that will receive a populated device list.
[in]FlagsSearch, filter, and listing options. see KLST_FLAG
Returns
On success, TRUE. Otherwise FALSE. Use GetLastError() to get extended error information.

LstK_Init populates DeviceList with connected usb devices that can be used by libusbK.

Note
if LstK_Init returns TRUE, the device list must be freed with LstK_Free when it is no longer needed.
Examples:
show-device.c.
KUSB_EXP BOOL KUSB_API LstK_InitEx ( _out KLST_HANDLE DeviceList,
_in KLST_FLAG  Flags,
_in PKLST_PATTERN_MATCH  PatternMatch 
)

Initializes a new usb device list containing only devices matching a specific class GUID.

Parameters
[out]DeviceListPointer reference that will receive a populated device list.
[in]FlagsSearch, filter, and listing options. see KLST_FLAG
[in]PatternMatchPattern Search filter.
Returns
On success, TRUE. Otherwise FALSE. Use GetLastError() to get extended error information.

LstK_InitEx populates DeviceList with usb devices that can be used by libusbK. Only device matching the KLST_PATTERN_MATCH string are included in the list.

Note
This function significantly improves performance when used with a device interface guid pattern patch.
if LstK_InitEx returns TRUE, the device list must be freed with LstK_Free when it it's no longer needed.
KUSB_EXP BOOL KUSB_API LstK_Free ( _in KLST_HANDLE  DeviceList)

Frees a usb device list.

Note
if LstK_Init returns TRUE, the device list must be freed with LstK_Free when it is no longer needed.
Parameters
[in]DeviceListThe DeviceList to free.
Returns
NONE

Frees all resources that were allocated to DeviceList by LstK_Init.

Examples:
config-interface.c, load-driver-api.c, open-device.c, pipe-policy-timeout.c, power-policy-suspend.c, show-device.c, xfer-async-loop.c, xfer-async.c, xfer-control.c, xfer-iso-asap.c, xfer-iso.c, xfer-stream.c, and xfer-sync.c.
KUSB_EXP BOOL KUSB_API LstK_Enumerate ( _in KLST_HANDLE  DeviceList,
_in KLST_ENUM_DEVINFO_CB EnumDevListCB,
_inopt PVOID  Context 
)

Enumerates KLST_DEVINFO elements of a KLST_HANDLE.

Parameters
[in]DeviceListThe DeviceList to enumerate.
[in]EnumDevListCBFunction to call for each iteration.
[in]ContextOptional user context pointer.
Returns
On success, TRUE. Otherwise FALSE. Use GetLastError() to get extended error information.

Calls EnumDevListCB for each element in the device list or until EnumDevListCB returns FALSE.

Examples:
show-device.c.
KUSB_EXP BOOL KUSB_API LstK_Current ( _in KLST_HANDLE  DeviceList,
_out KLST_DEVINFO_HANDLE DeviceInfo 
)

Gets the KLST_DEVINFO element for the current position.

Parameters
[in]DeviceListThe DeviceList to retrieve a current KLST_DEVINFO for.
[out]DeviceInfoThe device information.
Returns
On success, TRUE. Otherwise FALSE. Use GetLastError() to get extended error information.

After a DeviceList is created or after the LstK_MoveReset method is called, the LstK_MoveNext method must be called to advance the device list enumerator to the first element of the DeviceList before calling LstK_Current otherwise, DeviceInfo is undefined.

LstK_Current returns FALSE and sets last error to ERROR_NO_MORE_ITEMS if the last call to LstK_MoveNext returned FALSE, which indicates the end of the DeviceList.

LstK_Current does not move the position of the device list enumerator, and consecutive calls to LstK_Current return the same object until either LstK_MoveNext or LstK_MoveReset is called.

KUSB_EXP BOOL KUSB_API LstK_MoveNext ( _in KLST_HANDLE  DeviceList,
_outopt KLST_DEVINFO_HANDLE DeviceInfo 
)

Advances the device list current KLST_DEVINFO position.

Parameters
[in]DeviceListA usb device list returned by LstK_Init
[out]DeviceInfoOn success, contains a pointer to the device information for the current enumerators position.
Returns
On success, TRUE. Otherwise FALSE. Use GetLastError() to get extended error information.

After a DeviceList is created or after LstK_MoveReset is called, an enumerator is positioned before the first element of the DeviceList and the first call to LstK_MoveNext moves the enumerator over the first element of the DeviceList.

If LstK_MoveNext passes the end of the DeviceList, the enumerator is positioned after the last element in the DeviceList and LstK_MoveNext returns FALSE. When the enumerator is at this position, a subsequent call to LstK_MoveNext will reset the enumerator and it continues from the beginning.

Examples:
show-device.c.
KUSB_EXP VOID KUSB_API LstK_MoveReset ( _in KLST_HANDLE  DeviceList)

Sets the device list to its initial position, which is before the first element in the list.

Parameters
[in]DeviceList
Returns
On success, TRUE. Otherwise FALSE. Use GetLastError() to get extended error information.
Examples:
show-device.c.
KUSB_EXP BOOL KUSB_API LstK_FindByVidPid ( _in KLST_HANDLE  DeviceList,
_in INT  Vid,
_in INT  Pid,
_out KLST_DEVINFO_HANDLE DeviceInfo 
)

Find a device by vendor and product id.

Parameters
[in]DeviceListThe DeviceList to retrieve a current KLST_DEVINFO for.
[in]VidID is used in conjunction with the Pid to uniquely identify USB devices, providing traceability to the OEM.
[in]PidID is used in conjunction with the Pid to uniquely identify USB devices, providing traceability to the OEM.
[out]DeviceInfoOn success, the device information pointer, otherwise NULL.
Returns
  • TRUE if the device was found
  • FALSE if the device was not found or an error occurred.
    • Sets last error to ERROR_NO_MORE_ITEMS if the device was not found.

Searches all elements in DeviceList for usb device matching the specified.

Examples:
show-device.c.
KUSB_EXP BOOL KUSB_API LstK_Count ( _in KLST_HANDLE  DeviceList,
_ref PUINT  Count 
)

Counts the number of device info elements in a device list.

Parameters
[in]DeviceListThe deice list to count.
[in,out]CountOn success, receives the number of KLST_DEVINFO elements in the list.
Returns
On success, TRUE. Otherwise FALSE. Use GetLastError() to get extended error information.
Examples:
show-device.c.