Interfaccia del co-programma di installazione

L'interfaccia di un co-programma di installazione è costituita da una funzione del punto di ingresso esportato e da una struttura di dati associata.

Punto di ingresso del co-programma di installazione

Un co-programma di installazione deve esportare una funzione del punto di ingresso con il prototipo seguente:

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
Specifica la richiesta di installazione del dispositivo in fase di elaborazione, in cui il co-programma di installazione ha la possibilità di partecipare. Queste richieste vengono specificate usando codici DIF, ad esempio DIF_INSTALLDEVICE. Per altre informazioni, vedere Codici di funzione di installazione del dispositivo.

DeviceInfoSet
Fornisce un handle a un set di informazioni sul dispositivo.

DeviceInfoData
Facoltativamente, identifica un dispositivo che rappresenta la destinazione della richiesta di installazione del dispositivo. Se questo parametro è diverso da NULL, identifica un elemento informazioni sul dispositivo nel set di informazioni sul dispositivo. DeviceInfoData è diverso da NULL quando SetupDiCallClassInstaller chiama un coinstallatore specifico del dispositivo. Un co-programma di installazione specifico della classe può essere chiamato con una richiesta DIF con nullDeviceInfoData, ad esempio DIF_DETECT o DIF_FIRSTTIMESETUP.

Contesto
Punta a una struttura COINSTALLER_CONTEXT_DATA .

Un co-programma di installazione del dispositivo restituisce uno dei valori seguenti:

NO_ERROR
Il co-programma di installazione ha eseguito le azioni appropriate per l'oggetto InstallFunction specificato o il co-programma di installazione ha determinato che non è necessario eseguire alcuna azione per la richiesta.

Il co-programma di installazione deve restituire anche NO_ERROR se riceve un codice DIF non riconosciuto. Si noti che i programmi di installazione della classe restituiscono ERROR_DI_DO_DEFAULT per i codici DIF non riconosciuti.

ERROR_DI_POSTPROCESSING_REQUIRED
Il co-programma di installazione ha eseguito tutte le azioni appropriate per l'oggetto InstallFunction specificato e richiede di essere chiamato nuovamente dopo che il programma di installazione classi ha elaborato la richiesta.

Errore Win32
Il co-programma di installazione ha rilevato un errore.

Un co-programma di installazione non imposta lo stato restituito di ERROR_DI_DO_DEFAULT. Questo stato può essere usato solo da un programma di installazione classi. Se un programma di installazione condivisa restituisce questo stato, SetupDiCallClassInstaller non elabora correttamente la richiesta DIF_Xxx . Un co-programma di installazione potrebbe propagare uno stato restituito di ERROR_DI_DO_DEFAULT nel passaggio di post-elaborazione, ma non imposta mai questo valore.

COINSTALLER_CONTEXT_DATA

COINSTALLER_CONTEXT_DATA è una struttura di contesto specifica del programma di installazione che descrive una richiesta di installazione. Il formato della struttura è:

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

Nell'elenco seguente vengono descritti i membri di questa struttura:

• PostProcessing è TRUE quando viene chiamato un co-programma di installazione dopo il programma di installazione della classe appropriato, se presente, ha elaborato il codice DIF specificato da InstallFunction. PostProcessing è di sola lettura per il co-programma di installazione.

• Se PostProcessing è FALSE, InstallResult non è rilevante. Se PostProcessing è TRUE, InstallResult è lo stato corrente della richiesta di installazione. Questo valore è NO_ERROR o uno stato di errore restituito dal componente precedente chiamato per questa richiesta di installazione. Un co-programma di installazione può propagare lo stato restituendo questo valore per la relativa funzione restituita oppure può restituire un altro stato. InstallResult è di sola lettura nel co-programma di installazione.

• PrivateData punta a un buffer allocato dal co-programma di installazione. Se un programma di installazione condivisa imposta questo puntatore e richiede la post-elaborazione, SetupDiCallClassInstaller passa il puntatore al co-programma di installazione quando chiama il co-programma di installazione per la post-elaborazione.