Co-Installer-Schnittstelle

Hinweis

Die in diesem Abschnitt beschriebenen Features werden nicht unterstützt, und Treiberpakete, die sie enthalten, erhalten keine Microsoft-Signatur mehr. Weitere Informationen finden Sie unter Verwenden einer universellen INF-Datei.

Die Schnittstelle eines Co-Installers besteht aus einer exportierten Einstiegspunktfunktion und einer zugeordneten Datenstruktur.

Einstiegspunkt des Co-Installers

Ein Co-Installer muss eine Einstiegspunktfunktion exportieren, die über den folgenden Prototyp verfügt:

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
Gibt die zu verarbeitende Geräteinstallationsanforderung an, an der das Co-Installationsprogramm die Möglichkeit hat, teilzunehmen. Diese Anforderungen werden mithilfe von DIF-Codes wie DIF_INSTALLDEVICE angegeben. Weitere Informationen finden Sie unter Geräteinstallationsfunktionscodes.

DeviceInfoSet
Stellt einen Handle für einen Geräteinformationssatz bereit.

DeviceInfoData
Identifiziert optional ein Gerät, das das Ziel der Geräteinstallationsanforderung ist. Wenn dieser Parameter nicht NULL ist, identifiziert er ein Geräteinformationselement im Geräteinformationssatz. DeviceInfoData ist nicht NULL , wenn SetupDiCallClassInstaller einen gerätespezifischen Co-Installer aufruft. Ein klassenspezifisches Co-Installer kann mit einer DIF-Anforderung aufgerufen werden, die eine NULLDeviceInfoData-Instanz aufweist, z. B. DIF_DETECT oder DIF_FIRSTTIMESETUP.

Kontext
Zeigt auf eine COINSTALLER_CONTEXT_DATA-Struktur .

Ein Geräte-Co-Installer gibt einen der folgenden Werte zurück:

NO_ERROR
Das Co-Installationsprogramm hat die entsprechenden Aktionen für die angegebene InstallFunction ausgeführt, oder der Co-Installer hat festgestellt, dass keine Aktionen für die Anforderung ausgeführt werden müssen.

Das Co-Installationsprogramm muss auch NO_ERROR zurückgeben, wenn es einen nicht erkannten DIF-Code empfängt. (Beachten Sie, dass Klasseninstallationsprogramme ERROR_DI_DO_DEFAULT für nicht erkannte DIF-Codes zurückgeben.)

ERROR_DI_POSTPROCESSING_REQUIRED
Das Co-Installationsprogramm hat alle geeigneten Aktionen für die angegebene InstallFunction ausgeführt und fordert einen erneuten Aufruf an, nachdem der Klasseninstallateur die Anforderung verarbeitet hat.

Win32-Fehler
Beim Co-Installer ist ein Fehler aufgetreten.

Ein Co-Installer legt keinen Rückgabestatus von ERROR_DI_DO_DEFAULT fest. Dieser Status kann nur von einem Klasseninstallationsprogramm verwendet werden. Wenn ein Co-Installer diesen Status zurückgibt, verarbeitet SetupDiCallClassInstaller die DIF_Xxx-Anforderung nicht ordnungsgemäß. Ein Co-Installer kann einen Rückgabestatus von ERROR_DI_DO_DEFAULT in seinem Nachverarbeitungsdurchlauf weitergeben , legt diesen Wert jedoch nie fest .

COINSTALLER_CONTEXT_DATA

COINSTALLER_CONTEXT_DATA ist eine Co-Installer-spezifische Kontextstruktur, die eine Installationsanforderung beschreibt. Das Format der Struktur ist:

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

In der folgenden Liste werden die Elemente dieser Struktur beschrieben:

• PostProcessing ist TRUE , wenn ein Co-Installer aufgerufen wird, nachdem das entsprechende Klasseninstallationsprogramm den diF-Code verarbeitet hat, der von InstallFunction angegeben wurde. PostProcessing ist schreibgeschützt für das Co-Installationsprogramm.

• Wenn PostProcessingFALSE ist, ist InstallResult nicht relevant. Wenn PostProcessingTRUE ist, ist InstallResult der aktuelle Status der Installationsanforderung. Dieser Wert ist NO_ERROR oder ein Fehlerstatus, der von der vorherigen Komponente zurückgegeben wird, die für diese Installationsanforderung aufgerufen wurde. Ein Co-Installer kann den Status weitergeben, indem er diesen Wert für seine Funktionsrückgabe zurückgibt, oder es kann einen anderen Status zurückgeben. InstallResult ist schreibgeschützt für das Co-Installer.

• PrivateData verweist auf einen vom Co-Installer zugewiesenen Puffer. Wenn ein Co-Installer diesen Zeiger festlegt und die Nachverarbeitung anfordert, übergibt SetupDiCallClassInstaller den Zeiger an den Co-Installer, wenn es den Co-Installer für die Nachverarbeitung aufruft.