Interface de co-programme d’installation

Notes

Les fonctionnalités décrites dans cette section ne sont pas prises en charge et les packages de pilotes qui les contiennent ne recevront plus de signature Microsoft. Consultez Utilisation d’un fichier INF universel.

L’interface d’un co-programme d’installation se compose d’une fonction de point d’entrée exportée et d’une structure de données associée.

Point d’entrée du co-programme d’installation

Un co-programme d’installation doit exporter une fonction de point d’entrée qui a le prototype suivant :

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
Spécifie la demande d’installation de l’appareil en cours de traitement, à laquelle le co-programme d’installation a la possibilité de participer. Ces demandes sont spécifiées à l’aide de codes DIF, tels que DIF_INSTALLDEVICE. Pour plus d’informations, consultez Codes de fonction d’installation d’appareil.

DeviceInfoSet
Fournit un handle à un jeu d’informations d’appareil.

DeviceInfoData
Identifie éventuellement un appareil qui est la cible de la demande d’installation de l’appareil. Si ce paramètre n’est pas NULL, il identifie un élément d’informations sur l’appareil dans le jeu d’informations de l’appareil. DeviceInfoData n’a pas la valeur NULL lorsque SetupDiCallClassInstaller appelle un co-programme d’installation spécifique à l’appareil. Un co-programme d’installation spécifique à une classe peut être appelé avec une requête DIF qui a un DeviceInfoDataNULL, comme DIF_DETECT ou DIF_FIRSTTIMESETUP.

Contexte
Pointe vers une structure COINSTALLER_CONTEXT_DATA .

Un co-programme d’installation d’appareil retourne l’une des valeurs suivantes :

NO_ERROR
Le co-programme d’installation a effectué les actions appropriées pour l’installFunction spécifié, ou le co-programme d’installation a déterminé qu’il n’avait pas besoin d’effectuer d’actions pour la demande.

Le co-programme d’installation doit également retourner NO_ERROR s’il reçoit un code DIF non reconnu. (Notez que les programmes d’installation de classe retournent ERROR_DI_DO_DEFAULT pour les codes DIF non reconnus.)

ERROR_DI_POSTPROCESSING_REQUIRED
Le co-programme d’installation a effectué toutes les actions appropriées pour l’installFunction spécifié et demande à être appelé à nouveau une fois que le programme d’installation de classe a traité la demande.

Erreur Win32
Le co-programme d’installation a rencontré une erreur.

Un co-programme d’installation ne définit pas l’état de retour de ERROR_DI_DO_DEFAULT. Cet état ne peut être utilisé que par un programme d’installation de classe. Si un co-programme d’installation retourne cet état, SetupDiCallClassInstaller ne traite pas correctement la requête DIF_Xxx . Un co-programme d’installation peut propager un état de retour de ERROR_DI_DO_DEFAULT dans sa passe de post-traitement, mais il ne définit jamais cette valeur.

COINSTALLER_CONTEXT_DATA

COINSTALLER_CONTEXT_DATA est une structure de contexte spécifique au co-programme d’installation qui décrit une demande d’installation. Le format de la structure est le suivant :

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

La liste suivante décrit les membres de cette structure :

• Le post-traitement est TRUE lorsqu’un co-programme d’installation est appelé après que le programme d’installation de classe approprié, le cas échéant, a traité le code DIF spécifié par InstallFunction. Le post-traitement est en lecture seule pour le co-programme d’installation.

• Si post-traitement a la valeur FALSE, InstallResult n’est pas pertinent. Si post-traitement a la valeur TRUE, InstallResult correspond à l’état actuel de la demande d’installation. Cette valeur est NO_ERROR ou un état d’erreur retourné par le composant précédent appelé pour cette demande d’installation. Un co-programme d’installation peut propager l’état en retournant cette valeur pour son retour de fonction, ou il peut retourner un autre état. InstallResult est en lecture seule pour le co-programme d’installation.

• PrivateData pointe vers une mémoire tampon allouée par le co-programme d’installation. Si un co-programme d’installation définit ce pointeur et demande un posttraitement, SetupDiCallClassInstaller transmet le pointeur au co-programme d’installation lorsqu’il appelle le co-programme d’installation pour le post-traitement.