WinUsb_GetAssociatedInterface function (winusb.h)

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

Syntax

BOOL WinUsb_GetAssociatedInterface(
  [in]  WINUSB_INTERFACE_HANDLE  InterfaceHandle,
  [in]  UCHAR                    AssociatedInterfaceIndex,
  [out] PWINUSB_INTERFACE_HANDLE AssociatedInterfaceHandle
);

Parameters

[in] InterfaceHandle

An opaque handle to the first (default) interface on the device, which is returned by WinUsb_Initialize.

[in] AssociatedInterfaceIndex

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.

[out] AssociatedInterfaceHandle

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

Requirements

Requirement Value
Target Platform Universal
Header winusb.h (include Winusb.h)
Library Winusb.lib
DLL Winusb.dll

See also

WinUSB

WinUSB Functions

WinUsb_Initialize