Função CM_Get_Device_Interface_ListA (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_ListA(
  [in]           LPGUID      InterfaceClassGuid,
  [in, optional] DEVINSTID_A pDeviceID,
  [out]          PZZSTR      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
CR_BUFFER_SMALL	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

Confira também

CM_Get_Device_Interface_List_Size