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_INFO *	PKLST_DEV_COMMON_INFO
	Pointer to a KLST_DEV_COMMON_INFO structure.
typedef KLST_DEVINFO *	KLST_DEVINFO_HANDLE
	Pointer to a KLST_DEVINFO structure. (semi-opaque)
typedef KLST_PATTERN_MATCH *	PKLST_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

DeviceList	The device list DeviceInfo belongs to
DeviceInfo	Device information
Context	User context that was passed into LstK_Enumerate

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

Enumeration Type Documentation

enum KLST_SYNC_FLAG

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]	DeviceList	Pointer reference that will receive a populated device list.
[in]	Flags	Search, 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]	DeviceList	Pointer reference that will receive a populated device list.
[in]	Flags	Search, filter, and listing options. see KLST_FLAG
[in]	PatternMatch	Pattern 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]

DeviceList

The 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]	DeviceList	The DeviceList to enumerate.
[in]	EnumDevListCB	Function to call for each iteration.
[in]	Context	Optional 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]	DeviceList	The DeviceList to retrieve a current KLST_DEVINFO for.
[out]	DeviceInfo	The 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]	DeviceList	A usb device list returned by LstK_Init
[out]	DeviceInfo	On 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]	DeviceList	The DeviceList to retrieve a current KLST_DEVINFO for.
[in]	Vid	ID is used in conjunction with the Pid to uniquely identify USB devices, providing traceability to the OEM.
[in]	Pid	ID is used in conjunction with the Pid to uniquely identify USB devices, providing traceability to the OEM.
[out]	DeviceInfo	On 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]	DeviceList	The deice list to count.
[in,out]	Count	On 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.