estrutura SP_DEVINSTALL_PARAMS_A (setupapi.h)

  • Artigo

Uma estrutura SP_DEVINSTALL_PARAMS contém parâmetros de instalação do dispositivo associados a um elemento de informações de dispositivo específico 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. Os sinalizadores podem 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 de dispositivo , 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. SetupDiSetClassInstallParams define esse sinalizador quando o chamador especifica parâmetros e limpa o sinalizador quando o chamador especifica um ponteiro de parâmetros NULL .

DI_COMPAT_FROM_CLASS

Defina para forçar SetupDiBuildDriverInfoList a criar uma lista de drivers compatíveis de um dispositivo de sua lista de drivers de classe em vez do arquivo INF.

DI_DRIVERPAGE_ADDED

Definido por um instalador de classe ou um co-instalador se o instalador fornecer uma página que substitui a página de propriedades do driver fornecida 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_Ex CM_Setup_DevNodeCM_Setup_DevNode_ExCM_Set_HW_Prof_Flags CM_Set_HW_Prof_Flags_ExCM_Enable_DevNodeCM_Enable_DevNode_ExCM_Disable_DevNode CM_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 for 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 um 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 de dispositivo define esse sinalizador para restringir um usuário à instalação somente do local da mídia de instalação.

DI_NODI_DEFAULTACTION

Defina se SetupDiCallClassInstaller não deve 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 aplicativos e componentes 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ópia. Use a fila de cópia fornecida pelo chamador no SP_DEVINSTALL_PARAMS. FileQueue.

DI_NOWRITE_IDS

Defina para impedir que SetupDiInstallDevice grave as IDs de hardware especificadas pelo INF e as IDs compatíveis nas propriedades do dispositivo para o nó do dispositivo (devnode). Esse sinalizador só deve ser definido para dispositivos enumerados por raiz.

Esse sinalizador substitui o sinalizador DI_FLAGSEX_ALWAYSWRITEIDS.

DI_PROPERTIES_CHANGE

Definido por 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 ser silenciosas e usar 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 um co-instalador se o instalador fornecer uma página que substitui a página de propriedades do recurso fornecida pelo sistema. Se esse sinalizador estiver definido, o sistema operacional não exibirá a página de recursos fornecida pelo sistema.

DI_SHOWOEM

Defina 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á criou 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.

Esse sinalizador é somente leitura. Somente o sistema operacional define esse sinalizador.

DI_DIDCOMPAT

Defina se SetupDiBuildDriverInfoList já criou 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 drivers 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 de dispositivo como um todo.

Esse 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 contiver drivers fornecidos por vários fabricantes.

Esse 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 estã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 do 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 de dispositivo, somente leitura (definido apenas pelo sistema operacional), reservados e obsoletos.

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 incluirá Excluir de Selecionar drivers na lista de drivers solicitada.

Um driver será "Excluir de Selecionar" se estiver marcado como ExcludeFromSelect no arquivo INF ou se for um driver para um dispositivo cuja classe de instalação inteira está marcada como NoInstallClass ou NoUseClass no INF do instalador de classe. Os drivers para dispositivos PnP normalmente são "Excluir da Seleção"; 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 raiz.

DI_FLAGSEX_APPENDDRIVERLIST

Se definido, SetupDiBuildDriverInfoList acrescentará uma nova lista de driver a uma lista existente. Esse sinalizador é relevante ao pesquisar vários locais.

DI_FLAGSEX_DRIVERLIST_FROM_URL

Se definido, crie a lista de driveres de INF(s) recuperados da URL especificada em SP_DEVINSTALL_PARAMS. DriverPath. Se o DriverPath for uma cadeia de caracteres vazia, use o site Windows Update.

Atualmente, o sistema operacional não dá suporte a URLs. Use esse sinalizador para direcionar SetupDiBuildDriverInfoList para pesquisar o 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ê poderá limpar esse sinalizador se estiver apenas recebendo uma lista de drivers atualmente instalados para um dispositivo.

DI_FLAGSEX_FILTERCLASSES

Se definido, SetupDiBuildClassInfoList marcar para 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 drivers de classe. Um driver "semelhante" é aquele para o qual uma das IDs de hardware ou IDs compatíveis no arquivo INF corresponde parcialmente (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 de Finish-Install a ser executada 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 atualmente instalado ao criar uma lista de drivers de classe ou drivers compatíveis com dispositivos.

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 driver 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 AddReg e DelReg para as chaves de hardware e software (driver) do dispositivo. Ou seja, as entradas AddReg e DelReg no arquivo INF DDInstall e DDInstall. Seções HW .

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, Gerenciador de Dispositivos verifica o sinalizador DI_FLAGSEX_PROPCHANGE_PENDING. Se estiver definido, 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 mudou.

DI_FLAGSEX_RECURSIVESEARCH

(Windows Vista e posterior.) Se definido, quando SetupDiBuildDriverInfoList pesquisar INFs no caminho especificado no valor DriverPath , 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 valor do registro ConfigFlags do dispositivo. Se DI_FLAGSEX_SETFAILEDINSTALL estiver definida, 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. Esse sinalizador é somente leitura.

DI_FLAGSEX_DIDCOMPATINFO

O Windows criou uma lista de nós de driver compatíveis com o dispositivo. Esse 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 conjunto ou dispositivo HDEVINFO não tem nenhuma classe associada, a lista incluirá todos os nós de driver de todos os arquivos INF disponíveis. Esse sinalizador é somente leitura.

DI_FLAGSEX_IN_SYSTEM_SETUP

Se definido, a instalação ocorrerá durante a instalação inicial do sistema. Esse 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 será o proprietário das 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 retorno de chamada InstallMsgHandler .

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), deverá 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 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. Apenas para uso interno.

DriverPath[MAX_PATH]

Esse caminho é usado pela função SetupDiBuildDriverInfoList .

Comentários

Observação

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 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
Cabeçalho setupapi.h (inclua Setupapi.h)

Confira também

SetupDiBuildClassInfoList

SetupDiBuildDriverInfoList

SetupDiCallClassInstaller

SetupDiGetDeviceInstallParams

SetupDiInstallDevice

SetupDiSelectDevice

SetupDiSetDeviceInstallParams