WinUsb_GetAssociatedInterface function

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

Syntax

C++


BOOL __stdcall WinUsb_GetAssociatedInterface(
  _In_   WINUSB_INTERFACE_HANDLE InterfaceHandle,
  _In_   UCHAR AssociatedInterfaceIndex,
  _Out_  PWINUSB_INTERFACE_HANDLE AssociatedInterfaceHandle
);

Parameters

InterfaceHandle [in]: An opaque handle to the first (default) interface on the device, which is returned by WinUsb_Initialize.
AssociatedInterfaceIndex [in]: An index that specifies the associated interface to retrieve. A value of 0 indicates the first associated interface, a value of 1 indicates the second associated interface, and so on.
AssociatedInterfaceHandle [out]: A handle for the associated interface. Callers must pass this interface handle to WinUSB Functions exposed by Winusb.dll. To close this handle, call WinUsb_Free.

Return value

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

Return code	Description
ERROR_ALREADY_EXISTS	WinUsb_GetAssociatedInterface has already returned a handle for the interface that AssociatedInterfaceIndex specifies.
ERROR_INVALID_HANDLE	The caller passed NULL in the InterfaceHandle parameter.
ERROR_INVALID_PARAMETER	The passed AssociatedInterfaceIndex value failed an integer overflow check.
ERROR_NO_MORE_ITEMS	An interface does not exist for the specified AssociatedInterfaceIndex value.
ERROR_NOT_ENOUGH_MEMORY	Indicates that there is insufficient memory to perform the operation.

Remarks

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_GetAssociatedInterfacecan 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.

Requirements