編寫協(xié)同安裝程序
協(xié)同安裝程序是微軟公司開發(fā)的win32的DLL，它是用來幫助在Windows 2000系統(tǒng)上進行設備安裝。它被Setup API調用作為類安裝程序的“助手”。例如，供應商可以提供協(xié)同安裝程序將特定設備信息寫入INF文件無法處理的注冊表中。

本章內容：
l 4.1 協(xié)同安裝程序總覽
l 4.2 協(xié)同安裝程序界面
l 4.3 協(xié)同安裝程序操作
l 4.4 注冊協(xié)同安裝程序
1.1 協(xié)同安裝程序總覽
由Setup API調用的協(xié)同安裝程序如圖4-1所示。
圖4-1 協(xié)同安裝程序在設備安裝中的分工
帶有陰影的方框表示可由IHV和OEM提供的組件，其他組件則由OS提供。參見第1章“設備安裝總覽”可以了解更多的有關安裝組件的信息。
協(xié)同安裝程序可以是設備專用或類專用的。Setup API只在安裝協(xié)同安裝程序為其注冊的設備時才調用一個設備專用的協(xié)同安裝程序。操作系統(tǒng)(OS)及供應商可以為一個設備注冊零個或多個設備專用的協(xié)同安裝程序。在為協(xié)同安裝程序注冊安裝設備設置類的任何設備時，Setup API調用類協(xié)同安裝程序。操作系統(tǒng)及供應商可以為一個設備設置類注冊一個或多個類協(xié)同安裝程序。除此之外，類協(xié)同安裝程序還可以為一個或多個設置類注冊。

GUI模式設置、新設備DLL以及定制設置應用程序通過調用帶有設備安裝函數(shù)代碼(DIF代碼)的SetupDiCallClassInstaller來安裝設備。對于每一個DIF請求，SetupDiCallClassInstaller調用為設備設置類注冊的任何類協(xié)同安裝程序，調用為特定設備注冊的任何設備協(xié)同安裝程序，以及由系統(tǒng)提供用于設備設置類的類安裝程序(如果有的話)。

定制設置應用程序須調用SetupDiCallClassInstaller而不是直接調用協(xié)同安裝程序或類安裝程序。這個函數(shù)可以保證所有注冊的協(xié)同安裝程序都能被正確調用。

類協(xié)同安裝程序一般都在設備安裝之前注冊，而設備專用的協(xié)同安裝程序則是作為設備安裝的一部分被注冊的。因此類協(xié)同安裝程序總是在第一次構建時就被添加到協(xié)同安裝程序列表之中，并在設備安裝時被所有DIF請求調用。特定設備協(xié)同安裝程序則是在為該設備完成DIF_REGISTER_COINSTALLERS請求之后被添加到重安裝列表之中的(或是在調用了SetupDiRegisterCoDeviceInstallers之后)。特定設備協(xié)同安裝程序并不參與以下DIF請求：DIF_ALLOWINSTALL、DIF_INSTALLDEVICEFILES及DIF_SELECTBESTCOMPATDRV。

如果協(xié)同安裝程序需要響應以下任何一個DIF請求，它就必須是一個類協(xié)同安裝程序(而不是設備專用協(xié)同安裝程序)：
l DIF_FIRSTTIMESETUP，DIF_DETECT*
l DIF_NEWDEVICEWIZARD_PRESELECT
l DIF_NEWDEVICEWIZARD_SELECT
l DIF_NEWDEVICEWIZARD_PREANALYZE
l DIF_NEWDEVICEWIZARD_POSTANALYZE

設備協(xié)同安裝程序并不適用于這樣的上下文，這是因為并沒有標識出某個特定的設備，或是因為在安裝的這個初始階段還沒有注冊過設備安裝程序。
圖4-2顯示了在注冊了任意一個特定設備的協(xié)同安裝程序之后，SetupDiCallClassInstaller調用協(xié)同安裝程序及類安裝程序的順序。

圖4-2 為DIF請求調用協(xié)同安裝程序的處理及后處理示例
在圖4-2所演示的示例中，為該設備的設置類注冊了兩個類協(xié)同安裝程序以及一個特定設備協(xié)同安裝程序。以下步驟對應于圖4-2中的帶圓圈的數(shù)字標號：

1. SetupDiCallClassInstaller調用第一個類協(xié)同安裝程序，同時指定一個表示安裝請求正在處理中的DIF代碼(在本例中是DIF_INSTALLDEVICE)。協(xié)同安裝程序在安裝請求中有參與的選擇權。本例中，第一個注冊的類協(xié)同安裝程序返回NO_ERROR。
2. 接下來，SetupDiCallClassInstaller調用任意額外注冊的類協(xié)同安裝程序。在本例中，第二個類安裝程序返回了ERROR_DI_POSTPROCESSING_REQUIRED，它要求在后處理之后再調用協(xié)同安裝程序。
3. SetupDiCallClassInstaller調用任意注冊的設備專用協(xié)同安裝程序。
4. 在調用了所有的注冊過的協(xié)同安裝程序后，如果設備的設置類有一個系統(tǒng)提供的類安裝程序，SetupDiCallClassInstaller就調用它。在本例中，類安裝程序返回ERROR_DI_DO_DEFAULT，這是類安裝程序的一個典型返回值。
5. 如果有一個缺省的設備處理驅動程序，SetupDiCallClassInstaller就為安裝請求調用它。DIF_INSTALLDEVICE有一個缺省的設備處理驅動程序SetupDiInstallDevice，它是Setup API的一部分。
6. SetupDiCallClassInstaller調用任何要求后處理的協(xié)同安裝程序。在本例中，第二個類協(xié)同安裝程序要求了后處理。
除了協(xié)同安裝程序在它的單個入口點被再一次調用外，協(xié)同安裝程序的后處理與驅動程序的IoCompletion例程相似。當SetupDiCallClassInstaller為后處理調用協(xié)同安裝程序時，它將PostProcessing設為TRUE，并將InstallResult設為Context參數(shù)中的恰當值。在本例中，Context.InstallResult是NO_ERROR，這是因為成功地執(zhí)行了缺省的設備處理驅動程序。
在后處理中，SetupDicallClassInstaller反向調用了協(xié)同安裝程序。如果圖4-2中的所有協(xié)同安裝程序都已返回了ERROR_DI_POSTPROCESSING_REQUIRED，那么SetupDiCallClassInstaller就會為后處理先調用Device_Coinstaller_l，之后再是Class_Coinstaller_2，和Class_Coinstaller_1。類安裝程序并不要求后處理，只有協(xié)同安裝程序才要求。
即使先前的協(xié)同安裝程序在安裝請求中失敗，要求后處理的協(xié)同安裝程序也會被調用。
1.2 安裝程序界面
協(xié)同安裝程序具有以下原型：
typedef
DWORD
( CALLBACK* COINSTALLER_PROC) (
IN DI_FUNCTION InstallFunction,
IN HDEVINFO DeviceInfoSet,
IN PSP_DEVINFO_DADA DeviceInfoData OPTIONAL,
IN OUT PCOINSTALLER_CONTEXT_DATA Context
);
InstallFunction指定了正被處理的設備安裝請求，在其中協(xié)同安裝程序具有參與的選擇權。例如，DIF_INSTALLDEVICE。參見《Windows 2000 Driver Development Reference》一書的第一卷第3部分的第5章“安裝功能代碼”有關“在DIF代碼上的文檔處理”內容。
DeviceInfoSet提供了一個設備信息集的標識值。
DeviceInfoData有選擇性地標識作為設備安裝請求的目標設備。如果這個參數(shù)是非NULL的，它就在設備信息集中標識一個元素。當SetupDiCallClassInstaller調用一個特定設備協(xié)同安裝程序時，DeviceInfoData為非NULL。特定類協(xié)同安裝程序可以同一個具有NULL DeviceInfoData的DIF請求（如DIF_DETECT或DIF_FIRSTTIMESETUP）一起被調用。
Context指向該安裝請求的特定協(xié)同安裝程序上下文結構。這個上下文信息的格式如下：
Typedef struct
_COINSTALLER_CONTEXT_DATA {
BOOLEAN PostProcessing;
DWORD InstallResult;
PVOID PrivateData;
} COINSTALLER_CONTEXT_DATA, *PCOINSTALLER_CONTEXT_DATA;

當在恰當?shù)念惏惭b程序（如有的話）處理了InstallFunction之后再調用協(xié)同安裝程序時，PostProcessing為TRUE。PostProcessing對協(xié)同安裝程序是只讀的。
如果PostProcessing為FALSE，則InstallResult不相關。如果PostProcessing為TRUE，InstallResult就是安裝請求的當前狀態(tài)。該值為NO_ERROR或是一個由為該安裝請求調用的先前部分返回的錯誤狀態(tài)。協(xié)同安裝程序可以為它的函數(shù)返回通過返回該值傳送狀態(tài)，或者可以返回其他狀態(tài)。InstallResult對協(xié)同安裝程序是只讀的。
PrivateData指向一個被分配的協(xié)同安裝程序緩沖。如果協(xié)同安裝程序設置該指針并要求后處理，那么當SetupDiCallClassInstaller為后處理調用協(xié)同安裝程序時，將該指針傳給這個協(xié)同安裝程序。
設備協(xié)同安裝程序返回以下一個值：
l NO_ERROR
協(xié)同安裝程序對特定的InstallFunction執(zhí)行恰當?shù)膭幼鳎騾f(xié)同安裝程序決定它無需為該請求執(zhí)行任何操作。
l ERROR_DI_POSTPROCESSING_REQUIRED
協(xié)同安裝程序對特定的InstallFunction執(zhí)行任何恰當?shù)牟僮鳎瑫r在類安裝已處理了該請求之后并要求被再次調用。
l A Win32 error
協(xié)同安裝程序遇到一個錯誤。
協(xié)同安裝程序不會設置ERROR_DI_DO_DEFAULT的返回狀態(tài)。這個狀態(tài)只能由類安裝程序使用。如果一個協(xié)同安裝程序返回了這樣的狀態(tài)，那么SetupDiCallClassInstaller將不能正確地處理DIF_Xxx請求。協(xié)同安裝程序也可能在后處理傳送中傳輸ERROR_DE_DO_DEFAULT的一個返回狀態(tài)，但是它永遠不會設置這個值。
1.3 協(xié)同安裝程序操作
協(xié)同安裝程序是用戶模式的Win32 DLL，它為注冊編寫額外的配置信息或執(zhí)行要求動態(tài)信息的其他安裝任務，而該動態(tài)信息無法通過編寫INF來得到。
協(xié)同安裝程序可以完成以下一些或所有的任務：
l 打開InstallFunction來處理僅一個或少量的DIF_Xxx請求。
l 根據它是否被后處理調用來執(zhí)行不同的操作（也就是Contex->PostProcessing是否為TRUE?）
l 當為后處理調用時，檢查Context->InstallResult。如果它不是NO_ERROR，就進行任何必需的清除并返回InstallResult。
協(xié)同安裝程序必須不能給最終用戶顯示任何的UI。協(xié)同安裝程序應該為設備提供恰當?shù)娜笔≈怠Ｈ绻鼪]有缺省值并要求用戶輸入，那么其他的設備支持組件就應提示用戶稍后的所需輸入。例如，若調制解調器沒有正確的撥號屬性設置，則需在用戶使用調制解調器而不是在設備設置時提示他們。
1.3.1 處理DIF代碼
每個DIF代碼的參考頁都繼續(xù)了以下一些或全部的部分：
何時發(fā)送
描述Setup應用程序發(fā)送該DIF請求的典型時間及原因。
由誰處理
指出允許哪些安裝程序處理該請求。該安裝程序包括了類安裝程序、類協(xié)同安裝程序（設置-類范圍的協(xié)同安裝程序），以及設備協(xié)同安裝程序（特定設備協(xié)同安裝程序）。
輸入
SetupDiCallClassInstaller通過在它的主入口點調用安裝程序給一個安裝程序發(fā)送一個DIF請求。除了DIF代碼之外，這個功能提供與某請求相關的額外信息。參見每個DIF代碼的參考頁可得到與每個請求一起提供的信息細節(jié)。以下列表包括了額外輸入的一般描述，還列出了用于處理參數(shù)的SetupDiXxx函數(shù)：
l DeviceInfoSet
為設備信息集提供一個標識值。
該標識值是不透明的。利用這個標識值，例如，在調用中將設備信息集標識到SetupDiXxx函數(shù)。
DeviceInfoSet可能具有相聯(lián)的設備設置類。如果是這樣的，則調用SetupDiGetDeviceInfoListClass以得到類GUID。
l DeviceInfoData
有選擇性地給一個SP_DEVINFO_DATA結構提供一個指針，該結構在設備信息集中標識了一個設備。
l Device Installation Parameters
這些非直接的參數(shù)為SP_DEVINSTALL_PARAMS結構中的設備安裝提供了信息。如果DeviceInfoData是非NULL，就有與DeviceInfoData相關的設備安裝參數(shù)。如果DeviceInfoData為NULL，則設備安裝參數(shù)就與DeviceInfoSet相關的設備安裝參數(shù)。
調用SetupDiGetDeviceInstallParams以得到設備安裝參數(shù)。
l Class Installation Parameters
將可選的非直接參數(shù)指定給某個DIF請求。它們尤其是“DIF請求參數(shù)”。例如，一個DIF_REMOVE安裝請求的類安裝參數(shù)被包含在一個SP_REMOVEDEVICE_PARAMS結構中。
每個SP_XXX_PARAMS結構開始于一個固定大小的SP_CLASSINSTALL-HEADER。
調用SetupDiGetClassInstallParams以得到類安裝參數(shù)。
如果DIF請求具有類安裝參數(shù)，就有與DeviceInfoSet相關的參數(shù)集，及與DeviceInfoData相關的另一個參數(shù)集（如果DIF請求指定了DeviceInfoData）。SetupDiGetClassInstallParams返回了可得到的最特定參數(shù)。
l 上下文 （Context）
協(xié)同安裝程序具有一個可選的上下文參數(shù)。
l 輸出 （Output）
描述這個DIF代碼所需的輸出。
如果安裝程序修改了設備安裝參數(shù)，那么在返回之前安裝程序必須調用SetupDiSetDeviceInstallParams來應用改變。類似地，如果安裝程序修改DIF代碼的類安裝參數(shù)，安裝程序必須調用SetupDiSetClassInstallParams。
l 返回值 (Return Value)
指定DIF代碼的恰當返回值。參見圖4-3中有關返回值的更多信息。
l 缺省處理程序 (Default Handler)
指定SetupDi函數(shù)，它執(zhí)行DIF代碼的系統(tǒng)定義操作。并非所有的DIF代碼都具有缺省處理程序。除非協(xié)同安裝程序或類安裝程序采取步驟阻礙調用缺省處理程序，SetupDiCallClassInstaller才會在它調用類安裝程序之后再調用DIF代碼的缺省處理程序（但卻是在它調用任何為后處理注冊的協(xié)同安裝程序之前）。
操作 (Operation)
描述安裝程序可能用來處理DIF請求的典型任務。
其他 (See Also)
相關信息源的列表。
圖4-3中是SetupDiCallClassInstaller中處理DIF代碼的事件序列。
操作系統(tǒng)執(zhí)行每個DIF代碼的一些操作。由供應商提供的協(xié)同安裝程序及類安裝程序可以參與安裝行為。請注意即使DIF代碼失敗了，SetupDiCallClassInstaller也調用了為后處理注冊的協(xié)同安裝程序。
1.4 注冊協(xié)同安裝程序
協(xié)同安裝程序可以為某個設置類的單個或全部設備注冊。當特定設備中的一個已被安裝時，這些設備的協(xié)同安裝程序就通過INF文件動態(tài)注冊。類協(xié)同安裝程序被手工注冊或由定制的設置應用程序及一個INF注冊。
如要了解更多的信息，可參見《Registering a Device-Specific Coinstaller》及《Registering a Class Coinstaller》。
如要更新協(xié)同安裝程序，DLL的每個新版本都需有一個新的文件名，這是因為當用戶在設備屬性頁上點擊Update Driver按紐時，尤其要用到DLL。
圖4-3 在SetupDiCallClassInstaller中的DIF代碼處理流程圖
1.4.1 注冊設備專用的協(xié)同安裝程序
為了注冊設備專用的協(xié)同安裝程序，將以下部分添加到設備的INF文件中：
； ：
； ：
[DestinationDirs]
XxxCopyFilesSection = 11 \\DIRID_SYSTEM
\\ Xxx = driver or dev . prefix
； ：
； ：
[XxxInstall . OS-platporm.CoInstallers] \\ OS-platform is optional
CopyFiles = XxxCopyFilesSection
AddReg = Xxx.OS-platform. CoInstallers_AddReg
[XxxCopyFilesSection]
XxxCoInstall.dll
{Xxx. OS-platform.CoInstallers_AddReg}
HKR,,CoInstallers32.0x00010000.”XxxCoInstall.dll. \
XxxCoInstallEntryPoint”
DestinationDirs部分中的項說明XxxCopyFiles部分中列出的文件將被復制到系統(tǒng)目錄下。Xxx前綴標識出驅動程序、設備或設備組（如cdrom_CopyFilesSection）。Xxx前綴應是唯一的。
協(xié)同安裝程序安裝節(jié)的名稱可以用可選的操作系統(tǒng)/架構擴展（如cdrom_install.NTx86.CoInstallers）來修飾。
Xxx_AddReg部分中的項在設備驅動程序密鑰中建立一個CoInstallers32值項。該項包含了協(xié)同安裝程序DLL，而且可選地還可有一個特定入口點。如果忽略這個輸入點，則缺省為CoDeviceInstall。十六進制標志參數(shù)（0x00010000）指明這是REG_MULTI_SZ值項。
為了給設備注冊多于一個的特定設備協(xié)同安裝程序，復制每個協(xié)同安裝程序的文件并在注冊項中包含至少一個信息串。例如，為了注冊兩個協(xié)同安裝程序，建立如下部分：
； ：
； ：
[DestinationDirs]
XxxCopyFilesSection = 11 \\DIRID_SYSTEM
\\ Xxx = driver or dev . prefix
； ：
； ：
[XxxInstall . OS-platporm.CoInstallers] \\ OS-platform is optional
CopyFiles = XxxCopyFilesSection
AddReg = Xxx.OS-platform. CoInstallers_AddReg
[XxxCopyFilesSection]
XxxCoInstall.dll \\ copy 1st coinst. file
YyyCoinstall.dll \\ copy 2nd coinst. file
[Xxx. OS-platform.CoInstallers_AddReg]
HKR..CoInstallers32.0x00010000. \
“XxxCoInstall.dll. XxxCoInstallEntryPoint”. \
“YyyCoInstall.dll. YyyCoInstallEntryPoint”
\\ add both to registry
當執(zhí)行設備專用的協(xié)同安裝程序INF部分時，該協(xié)同安裝程序是在安裝一個設備的過程中被注冊的。接著Setup API在安裝過程中的每個隨后步驟上調用協(xié)同安裝程序。如果為一個設備注冊多個協(xié)同安裝程序，那么Setup API按其在注冊中所列順序調用它們。
1.4.2 注冊類協(xié)同安裝程序
如要為某個設置類的每個設備都注冊一個協(xié)同安裝程序，可按以下所列建立一個注冊表項
HKLM\System\CurrentControlSet\Control\CoDeviceInstallers subkey:
{setup-class-GUID}: REG_MULTI_SZ : “XyzCoInstall.dll. XyzCoInstallEntryPoint\0\0”
該系統(tǒng)建立了CoDeviceInstallers密鑰。Setup-class-GUID為設備設置類指定GUID。如果協(xié)同安裝程序提供設備的多個類，它就建立每個設置類的單個值項。
我們不能覆蓋先前寫給setup-class-GUID密鑰的其他協(xié)同安裝程序。讀取這個密鑰，將自己的協(xié)同安裝程序信息串附加到REG_MULTI_SZ列表中，并將該密鑰寫回到注冊表中。
如果忽略CoInstallEntryPoint，則缺省為CoDeviceInstall。
協(xié)同安裝程序DLL必須也被復制到系統(tǒng)目錄下。
一旦復制了文件且做出了注冊表項，類協(xié)同安裝程序就可被用來調用相關設備和服務。
不用手工建立注冊項來注冊一個類協(xié)同安裝程序，就可以利用INF文件注冊它，如下所示。
[version]
signature = “$Windows NT$”
[DestinationDirs]
DefaultDestDir = 11 / / DIRID_SYSTEM
[DefaultInstall]
CopyFiles = @classXcoinst.dll
AddReg = CoInstaller_AddReg
[CoInstaller_AddReg]
HKLM.System\CurrentControlSet\Control\CoDeviceInstallers, \
{setup-class-GUID}, 0x00010008, “classXcoinst.dll,classXCoInstaller’
; above line uses the line continuation character (\)
這個例子INF將文件classXcoinst.dll復制到系統(tǒng)目錄下并在CoDeviceInstallers密鑰下建立了一個setup-class-GUID類的項。Xxx-AddReg部分的項指示兩個標志：”00010000”標志表示這個項是REG_MULTI_SZ，而”00000008”標志表示新值將被附加到任何已有的值上（如果新值并未存在于信息串中）。
這樣一個注冊表類協(xié)同安裝程序的INF可由右點擊安裝或通過SetupInstallFromInfSection應用程序激活。