共同安裝程式介面

注意

本節所述的功能不受支援，且包含這些功能的驅動程式套件將不再收到 Microsoft 簽章。 請參閱 使用通用 INF 檔案。

共同安裝程式的介面是由匯出的進入點函式和相關聯的資料結構所組成。

共同安裝程式進入點

共同安裝程式必須匯出具有下列原型的進入點函式：

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
指定正在處理的裝置安裝要求，其中共同安裝程式有參與的選項。 這些要求是使用 DIF 程式碼來指定，例如DIF_INSTALLDEVICE。 如需詳細資訊，請參閱 裝置安裝函式代碼。

DeviceInfoSet
提供 裝置資訊集的控制碼。

DeviceInfoData
選擇性地識別裝置安裝要求的目標裝置。 如果此參數為非Null，它會識別裝置資訊集中的裝置資訊元素。 當SetupDiCallClassInstaller呼叫裝置特定的共同安裝程式時，DeviceInfoData不是Null。 您可以使用具有 NullDeviceInfoData的 DIF 要求呼叫類別特定的共同安裝程式，例如DIF_DETECT或DIF_FIRSTTIMESETUP。

上下文
指向 COINSTALLER_CONTEXT_DATA 結構。

裝置共同安裝程式會傳回下列其中一個值：

NO_ERROR
共同安裝程式會針對指定的 InstallFunction執行適當的動作，或共同安裝程式判斷它不需要對要求執行任何動作。

如果共同安裝程式收到無法辨識的 DIF 程式碼，則也必須傳回NO_ERROR。 (請注意，類別安裝程式會針對無法辨識的 DIF 程式碼傳回ERROR_DI_DO_DEFAULT。)

ERROR_DI_POSTPROCESSING_REQUIRED
共同安裝程式會針對指定的 InstallFunction 執行任何適當的動作，並在類別安裝程式處理要求之後再次呼叫。

Win32 錯誤
共同安裝程式發生錯誤。

共同安裝程式不會設定ERROR_DI_DO_DEFAULT的傳回狀態。 此狀態只能由類別安裝程式使用。 如果共同安裝程式傳回此狀態， SetupDiCallClassInstaller 將不會正確處理DIF_Xxx 要求。 共同安裝程式可能會在其後置處理階段中 傳播 ERROR_DI_DO_DEFAULT的傳回狀態，但永遠不會 設定 此值。

COINSTALLER_CONTEXT_DATA

COINSTALLER_CONTEXT_DATA是描述安裝要求的共同安裝程式特定內容結構。 結構的格式為：

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

下列清單描述此結構的成員：

• 在適當的類別安裝程式之後呼叫共同安裝程式時，PostProcessing為TRUE，如果有的話，則已處理InstallFunction所指定的 DIF 程式碼。 PostProcessing 是共同安裝程式的唯讀。

• 如果 PostProcessing 為 FALSE， 則 InstallResult 不相關。 如果 PostProcessing 為 TRUE， InstallResult 是安裝要求的目前狀態。 這個值NO_ERROR或先前針對此安裝要求呼叫的元件所傳回的錯誤狀態。 共同安裝程式可以傳回此值以傳回其函式傳回來傳播狀態，也可以傳回另一個狀態。 InstallResult 是共同安裝程式的唯讀。

• PrivateData 指向共同安裝程式配置的緩衝區。 如果共同安裝程式設定此指標並要求後置處理， 則 SetupDiCallClassInstaller 會在呼叫共同安裝程式以進行後處理時，將指標傳遞至共同安裝程式。