Interface do co-instalador

A interface de um co-instalador consiste em uma função de ponto de entrada exportada e uma estrutura de dados associada.

Ponto de entrada do co-instalador

Um co-instalador deve exportar uma função de ponto de entrada que tenha o seguinte protótipo:

typedef DWORD 
  (CALLBACK* COINSTALLER_PROC) (
    IN DI_FUNCTION  InstallFunction,
    IN HDEVINFO  DeviceInfoSet,
    IN PSP_DEVINFO_DATA  DeviceInfoData  OPTIONAL,
    IN OUT PCOINSTALLER_CONTEXT_DATA  Context
    );

InstallFunction
Especifica a solicitação de instalação do dispositivo que está sendo processada, na qual o co-instalador tem a opção de participar. Essas solicitações são especificadas usando códigos DIF, como DIF_INSTALLDEVICE. Para obter mais informações, consulte Códigos de função de instalação do dispositivo.

DeviceInfoSet
Fornece um identificador para um conjunto de informações do dispositivo.

DeviceInfoData
Opcionalmente, identifica um dispositivo que é o destino da solicitação de instalação do dispositivo. Se esse parâmetro não for NULL, ele identificará um elemento de informações do dispositivo no conjunto de informações do dispositivo. DeviceInfoData não é NULL quando SetupDiCallClassInstaller chama um co-instalador específico do dispositivo. Um co-instalador específico da classe pode ser chamado com uma solicitação DIF que tem um DeviceInfoDataNULL, como DIF_DETECT ou DIF_FIRSTTIMESETUP.

Contexto
Aponta para uma estrutura COINSTALLER_CONTEXT_DATA .

Um co-instalador de dispositivo retorna um dos seguintes valores:

NO_ERROR
O co-instalador executou as ações apropriadas para o InstallFunction especificado ou o co-instalador determinou que não precisava executar nenhuma ação para a solicitação.

O coinstalador também deverá retornar NO_ERROR se receber um código DIF não reconhecido. (Observe que os instaladores de classe retornam ERROR_DI_DO_DEFAULT para códigos DIF não reconhecidos.)

ERROR_DI_POSTPROCESSING_REQUIRED
O co-instalador executou todas as ações apropriadas para o InstallFunction especificado e está solicitando que seja chamado novamente depois que o Instalador de Classe tiver processado a solicitação.

Um erro win32
O co-instalador encontrou um erro.

Um co-instalador não define um status de retorno de ERROR_DI_DO_DEFAULT. Esse status só pode ser usado por um Instalador de Classe. Se um co-instalador retornar esse status, SetupDiCallClassInstaller não processará a solicitação DIF_Xxx corretamente. Um co-instalador pode propagar um status de retorno de ERROR_DI_DO_DEFAULT em sua passagem de pós-processamento, mas nunca define esse valor.

COINSTALLER_CONTEXT_DATA

COINSTALLER_CONTEXT_DATA é uma estrutura de contexto específica do coinstalador que descreve uma solicitação de instalação. O formato da estrutura é:

typedef struct 
  _COINSTALLER_CONTEXT_DATA {
      BOOLEAN  PostProcessing;
      DWORD    InstallResult;
      PVOID    PrivateData;
  } COINSTALLER_CONTEXT_DATA, *PCOINSTALLER_CONTEXT_DATA;

A lista a seguir descreve os membros dessa estrutura:

• O PostProcessing é TRUE quando um co-instalador é chamado após o instalador de classe apropriado, se houver, ter processado o código DIF especificado por InstallFunction. O PostProcessing é somente leitura para o co-instalador.

• Se PostProcessing for FALSE, InstallResult não será relevante. Se PostProcessing for TRUE, InstallResult será o status atual da solicitação de instalação. Esse valor é NO_ERROR ou um status de erro retornado pelo componente anterior chamado para essa solicitação de instalação. Um co-instalador pode propagar o status retornando esse valor para seu retorno de função ou pode retornar outro status. InstallResult é somente leitura para o co-instalador.

• PrivateData aponta para um buffer alocado pelo co-instalador. Se um co-instalador definir esse ponteiro e solicitar o pós-processamento, SetupDiCallClassInstaller passará o ponteiro para o co-instalador ao chamar o co-instalador para pós-processamento.