função CM_Get_Device_Interface_ListW (cfgmgr32.h)

Artigo
11/20/2024

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 do dispositivo.

[in, optional] pDeviceID

Ponteiro fornecido pelo chamador para uma cadeia de caracteres terminada por NULL que representa uma ID da 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 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 por NULL, cada uma representando o nome de link simbólico 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 à ID da instância de dispositivo e GUID especificada, se houver.

Valor de retorno

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 do buffer é muito pequeno para manter a lista solicitada de interfaces de dispositivo.

Observações

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 do 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;
    }

Nota

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 do pré-processador UNICODE. A combinação do uso do alias neutro de codificação com código que não é neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Conventions for Function Prototypes.

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Disponível no Microsoft Windows 2000 e versões posteriores do Windows.
da Plataforma de Destino	Universal
cabeçalho	cfgmgr32.h (inclua Cfgmgr32.h)
biblioteca	Cfgmgr32.lib
de DLL	CfgMgr32.dll

Consulte também

CM_Get_Device_Interface_List_Size

Compartilhar via