CM_Get_Device_Interface_AliasW function (cfgmgr32.h)

Article
02/09/2023

The CM_Get_Device_Interface_Alias function returns the alias of the specified device interface instance, if the alias exists.

Syntax

CMAPI CONFIGRET CM_Get_Device_Interface_AliasW(
  [in]      LPCWSTR pszDeviceInterface,
  [in]      LPGUID  AliasInterfaceGuid,
  [out]     LPWSTR  pszAliasDeviceInterface,
  [in, out] PULONG  pulLength,
  [in]      ULONG   ulFlags
);

Parameters

[in] pszDeviceInterface

Pointer to the name of the device interface instance for which to retrieve an alias. The caller typically received this string from a call to CM_Get_Device_Interface_List, or in a PnP notification structure.

[in] AliasInterfaceGuid

Pointer to a GUID specifying the interface class of the alias to retrieve.

[out] pszAliasDeviceInterface

Specifies a pointer to a buffer, that upon successful return, points to a string containing the name of the alias. The caller must free this string when it is no longer needed.

A buffer is required. Otherwise, the call will fail.

[in, out] pulLength

Supplies the count of characters in pszAliasDeviceInterface and receives the number of characters required to hold the alias device interface.

On input, this parameter must be greater than 0.

[in] ulFlags

Reserved. Do not use.

Return value

If the operation succeeds, the function returns CR_SUCCESS. Otherwise, it returns one of the CR_-prefixed error codes defined in Cfgmgr32.h.

Return code	Description
CR_NO_SUCH_DEVICE_INTERFACE	Possibly indicates that there is no alias of the specified interface class.
CR_OUT_OF_MEMORY	There is not enough memory to complete the operation.
CR_BUFFER_SMALL	The buffer passed is too small.

Remarks

Device interfaces are considered aliases if they are exposed by the same underlying device and have identical interface reference strings, but are of different interface classes.

The pszDeviceInterface parameter specifies a device interface instance for a particular device, belonging to a particular interface class, with a particular reference string. CM_Get_Device_Interface_Alias returns another device interface instance for the same device and reference string, but of a different interface class, if it exists.

For example, the function driver for a fault-tolerant volume could register and set two device interfaces, one of the fault-tolerant-volume interface class and one of the volume interface class. Another driver could call CM_Get_Device_Interface_Alias with the symbolic link for one of the interfaces and ask whether the other interface exists by specifying its interface class.

Two device interfaces with NULL reference strings are aliases if they are exposed by the same underlying device and have different interface class GUIDs.

Requirements

Requirement	Value
Minimum supported client	Available in Microsoft Windows 2000 and later versions of Windows.
Target Platform	Desktop
Header	cfgmgr32.h (include Cfgmgr32.h)
Library	Cfgmgr32.lib

Share via