Função CM_Get_Device_Interface_ListW (cfgmgr32.h)
A função CM_Get_Device_Interface_List recupera uma lista de instâncias de interface do dispositivo que pertencem a uma classe de interface de dispositivo especificada.
Sintaxe
CMAPI CONFIGRET CM_Get_Device_Interface_ListW(
[in] LPGUID InterfaceClassGuid,
[in, optional] DEVINSTID_W pDeviceID,
[out] PZZWSTR Buffer,
[in] ULONG BufferLen,
[in] ULONG ulFlags
);
Parâmetros
[in] InterfaceClassGuid
Fornece um GUID que identifica uma classe de interface de dispositivo.
[in, optional] pDeviceID
Ponteiro fornecido pelo chamador para uma cadeia de caracteres terminada em NULL que representa uma ID de instância do dispositivo. Se especificada, a função recupera interfaces de dispositivo compatíveis com o dispositivo para a classe especificada. Se esse valor for NULL ou se ele apontar para uma cadeia de caracteres de comprimento zero, a função recuperará todas as interfaces que pertencem à classe especificada.
[out] Buffer
Ponteiro fornecido pelo chamador para um buffer que recebe várias cadeias de caracteres Unicode terminadas em NULL, cada uma representando o nome simbólico do link de uma instância de interface.
[in] BufferLen
Valor fornecido pelo chamador que especifica o comprimento, em caracteres, do buffer apontado por Buffer. Chame CM_Get_Device_Interface_List_Size para determinar o tamanho do buffer necessário.
[in] ulFlags
Contém um dos seguintes sinalizadores fornecidos pelo chamador:
CM_GET_DEVICE_INTERFACE_LIST_ALL_DEVICES
A função fornece uma lista que contém interfaces de dispositivo associadas a todos os dispositivos que correspondem ao GUID especificado e à ID da instância do dispositivo, se houver.
CM_GET_DEVICE_INTERFACE_LIST_PRESENT
A função fornece uma lista que contém interfaces de dispositivo associadas a dispositivos que estão ativos no momento e que correspondem ao GUID especificado e à ID da instância do dispositivo, se houver.
Retornar valor
Se a operação for bem-sucedida, a função retornará CR_SUCCESS. Caso contrário, ele retornará um dos códigos de erro com o prefixo CR_, conforme definido em Cfgmgr32.h.
A tabela a seguir inclui alguns dos códigos de erro mais comuns que essa função pode retornar.
Código de retorno | Descrição |
---|---|
|
O buffer de buffer é muito pequeno para manter a lista solicitada de interfaces de dispositivo. |
Comentários
Entre chamar CM_Get_Device_Interface_List_Size para obter o tamanho da lista e chamar CM_Get_Device_Interface_List para obter a lista, uma nova interface de dispositivo pode ser adicionada ao sistema, fazendo com que o tamanho retornado não seja mais válido. Os chamadores devem ser robustos para essa condição e tentar novamente obter o tamanho e a lista se CM_Get_Device_Interface_List retornar CR_BUFFER_SMALL.
Exemplos
Este snippet ilustra a repetição da obtenção do tamanho e da lista, conforme descrito na seção Comentários.
CONFIGRET cr = CR_SUCCESS;
PWSTR DeviceInterfaceList = NULL;
ULONG DeviceInterfaceListLength = 0;
do {
cr = CM_Get_Device_Interface_List_Size(&DeviceInterfaceListLength,
(LPGUID)&GUID_DEVINTERFACE_VOLUME,
NULL,
CM_GET_DEVICE_INTERFACE_LIST_ALL_DEVICES);
if (cr != CR_SUCCESS)
{
break;
}
if (DeviceInterfaceList != NULL) {
HeapFree(GetProcessHeap(),
0,
DeviceInterfaceList);
}
DeviceInterfaceList = (PWSTR)HeapAlloc(GetProcessHeap(),
HEAP_ZERO_MEMORY,
DeviceInterfaceListLength * sizeof(WCHAR));
if (DeviceInterfaceList == NULL)
{
cr = CR_OUT_OF_MEMORY;
break;
}
cr = CM_Get_Device_Interface_List((LPGUID)&GUID_DEVINTERFACE_VOLUME,
NULL,
DeviceInterfaceList,
DeviceInterfaceListLength,
CM_GET_DEVICE_INTERFACE_LIST_ALL_DEVICES);
} while (cr == CR_BUFFER_SMALL);
if (cr != CR_SUCCESS)
{
goto Exit;
}
Observação
O cabeçalho cfgmgr32.h define CM_Get_Device_Interface_List como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante de pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.
Requisitos
Requisito | Valor |
---|---|
Cliente mínimo com suporte | Disponível no Microsoft Windows 2000 e versões posteriores do Windows. |
Plataforma de Destino | Universal |
Cabeçalho | cfgmgr32.h (inclua Cfgmgr32.h) |
Biblioteca | Cfgmgr32.lib |
DLL | CfgMgr32.dll |