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 de 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 de IDs (identificadores de instância de dispositivo) do computador ou para NULL. Consulte 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 umNULL
[in] BufferLen
Comprimento fornecido pelo chamador, em caracteres, do buffer especificado por 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 da instância do dispositivo para as relações de barramento da instância do 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 uma classe de instalação dispositivo GUID. 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 for definido, a lista retornada conterá apenas as instâncias de dispositivo que estão presentes no sistema no momento. Esse valor pode ser combinado com outros valores ulFlags
CM_GETIDLIST_FILTER_TRANSPORTRELATIONS (Windows 7 e versões posteriores do Windows)
Se esse sinalizador estiver definido, pszFilter deverá especificar o identificador da instância do dispositivo de um nó de dispositivo composto (de 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 desenvolvimentos compostos e relações de transporte, consulte a seção comentários
CM_GETIDLIST_DONOTGENERATE
Usado somente com CM_GETIDLIST_FILTER_SERVICE. Se definido e se a árvore do dispositivo 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 da instância do dispositivo para as relações de ejeção da instância do 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 é
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 pszFilter fornecer um enumerador e uma ID do dispositivo , a função retornará IDs de instância do dispositivo apenas para as instâncias do dispositivo especificado que está associado 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 do 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 de da instância do 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 do dispositivo não contiver um de 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.
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 prefixados por CR_ definidos em Cfgmgr32.h.
Observações
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 composto devnode. 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 as interfaces do dispositivo aos aplicativos e ao sistema. Quando um aplicativo usa essas interfaces de dispositivo público, o dispositivo composto roteia os dados baseados em pacotes 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 ônibus Bluetooth, cada ônibus enumera um devnode de transporte filho nesse ônibus para representar a conexão física do dispositivo.
Nesse caso, se você definir os sinalizadores de CM_GETIDLIST_FILTER_TRANSPORTRELATIONS em
Para obter mais informações sobre IDs de instância do dispositivo, consulte cadeias de caracteres de identificação do dispositivo.
Nota
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 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 |