SP_DEVINSTALL_PARAMS_A estrutura (setupapi.h)
Uma estrutura SP_DEVINSTALL_PARAMS contém parâmetros de instalação do dispositivo associados a um determinado elemento de informações do dispositivo ou associado globalmente a um conjunto de informações do dispositivo.
Sintaxe
typedef struct _SP_DEVINSTALL_PARAMS_A {
DWORD cbSize;
DWORD Flags;
DWORD FlagsEx;
HWND hwndParent;
PSP_FILE_CALLBACK InstallMsgHandler;
PVOID InstallMsgHandlerContext;
HSPFILEQ FileQueue;
ULONG_PTR ClassInstallReserved;
DWORD Reserved;
CHAR DriverPath[MAX_PATH];
} SP_DEVINSTALL_PARAMS_A, *PSP_DEVINSTALL_PARAMS_A;
Membros
cbSize
O tamanho, em bytes, da estrutura SP_DEVINSTALL_PARAMS.
Flags
Sinalizadores que controlam a instalação e as operações de interface do usuário. Alguns sinalizadores podem ser definidos antes de enviar a solicitação de instalação do dispositivo, enquanto outros sinalizadores são definidos automaticamente durante o processamento de algumas solicitações. Flags pode ser uma combinação dos valores a seguir.
Os valores de sinalizador são listados em grupos: graváveis por aplicativos de instalação de dispositivo e instaladores, somente leitura (definidos apenas pelo sistema operacional), reservados e obsoletos. O primeiro grupo lista os sinalizadores graváveis:
DI_CLASSINSTALLPARAMS
Defina para usar os parâmetros de Instalação de Classe.
DI_COMPAT_FROM_CLASS
Defina para forçar SetupDiBuildDriverInfoList para criar uma lista de drivers compatíveis de um dispositivo de sua lista de driveres de classe em vez do arquivo INF.
DI_DRIVERPAGE_ADDED
Definido por um instalador de classe ou co-instalador se o instalador fornecer uma página que substitua a página de propriedades de driver fornecidas pelo sistema. Se esse sinalizador estiver definido, o sistema operacional não exibirá a página de driver fornecida pelo sistema.
DI_DONOTCALLCONFIGMG
Defina se o gerenciador de configurações não deve ser chamado para remover ou reenumerar dispositivos durante a execução de determinadas funções de instalação do dispositivo (por exemplo, SetupDiInstallDevice).
Se esse sinalizador estiver definido, os aplicativos de instalação do dispositivo, os instaladores de classe e os co-instaladores não deverão chamar as seguintes funções:
CM_Reenumerate_DevNodeCM_Reenumerate_DevNode_ExCM_Query_And_Remove_SubTreeCM_Query_And_Remove_SubTree_ExCM_Setup_DevNodeCM_Setup_DevNode_ExCM_Set_HW_Prof_FlagsCM_Set_HW_Prof_Flags_ExCM_Enable_DevNodeCM_Enable_DevNode_ExCM_Disable_DevNodeCM_Disable_DevNode_Ex
DI_ENUMSINGLEINF
Defina se os instaladores e outros componentes de instalação do dispositivo só devem pesquisar o arquivo INF especificado por SP_DEVINSTALL_PARAMS.DriverPath. Se esse sinalizador estiver definido, driverpath conterá o caminho de um único arquivo INF em vez de um caminho de um diretório.
DI_INF_IS_SORTED
Defina para indicar que a página Selecionar Dispositivo deve listar drivers na ordem em que eles aparecem no arquivo INF, em vez de classificá-los em ordem alfabética.
DI_INSTALLDISABLED
Defina se o dispositivo deve ser instalado em um estado desabilitado por padrão. Para ser reconhecido, esse sinalizador deve ser definido antes que o Windows chame o manipulador padrão para a solicitação de DIF_INSTALLDEVICE.
DI_NEEDREBOOT
Para sistemas operacionais baseados em NT, esse sinalizador será definido se o dispositivo exigir que o computador seja reiniciado após a instalação do dispositivo ou uma alteração de estado do dispositivo. Um instalador de classe ou co-instalador pode definir esse sinalizador a qualquer momento durante a instalação do dispositivo, se o instalador determinar que uma reinicialização é necessária.
DI_NEEDRESTART
O mesmo que DI_NEEDREBOOT.
DI_NOBROWSE
Defina para desabilitar a navegação quando o usuário estiver selecionando um caminho de disco OEM. Um aplicativo de instalação do dispositivo define esse sinalizador para restringir um usuário à instalação somente do local de mídia de instalação.
DI_NODI_DEFAULTACTION
Defina se SetupDiCallClassInstaller não deverá executar nenhuma ação padrão se o instalador de classe retornar ERR_DI_DO_DEFAULT ou se não houver um instalador de classe.
DI_NOFILECOPY
Defina se os componentes e aplicativos de instalação do dispositivo, como SetupDiInstallDevice, devem ignorar a cópia de arquivo.
DI_NOVCP
Defina para desabilitar a criação de uma nova fila de cópias. Use a fila de cópia fornecida pelo chamador no SP_DEVINSTALL_PARAMS.FileQueue.
DI_NOWRITE_IDS
Definido para impedir SetupDiInstallDevice de gravar as IDs de hardware especificadas pelo INF e IDs compatíveis para as propriedades do dispositivo para o nó do dispositivo (de devnode). Esse sinalizador só deve ser definido para dispositivos enumerados por raiz.
Esse sinalizador substitui o sinalizador DI_FLAGSEX_ALWAYSWRITEIDS.
DI_PROPERTIES_CHANGE
Definido pelo Gerenciador de Dispositivos se as propriedades de um dispositivo foram alteradas, o que requer uma atualização da interface do usuário do instalador.
DI_QUIETINSTALL
Defina se as funções do instalador do dispositivo devem ficar silenciosas e usar as opções padrão sempre que possível. Os instaladores de classe e os co-instaladores não deverão exibir nenhuma interface do usuário se esse sinalizador estiver definido.
DI_RESOURCEPAGE_ADDED
Definido por um instalador de classe ou co-instalador se o instalador fornecer uma página que substitua a página de propriedades de recurso fornecidas pelo sistema. Se esse sinalizador estiver definido, o sistema operacional não exibirá a página de recursos fornecida pelo sistema.
DI_SHOWOEM
Definido para permitir o suporte para discos OEM. Se esse sinalizador estiver definido, o sistema operacional apresentará um botão "Ter Disco" na página Selecionar Dispositivo. Esse sinalizador é definido, por padrão, em assistentes fornecidos pelo sistema.
DI_USECI_SELECTSTRINGS
Defina se um instalador de classe ou co-instalador forneceu cadeias de caracteres que devem ser usadas durante SetupDiSelectDevice.
Os sinalizadores a seguir são somente leitura (definidos apenas pelo sistema operacional):
DI_DIDCLASS
Defina se SetupDiBuildDriverInfoList já tiver criado uma lista dos drivers para essa classe de dispositivo. Se essa lista já tiver sido criada, ela conterá todas as informações do driver e esse sinalizador sempre será definido. SetupDiDestroyDriverInfoList limpa esse sinalizador quando exclui uma lista de drivers para uma classe.
Este sinalizador é somente leitura. Somente o sistema operacional define esse sinalizador.
DI_DIDCOMPAT
Defina se SetupDiBuildDriverInfoList já tiver criado uma lista de drivers compatíveis para este dispositivo. Se essa lista já tiver sido criada, ela conterá todas as informações do driver e esse sinalizador sempre será definido. SetupDiDestroyDriverInfoList limpa esse sinalizador quando exclui uma lista de driver compatível.
Esse sinalizador só é definido em parâmetros de instalação do dispositivo associados a um elemento de informações de dispositivo específico, não em parâmetros para um conjunto de informações do dispositivo como um todo.
Este sinalizador é somente leitura. Somente o sistema operacional define esse sinalizador.
DI_MULTMFGS
Definido por SetupDiBuildDriverInfoList se uma lista de drivers para uma classe de configuração de dispositivo contém drivers fornecidos por vários fabricantes.
Este sinalizador é somente leitura. Somente o sistema operacional define esse sinalizador.
Os seguintes sinalizadores são reservados:
DI_AUTOASSIGNRES
DI_DISABLED
DI_FORCECOPY
DI_GENERALPAGE_ADDED
DI_OVERRIDE_INFFLAGS
DI_SHOWALL
DI_SHOWCLASS
DI_SHOWCOMPAT
Os seguintes sinalizadores são obsoletos:
DI_NOSELECTICONS
DI_PROPS_NOCHANGEUSAGE
FlagsEx
Sinalizadores adicionais que fornecem controle sobre operações de instalação e interface do usuário. Alguns sinalizadores podem ser definidos antes de chamar as funções do instalador de dispositivo, enquanto outros sinalizadores são definidos automaticamente durante o processamento de algumas funções. FlagsEx pode ser uma combinação dos valores a seguir.
Os valores de sinalizador são listados em grupos: graváveis por aplicativos e instaladores de instalação do dispositivo, somente leitura (definido apenas pelo sistema operacional), reservado e obsoleto.
O primeiro grupo lista os sinalizadores graváveis:
DI_FLAGSEX_ALLOWEXCLUDEDDRVS
Se definido, inclua drivers marcados como "Excluir de Selecionar".
Por exemplo, se esse sinalizador estiver definido, SetupDiSelectDevice exibirá drivers que têm o estado Excluir de Selecionar e SetupDiBuildDriverInfoList inclui excluir de selecionar drivers na lista de drivers solicitados.
Um driver será "Excluir de Selecionar" se estiver marcado ExcludeFromSelect no arquivo INF ou for um driver para um dispositivo cuja classe de instalação inteira está marcada NoInstallClass ou NoUseClass no INF do instalador de classe. Os drivers para dispositivos PnP normalmente são "Excluir de Selecionar"; Os dispositivos PnP não devem ser instalados manualmente. Para criar uma lista de arquivos de driver para um dispositivo PnP, um chamador de SetupDiBuildDriverInfoList deve definir esse sinalizador.
DI_FLAGSEX_ALWAYSWRITEIDS
Se definido e o sinalizador DI_NOWRITE_IDS estiver claro, sempre escreva hardware e IDs compatíveis nas propriedades do dispositivo para o devnode. Esse sinalizador só deve ser definido para dispositivos enumerados por raiz.
DI_FLAGSEX_APPENDDRIVERLIST
Se definido, SetupDiBuildDriverInfoList acrescenta uma nova lista de driver a uma lista existente. Esse sinalizador é relevante ao pesquisar vários locais.
DI_FLAGSEX_DRIVERLIST_FROM_URL
Se definido, compile a lista de drivers de INF(s) recuperada da URL especificada em SP_DEVINSTALL_PARAMS.DriverPath. Se o DriverPath for uma cadeia de caracteres vazia, use o site do Windows Update.
Atualmente, o sistema operacional não dá suporte a URLs. Use esse sinalizador para direcionar SetupDiBuildDriverInfoList para pesquisar no site do Windows Update.
Não defina esse sinalizador se DI_QUIETINSTALL estiver definido.
DI_FLAGSEX_EXCLUDE_OLD_INET_DRIVERS
Se definido, não inclua drivers de Internet antigos ao criar uma lista de drivers. Esse sinalizador deve ser definido sempre que você estiver criando uma lista de possíveis drivers para um dispositivo. Você pode limpar esse sinalizador se estiver apenas recebendo uma lista de drivers atualmente instalados para um dispositivo.
DI_FLAGSEX_FILTERCLASSES
Se definido, SetupDiBuildClassInfoList verificará se há filtros de inclusão de classe. Isso significa que um dispositivo não será incluído na lista de classes se sua classe estiver marcada como NoInstallClass.
DI_FLAGSEX_FILTERSIMILARDRIVERS
(Windows XP e posterior.) Se definido, SetupDiBuildDriverInfoList inclui drivers "semelhantes" ao criar uma lista de driver de classe. Um driver "semelhante" é aquele para o qual uma das IDs de hardware ou IDs compatíveis no arquivo INF corresponde parcial (ou completamente) a uma das IDs de hardware ou IDs compatíveis do hardware.
DI_FLAGSEX_FINISHINSTALL_ACTION
(Windows Vista e posterior.) Consulte Marcando um dispositivo como tendo uma ação Finish-Install para executar para obter mais informações.
DI_FLAGSEX_INET_DRIVER
Se definido, o driver foi obtido da Internet. O Windows não usará o INF do dispositivo para instalar dispositivos futuros porque o Windows não pode garantir que ele possa recuperar os arquivos de driver novamente da Internet.
DI_FLAGSEX_INSTALLEDDRIVER
(Windows XP e posterior.) Se definido, SetupDiBuildDriverInfoList inclui apenas o driver instalado no momento ao criar uma lista de drivers de classe ou drivers compatíveis com o dispositivo.
DI_FLAGSEX_NO_CLASSLIST_NODE_MERGE
(Windows XP e posterior.) Se definido, ao criar uma lista de drivers de classe, SetupDiBuildDriverInfoList não mesclará nós na lista de drivers que são do mesmo INF e têm a mesma descrição e classificação do driver.
DI_FLAGSEX_NO_DRVREG_MODIFY
Não processe as entradas
DI_FLAGSEX_POWERPAGE_ADDED
Se definido, um instalador adicionou sua própria página para a caixa de diálogo propriedades de energia. O sistema operacional não exibirá a página de propriedades de energia fornecidas pelo sistema. Esse sinalizador só será relevante se o dispositivo der suporte ao gerenciamento de energia.
DI_FLAGSEX_PROPCHANGE_PENDING
Se definido, o usuário fez alterações em uma ou mais folhas de propriedades do dispositivo. O provedor de página de propriedades normalmente define esse sinalizador.
Quando o usuário fecha a folha de propriedades do dispositivo, o Gerenciador de Dispositivos verifica o sinalizador DI_FLAGSEX_PROPCHANGE_PENDING. Se estiver definido, o Gerenciador de Dispositivos limpará esse sinalizador, definirá o sinalizador DI_PROPERTIES_CHANGE e enviará uma solicitação DIF_PROPERTYCHANGE aos instaladores para notificá-los de que algo foi alterado.
DI_FLAGSEX_RECURSIVESEARCH
(Windows Vista e posterior.) Se definido, quando SetupDiBuildDriverInfoList pesquisa infs no caminho especificado no driverpath valor, a pesquisa será recursiva.
DI_FLAGSEX_SEARCH_PUBLISHED_INFS
(Windows Vista e posterior.) Se definido, quando SetupDiBuildDriverInfoList é usado para pesquisar INFs sem um caminho INF ou caminho de pesquisa especificado, isso restringe a pesquisa apenas a INFs que foram importados para o Repositório de Driver.
DI_FLAGSEX_SETFAILEDINSTALL
Defina se a instalação falhou. Se esse sinalizador estiver definido, a função SetupDiInstallDevice apenas definirá o sinalizador FAILEDINSTALL no ConfigFlags do dispositivo valor do registro. Se DI_FLAGSEX_SETFAILEDINSTALL estiver definido, os co-instaladores deverão retornar NO_ERROR em resposta a DIF_INSTALLDEVICE, enquanto os instaladores de classe deverão retornar NO_ERROR ou ERROR_DI_DO_DEFAULT.
DI_FLAGSEX_USECLASSFORCOMPAT
Filtre arquivos INF na classe de instalação do dispositivo ao criar uma lista de drivers compatíveis. Se a classe de instalação de um dispositivo for conhecida, definir esse sinalizador reduzirá o tempo necessário para criar uma lista de drivers compatíveis ao pesquisar arquivos INF que não são pré-compilados. Esse sinalizador será ignorado se DI_COMPAT_FROM_CLASS estiver definido.
Os sinalizadores a seguir são somente leitura; somente o sistema operacional define estes sinalizadores:
DI_FLAGSEX_CI_FAILED
Definido pelo sistema operacional se um instalador de classe não tiver sido carregado ou iniciado. Este sinalizador é somente leitura.
DI_FLAGSEX_DIDCOMPATINFO
O Windows criou uma lista de nós de driver compatíveis com o dispositivo. Este sinalizador é somente leitura.
DI_FLAGSEX_DIDINFOLIST
O Windows criou uma lista de nós de driver que inclui todos os drivers listados nos arquivos INF da classe de instalação especificada. Se a classe de instalação especificada for NULL porque o dispositivo ou conjunto HDEVINFO não tem nenhuma classe associada, a lista inclui todos os nós de driver de todos os arquivos INF disponíveis. Este sinalizador é somente leitura.
DI_FLAGSEX_IN_SYSTEM_SETUP
Se definido, a instalação ocorrerá durante a instalação inicial do sistema. Este sinalizador é somente leitura.
Os seguintes sinalizadores são reservados e não devem ser usados:
DI_FLAGSEX_ALTPLATFORM_DRVSEARCH
DI_FLAGSEX_BACKUPONREPLACE
DI_FLAGSEX_DEVICECHANGE
DI_FLAGSEX_OLDINF_IN_CLASSLIST
DI_FLAGSEX_PREINSTALLBACKUP
DI_FLAGSEX_RESTART_DEVICE_ONLY
DI_FLAGSEX_USEOLDINFSEARCH
Os seguintes sinalizadores são obsoletos:
DI_FLAGSEX_AUTOSELECTRANK0
DI_FLAGSEX_NOUIONQUERYREMOVE
hwndParent
Identificador de janela que terá as caixas de diálogo da interface do usuário relacionadas a este dispositivo.
InstallMsgHandler
Retorno de chamada usado para manipular eventos durante a cópia de arquivo. Um instalador pode usar um retorno de chamada, por exemplo, para executar um processamento especial ao confirmar uma fila de arquivos.
InstallMsgHandlerContext
Dados privados usados pelo InstallMsgHandler retorno de chamada.
FileQueue
Um identificador para uma fila de arquivos fornecida pelo chamador em que as operações de arquivo devem ser enfileiradas, mas não confirmadas.
Se você associar uma fila de arquivos a um conjunto de informações do dispositivo (SetupDiSetDeviceInstallParams), será necessário desassociar a fila do conjunto de informações do dispositivo antes de excluir o conjunto de informações do dispositivo. Se você não conseguir desassociar a fila de arquivos, o Windows não poderá diminuir sua contagem de referência no conjunto de informações do dispositivo e não poderá liberar a memória.
Essa fila só será usada se o sinalizador de DI_NOVCP estiver definido, indicando que as operações de arquivo devem ser enfileiradas, mas não confirmadas.
ClassInstallReserved
Um ponteiro para dados do instalador de classe. Os co-instaladores não devem usar esse campo.
Reserved
Reservado. Somente para uso interno.
DriverPath[MAX_PATH]
Esse caminho é usado pela função
Observações
Nota
O cabeçalho setupapi.h define SP_DEVINSTALL_PARAMS 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 |
|---|---|
| cabeçalho | setupapi.h (inclua Setupapi.h) |
Consulte também
SetupDiBuildClassInfoList
setupDiInstallDevice