Função SwDeviceCreate (swdevice.h)
Inicia a enumeração de um dispositivo de software.
Sintaxe
HRESULT SwDeviceCreate(
[in] PCWSTR pszEnumeratorName,
[in] PCWSTR pszParentDeviceInstance,
[in] const SW_DEVICE_CREATE_INFO *pCreateInfo,
[in] ULONG cPropertyCount,
[in, optional] const DEVPROPERTY *pProperties,
[in] SW_DEVICE_CREATE_CALLBACK pCallback,
[in, optional] PVOID pContext,
[out] PHSWDEVICE phSwDevice
);
Parâmetros
[in] pszEnumeratorName
Uma cadeia de caracteres que nomeia o enumerador do dispositivo de software. Escolha um nome que represente o componente que enumera os dispositivos.
[in] pszParentDeviceInstance
Uma cadeia de caracteres que especifica a ID da instância do dispositivo que é o pai do dispositivo de software.
Isso pode ser HTREE\ROOT\0, mas é recomendável manter os filhos do dispositivo raiz no mínimo. Também recomendamos que o pai preferencial de um dispositivo de software seja um dispositivo real para o qual o dispositivo de software está estendendo a funcionalidade. Em situações em que um dispositivo de software não tem um pai tão natural, crie um dispositivo como um filho da raiz que possa coletar todos os dispositivos de software que um componente enumerará; em seguida, enumere os dispositivos de software reais como filhos desse nó de agrupamento de dispositivos. Isso mantém os filhos do dispositivo raiz em um número gerenciável.
[in] pCreateInfo
Um ponteiro para uma estrutura SW_DEVICE_CREATE_INFO que descreve as informações que o PnP usa para criar o dispositivo.
[in] cPropertyCount
O número de estruturas DEVPROPERTY na matriz pProperties .
[in, optional] pProperties
Uma matriz opcional de estruturas DEVPROPERTY . Essas propriedades são definidas no dispositivo depois que ele é criado, mas antes que uma notificação de que o dispositivo foi criado seja enviada. Para obter mais informações, consulte Comentários. Esse ponteiro pode ser NULL.
[in] pCallback
O SW_DEVICE_CREATE_CALLBACK função de retorno de chamada que o sistema operacional chama depois que o PnP enumera o dispositivo.
[in, optional] pContext
Um contexto de cliente opcional que o sistema operacional passa para a função de retorno de chamada. Esse ponteiro pode ser NULL.
[out] phSwDevice
Um ponteiro para uma variável que recebe o identificador HSWDEVICE que representa o dispositivo. Chame SwDeviceClose para fechar esse identificador depois que o aplicativo cliente quiser que o PnP remova o dispositivo.
DECLARE_HANDLE(HSWDEVICE);
typedef HSWDEVICE *PHSWDEVICE;
Retornar valor
S_OK será retornado se a enumeração do dispositivo tiver sido iniciada com êxito. Isso não significa que o dispositivo foi enumerado com êxito. Verifique o parâmetro CreateResult da função de retorno de chamada SW_DEVICE_CREATE_CALLBACK para determinar se o dispositivo foi enumerado com êxito.
Comentários
SwDeviceCreate retorna um identificador que representa o dispositivo. Depois que esse identificador for fechado, o PnP removerá o dispositivo.
O processo de chamada deve ter acesso de Administrador para iniciar a enumeração de um dispositivo de software.
O PnP forma a ID da instância do dispositivo de um dispositivo de software como "SWD< pszEnumeratorName>< pszInstanceId>", mas essa cadeia de caracteres pode mudar ou pnP pode decorar o nome. Sempre obtenha a ID da instância do dispositivo da função de retorno de chamada.
Há uma diferença sutil entre as propriedades que são definidas como parte de uma chamada SwDeviceCreate e propriedades que são definidas posteriormente chamando SwDevicePropertySet. As propriedades definidas como parte de SwDeviceCreate são armazenadas na memória; se o dispositivo estiver desinstalado ou um driver nulo apagar os repositórios de propriedades, essas propriedades serão gravadas novamente pelo recurso de API de Dispositivo de Software quando o PnP renumerar os dispositivos. Tudo isso é transparente para o cliente. As propriedades definidas usando SwDevicePropertySet após a enumeração não persistem na memória. Mas, se você definir uma propriedade usando SwDeviceCreate, poderá atualizar o valor com SwDevicePropertySet e essa atualização será aplicada ao valor na memória, bem como ao repositório persistente.
Recomendamos que todas as propriedades sejam especificadas como parte da chamada para SwDeviceCreate quando possível e que essas propriedades sejam especificadas para cada chamada para SwDeviceCreate.
Requisitos
| Requisito | Valor |
|---|---|
| Cliente mínimo com suporte | Windows 8 |
| Servidor mínimo com suporte | Windows Server 2012 |
| Plataforma de Destino | Universal |
| Cabeçalho | swdevice.h |
| Biblioteca | Swdevice.lib; OneCoreUAP.lib no Windows 10 |
| DLL | Cfgmgr32.dll |