DIF_SELECTDEVICE
Uma solicitação de DIF_SELECTDEVICE permite que um instalador participe da seleção do driver de um dispositivo.
Quando enviado
Ao escolher um driver para um dispositivo recém-enumerado ou um novo driver para um dispositivo existente (driver de alteração). Por exemplo, quando um usuário seleciona Adicionar/Remover Hardware e seleciona a classe modem. Ou um usuário insere um dispositivo PnP e seleciona "Escolher um driver de uma lista" no Assistente de Novo Hardware Encontrado.
Quem manipula
Co-instalador de classe |
Pode manipular |
Co-instalador de dispositivo |
Não manipula |
Instalador de Classe |
Pode manipular |
Entrada do instalador
DeviceInfoSet
Fornece um identificador para o conjunto de informações do dispositivo que contém o dispositivo para o qual um driver deve ser selecionado. Há uma classe de configuração de dispositivo associada ao DeviceInfoSet.
DeviceInfoData
Opcionalmente, fornece um ponteiro para uma estrutura SP_DEVINFO_DATA que identifica o dispositivo no conjunto de informações do dispositivo.
Se DeviceInfoData for NULL, essa solicitação será selecionar um driver para a classe de configuração do dispositivo associada ao DeviceInfoSet.
Parâmetros de instalação do dispositivo
Se DeviceInfoData não for NULL, haverá parâmetros de instalação do dispositivo (SP_DEVINSTALL_PARAMS) associados ao DeviceInfoData. Se DeviceInfoData for NULL, haverá parâmetros de instalação do dispositivo associados ao DeviceInfoSet.
De interesse específico é o DriverPath, que contém o local de INF(s) a ser usado ao criar a lista de drivers.
Parâmetros de instalação de classe
Uma estrutura SP_SELECTDEVICE_PARAMS será associada ao DeviceInfoData se DeviceInfoData não for NULL. Caso contrário, os parâmetros de instalação da classe serão associados às informações do dispositivo definidas como um todo.
Saída do instalador
Parâmetros de instalação do dispositivo
Um instalador pode modificar os parâmetros de instalação do dispositivo. No entanto, ele não deve modificar o campo DriverPath .
Parâmetros de instalação de classe
Um instalador pode modificar o SP_SELECTDEVICE_PARAMS. Por exemplo, um instalador pode especificar um título e/ou instruções para o Windows usar na caixa de diálogo que solicita que o usuário selecione um driver.
Se um instalador definir novos parâmetros select-device versus modificar parâmetros definidos por um instalador anterior, o instalador deverá zero os campos que não definir.
Valor retornado do instalador
Se um co-instalador não fizer nada para esse código DIF, ele retornará NO_ERROR de sua passagem de pré-processamento. Se um co-instalador manipular esse código DIF, ele deverá fazer isso em sua passagem de pré-processamento e retornar NO_ERROR ou um código de erro Win32. No momento em que um co-instalador é chamado para pós-processamento, o driver já foi selecionado.
Se um instalador de classe manipular com êxito essa solicitação e SetupDiCallClassInstaller precisar chamar posteriormente o manipulador padrão, o instalador de classe retornará ERROR_DI_DO_DEFAULT.
Se o instalador de classe manipular com êxito essa solicitação, incluindo chamar diretamente o manipulador padrão, o instalador de classe deverá retornar NO_ERROR e SetupDiCallClassInstaller não chamará o manipulador padrão novamente.
Nota O instalador de classe pode chamar diretamente o manipulador padrão, mas o instalador de classe nunca deve tentar substituir as operações do manipulador padrão.
Para obter mais informações sobre como chamar o manipulador padrão, consulte Chamando manipuladores de código DIF padrão.
Se o instalador de classe encontrar um erro, o instalador deverá retornar um código de erro Win32 apropriado e SetupDiCallClassInstaller não chamará posteriormente o manipulador padrão.
Um instalador de classe retornará ERROR_DI_BAD_PATH se o membro DriverPath da estrutura de SP_DEVINSTALL_PARAMS correspondente não for igual a NULL, mas não houver drivers válidos no local do caminho especificado. Isso pode ocorrer se não houver drivers no local do caminho ou se houver drivers, mas o membro Flags da estrutura SP_DRVINSTALL_PARAMS de cada driver foi definido com o sinalizador DN_BAD_DRIVER. Em resposta a esse código de erro, o Windows exibe um erro para o usuário.
Manipulador de código DIF padrão
Operação do instalador
Em resposta a uma solicitação de DIF_SELECTDEVICE, um instalador executa todas as operações de seleção necessárias para seu dispositivo ou classe de dispositivo, além do que o manipulador padrão faz. Um instalador normalmente responde a essa solicitação DIF de uma das seguintes maneiras:
Não fazer nada.
Se um instalador não tiver requisitos especiais de seleção, ele não fará nada em resposta a esse código DIF. Um instalador de classe retorna ERROR_DI_DO_DEFAULT e um coinstalador retorna NO_ERROR.
Forneça cadeias de caracteres selecionadas que o Windows exibirá na interface do usuário de seleção.
Um instalador pode fornecer cadeias de caracteres selecionadas nos parâmetros de instalação da classe (SP_SELECTDEVICE_PARAMS). Por exemplo, um instalador pode modificar as Instruções ou o título do cabeçalho da janela.
Um instalador de classe não deverá fornecer cadeias de caracteres selecionadas se um co-instalador já tiver fornecido cadeias de caracteres selecionadas. O co-instalador provavelmente tem informações mais relevantes.
Se um instalador modificar o SP_SELECTDEVICE_PARAMS, o instalador também deverá definir o sinalizador DI_USECI_SELECTSTRINGS no SP_DEVINSTALL_PARAMS.
Se um instalador fornecer cadeias de caracteres selecionadas com êxito, o Windows ainda precisará chamar o manipulador padrão. Portanto, nesse caso, um co-instalador retorna NO_ERROR e um instalador de classe retorna ERROR_DI_DO_DEFAULT.
Modifique os parâmetros de instalação do dispositivo.
Um instalador pode modificar os parâmetros de instalação do dispositivo (SP_DEVINSTALL_PARAMS). Por exemplo, um instalador pode definir o sinalizador DI_SHOWOEM para que o Windows exiba o botão Ter Disco .
Se um instalador de classe modificar com êxito os parâmetros de instalação do dispositivo, o instalador de classe retornará ERROR_DI_DO_DEFAULT.
Modifique a lista de drivers dos quais o usuário pode selecionar.
Essa ação é menos comum, mas possível. Um instalador que modifica a lista de driver pode, ou não, fornecer cadeias de caracteres selecionadas.
Um instalador que modifica a lista de drivers normalmente marca os drivers inadequados para o dispositivo. Um instalador marca esses drivers com o sinalizador DNF_BAD_DRIVER. O Windows omite esses drivers da lista exibida para o usuário.
Um instalador marca drivers inválidos seguindo estas etapas:
- Crie a lista de drivers chamando SetupDiBuildDriverInfoList com um DriverType de SPDIT_CLASSDRIVER.
- Obtenha as informações sobre o primeiro driver na lista chamando SetupDiEnumDriverInfo e SetupDiGetDriverInstallParams. Se o driver não for apropriado para o dispositivo, defina o sinalizador DNF_BAD_DRIVER no campo Sinalizadores dos parâmetros. Aplique a alteração aos parâmetros chamando SetupDiSetDriverInstallParams.
- Repita a etapa anterior até que você tenha processado todos os drivers na lista. Certifique-se de incrementar o parâmetro MemberIndex para SetupDiEnumDriverInfo , conforme descrito na página de referência dessa função.
Um instalador pode definir o sinalizador DNF_BAD_DRIVER para um ou mais drivers na lista de drivers, mas um instalador não deve limpar esse sinalizador.
Se um ou mais instaladores modificarem com êxito a lista de drivers, o Windows ainda precisará chamar o manipulador padrão. Portanto, nesse caso, um co-instalador retorna NO_ERROR e um instalador de classe retorna ERROR_DI_DO_DEFAULT.
Exiba sua própria interface do usuário de seleção de driver e defina o driver selecionado.
Somente um instalador de classe pode exibir sua própria interface do usuário de seleção de driver; os co-instaladores não devem. Por exemplo, um instalador de classe pode exibir imagens em vez de listas textuais.
Se o instalador de classe definir com êxito o driver selecionado, o instalador de classe retornará NO_ERROR e o Windows não chamará o manipulador padrão e, portanto, não exibirá a interface de seleção padrão.
Se o sinalizador DI_ENUMSINGLEINF estiver definido nos parâmetros de instalação do dispositivo, o DriverPath será um caminho de um único arquivo INF em vez de um caminho de um diretório. Um instalador deve usar apenas esse ÚNICO INF para criar a lista de drivers.
Para obter mais informações sobre códigos DIF, consulte Manipulando códigos DIF.
Requisitos
Versão |
Com suporte no Microsoft Windows 2000 e versões posteriores do Windows. |
Cabeçalho |
Setupapi.h (inclua Setupapi.h) |
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