função CM_Get_Device_ID_ListW (cfgmgr32.h)
A função CM_Get_Device_ID_List recupera uma lista de IDs de instância do dispositivo para as instâncias de dispositivo do computador local.
Sintaxe
CMAPI CONFIGRET CM_Get_Device_ID_ListW(
[in, optional] PCWSTR pszFilter,
[out] PZZWSTR Buffer,
[in] ULONG BufferLen,
[in] ULONG ulFlags
);
Parâmetros
[in, optional] pszFilter
Ponteiro fornecido pelo chamador para uma cadeia de caracteres que é definida como um subconjunto das IDs (identificadores de instância de dispositivo) do computador ou como NULL. Confira a descrição a seguir de ulFlags.
[out] Buffer
Endereço de um buffer para receber um conjunto de cadeias de caracteres de identificador de instância de dispositivo terminadas em NULL. O final do conjunto é encerrado por um NULL extra. O tamanho do buffer necessário deve ser obtido chamando CM_Get_Device_ID_List_Size.
[in] BufferLen
Comprimento fornecido pelo chamador, em caracteres, do buffer especificado pelo Buffer.
[in] ulFlags
Um dos seguintes sinalizadores de bits fornecidos pelo chamador que especifica filtros de pesquisa:
CM_GETIDLIST_FILTER_BUSRELATIONS
Se esse sinalizador estiver definido, pszFilter deverá especificar um identificador de instância do dispositivo. A função retorna IDs de instância do dispositivo para as relações de barramento da instância de dispositivo especificada.
CM_GETIDLIST_FILTER_CLASS (Windows 7 e versões posteriores do Windows)
Se esse sinalizador estiver definido, pszFilter conterá uma cadeia de caracteres que especifica um GUID de classe de instalação do dispositivo . A lista retornada contém instâncias de dispositivo para as quais a propriedade (referenciada pela constante CM_DRP_CLASSGUID) corresponde ao GUID da classe de instalação do dispositivo especificado.
A constante CM_DRP_CLASSGUID é definida em Cfgmgr32.h.
CM_GETIDLIST_FILTER_PRESENT (Windows 7 e versões posteriores do Windows)
Se esse sinalizador estiver definido, a lista retornada conterá apenas as instâncias do dispositivo que estão atualmente presentes no sistema. Esse valor pode ser combinado com outros valores ulFlags , como CM_GETIDLIST_FILTER_CLASS.
CM_GETIDLIST_FILTER_TRANSPORTRELATIONS (Windows 7 e versões posteriores do Windows)
Se esse sinalizador estiver definido, pszFilter deverá especificar o identificador de instância do dispositivo de um nó de dispositivo composto (devnode).
A função retorna os identificadores de instância do dispositivo dos devnodes que representam as relações de transporte do devnode composto especificado.
Para obter mais informações sobre devnodes compostos e relações de transporte, consulte a seção Comentários a seguir.
CM_GETIDLIST_DONOTGENERATE
Usado somente com CM_GETIDLIST_FILTER_SERVICE. Se definido e se a árvore de dispositivos não contiver um devnode para o serviço especificado, esse sinalizador impedirá que a função crie um devnode para o serviço.
CM_GETIDLIST_FILTER_EJECTRELATIONS
Se esse sinalizador estiver definido, pszFilter deverá especificar um identificador de instância do dispositivo. A função retorna IDs de instância do dispositivo para as relações de ejeção da instância de dispositivo especificada.
CM_GETIDLIST_FILTER_ENUMERATOR
Se esse sinalizador estiver definido, pszFilter deverá especificar o nome de um enumerador de dispositivo, opcionalmente seguido por uma ID do dispositivo. O formato de cadeia de caracteres é EnumeratorName\<DeviceID>, como ROOT ou ROOT\*PNP0500.
Se pszFilter fornecer apenas um nome de enumerador, a função retornará IDs de instância do dispositivo para as instâncias de cada dispositivo associado ao enumerador. Os nomes do enumerador podem ser obtidos chamando CM_Enumerate_Enumerators.
Se o pszFilter fornecer um enumerador e uma ID do dispositivo, a função retornará IDs de instância do dispositivo somente para as instâncias do dispositivo especificado associadas ao enumerador.
CM_GETIDLIST_FILTER_NONE
Se esse sinalizador estiver definido, pszFilter será ignorado e uma lista de todos os dispositivos no sistema será retornada.
CM_GETIDLIST_FILTER_POWERRELATIONS
Se esse sinalizador estiver definido, pszFilter deverá especificar um identificador de instância do dispositivo. A função retorna IDs de instância do dispositivo para as relações de energia da instância de dispositivo especificada.
CM_GETIDLIST_FILTER_REMOVALRELATIONS
Se esse sinalizador estiver definido, pszFilter deverá especificar um identificador de instância do dispositivo. A função retorna IDs de instância do dispositivo para as relações de remoção da instância de dispositivo especificada.
CM_GETIDLIST_FILTER_SERVICE
Se esse sinalizador estiver definido, pszFilter deverá especificar o nome de um serviço Microsoft Windows (normalmente um driver). A função retorna IDs de instância do dispositivo para as instâncias de dispositivo controladas pelo serviço especificado.
Observe que, se a árvore de dispositivos não contiver um devnode para o serviço especificado, essa função criará uma por padrão. Para inibir esse comportamento, defina também CM_GETIDLIST_DONOTGENERATE.
Se nenhum sinalizador de filtro de pesquisa for especificado, a função retornará todas as IDs de instância do dispositivo para todas as instâncias do dispositivo.
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 prefixados por CR_ definidos em Cfgmgr32.h.
Comentários
A partir do Windows 7, um dispositivo que dá suporte a vários caminhos de transporte para dados baseados em pacotes é conhecido como um dispositivo composto e é representado por um devnodecomposto. Um devnode composto representa logicamente o dispositivo composto para o usuário e os aplicativos como um único dispositivo, embora o devnode composto possa ter vários caminhos para o dispositivo físico.
Cada caminho de transporte ativo para o dispositivo físico é representado por um devnode de transporte e é conhecido como uma relação de transporte para o dispositivo composto.
O devnode composto (mas não os devnodes de transporte relacionados) expõe interfaces de dispositivo para aplicativos e o sistema. Quando um aplicativo usa essas interfaces de dispositivo público, o dispositivo composto roteia os dados baseados em pacote para um ou mais desses devnodes de transporte, que transportam os dados para o dispositivo físico.
Por exemplo, se um celular físico estiver conectado simultaneamente ao computador no USB e nos barramentos Bluetooth, cada barramento enumerará um devnode de transporte filho nesse barramento para representar a conexão física do dispositivo.
Nesse caso, se você definir os sinalizadores de CM_GETIDLIST_FILTER_TRANSPORTRELATIONS em ulFlags e especificar a ID da instância do dispositivo do devnode composto do telefone celular em pszFilter, a função retornará as IDs de instância do dispositivo para os dois devnodes de transporte no parâmetro Buffer .
Para obter mais informações sobre IDs de instância do dispositivo, consulte Cadeias de caracteres de identificação do dispositivo.
Observação
O cabeçalho cfgmgr32.h define CM_Get_Device_ID_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
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de