SetupDiRegisterDeviceInfo 函式 (setupapi.h)

  • 發行項

SetupDiRegisterDeviceInfo 函式是DIF_REGISTERDEVICE要求的默認處理程式。

語法

WINSETUPAPI BOOL SetupDiRegisterDeviceInfo(
  [in]            HDEVINFO           DeviceInfoSet,
  [in, out]       PSP_DEVINFO_DATA   DeviceInfoData,
  [in]            DWORD              Flags,
  [in, optional]  PSP_DETSIG_CMPPROC CompareProc,
  [in, optional]  PVOID              CompareContext,
  [out, optional] PSP_DEVINFO_DATA   DupDeviceInfoData
);

參數

[in] DeviceInfoSet

裝置資訊集的句柄，其中包含代表要註冊之裝置的裝置信息元素。 裝置資訊集不得包含任何遠端元素。

[in, out] DeviceInfoData

SP_DEVINFO_DATA 結構的指標，指定 DeviceInfoSet 中的裝置信息專案。 這是 IN-OUT 參數，因為 DeviceInfoData。DevInst 可能會在傳回時使用新的句柄值來更新。

[in] Flags

旗標值，控制裝置的註冊方式，可以是零或下列值：

SPRDI_FIND_DUPS

搜尋先前存在的 裝置實例 ，該實例對應至 DeviceInfoData 所代表的裝置。 如果未指定此旗標，則不論裝置實例是否已存在裝置實例，都會註冊裝置實例。

如果呼叫端提供 CompareProc，則呼叫端也必須設定此旗標。

[in, optional] CompareProc

用於重複偵測之比較回呼函式的指標。 這個參數是選擇性的，而且可以是 NULL。 如果指定此參數，則會針對與所註冊裝置實例相同的類別的每個裝置實例呼叫回呼函式。 回呼函式的原型如下所示：

typedef  DWORD (CALLBACK* PSP_DETSIG_CMPPROC) (
    IN HDEVINFO  DeviceInfoSet,
    IN PSP_DEVINFO_DATA  NewDeviceData,
    IN PSP_DEVINFO_DATA  ExistingDeviceData,
    IN PVOID  CompareContextOPTIONAL
    );

如果比較函式發現兩個裝置重複，則必須傳回ERROR_DUPLICATE_FOUND。 否則，它應該會傳回NO_ERROR。 如果遇到其他錯誤，回呼函式應該會傳回適當的ERROR_* 程式代碼，以指出失敗。

如果未指定 CompareProc 並要求重複偵測，則會使用預設的比較行為。 預設值是比較新裝置的偵測簽章與 類別中所有其他裝置的偵測簽章。 偵測簽章包含在裝置開機記錄組態的類別特定資源描述元中。

[in, optional] CompareContext

傳遞至回呼函式之呼叫端提供之內容緩衝區的指標。 如果未指定 CompareProc ，則會忽略此參數。

[out, optional] DupDeviceInfoData

SP_DEVINFO_DATA 結構的指標，可接收重複裝置實例的相關信息，如果有的話，因為嘗試註冊此裝置而發現。 這個參數是選擇性的，而且可以是 NULL。 如果指定此參數，呼叫端必須設定 DupDeviceInfoData。cbSize 為 sizeof (SP_DEVINFO_DATA) 。 如果函式傳回 FALSE，而且 GetLastError 傳回ERROR_DUPLICATE_FOUND，就會填入此專案。 如果還沒有成員，這個裝置資訊元素會新增為指定 DeviceInfoSet 的成員。 如果未指定 DupDeviceInfoData ，則不會將重複專案新增至裝置資訊集。

如果您在處理 DIF_REGISTERDEVICE 要求時呼叫此函式， DupDeviceInfoData 參數必須是 NULL。

傳回值

如果函式成功，函式會傳回 TRUE 。 否則，它會傳回 FALSE ，而且可以使用 呼叫 GetLastError 來擷取記錄的錯誤。

備註

SetupDiRegisterDeviceInfo 主要是設計為在本機計算機上向 隨插即用 (PnP) 管理員註冊非 PnP 裝置。 雖然 SetupDiRegisterDeviceInfo 不會失敗，但如果裝置資訊集是用於遠端電腦，結果會受到限制，因為裝置資訊集之後無法與遠端電腦上的DIF_Xxx 安裝要求或 SetupDiXxx 函式搭配使用。 例如，呼叫 SetupDiCreateDevRegKey 來執行遠端電腦上新註冊裝置的 INF 區段將會失敗。

注意 只有類別安裝程式應該呼叫 SetupDiRegisterDeviceInfo ，而且只有在類別安裝程式必須在 SetupDiRegisterDeviceInfo 完成預設裝置註冊作業之後執行裝置註冊作業的情況。 在這種情況下，當安裝程式處理DIF_REGISTERDEVICE要求時，類別安裝程序必須直接呼叫 SetupDiRegisterDeviceInfo 。 如需呼叫預設處理程式的詳細資訊，請參閱呼叫預設 DIF 程式代碼處理程式式。
 
註冊裝置資訊項目之後，呼叫端應該更新與此裝置相關聯的 DevInst 句柄的任何預存複本。 這是必要的，因為句柄值可能會在註冊期間變更。 呼叫端不需要再次擷取SP_DEVINFO_DATA結構，因為結構的 DevInst 欄位會更新以反映句柄的目前值。

請勿直接針對 PnP 裝置實例呼叫此函式。 操作系統會自動註冊 PnP 裝置實例。 不過，您必須以下列其中一種方式註冊非 PnP 裝置實例：

  1. 如果您的安裝應用程式使用 DIF_DETECT 要求成功偵測裝置，它也應該使用DIF_REGISTERDEVICE要求來註冊裝置實例。 要求應該以預設方式處理。 (根據預設， SetupDiCallClassInstaller 會先呼叫類別安裝程式和類別共同安裝程式，以執行重複偵測並註冊裝置實例。如果這些安裝程式未註冊裝置實例， SetupDiCallClassInstaller 會呼叫 SetupDiRegisterDeviceInfo 來執行重複的偵測，並註冊裝置實例。)
  2. 例如，如果您的安裝應用程式 (建立裝置實例，方法是呼叫 SetupDiCreateDeviceInfo) 但不會重複偵測，則安裝應用程式應該使用DIF_REGISTERDEVICE要求來註冊裝置實例。 要求應該以預設方式處理，如先前所述。
  3. 如果您的安裝應用程式建立新的裝置並執行重複偵測，您的安裝應用程式應該使用DIF_REGISTERDEVICE要求，但應該防止 SetupDiCallClassInstaller 呼叫 SetupDiRegisterDeviceInfo。 若要防止 SetupDiCallClassInstaller 呼叫 SetupDiRegisterDeviceInfo，請在裝置實例SP_DEVINSTALL_PARAMS結構的 Flags 成員中設定DI_NODI_DEFAULTACTION旗標。

    如果 SetupDiCallClassInstaller 針對DIF_REGISTERDEVICE要求傳回 TRUE ，類別安裝程式或類別共同安裝程式會註冊裝置實例。 在此情況下，安裝應用程式可以繼續安裝裝置。

    如果 SetupDiCallClassInstaller 針對DIF_REGISTERDEVICE要求傳回 FALSE ，類別安裝程式或類別共同安裝程式不會註冊裝置實例。 在此情況下，安裝應用程式應該執行下列其中一項，視 GetLastError 針對要求傳回的最後一個錯誤而定：

    • 如果最後一個錯誤ERROR_DI_DO_DEFAULT，安裝應用程式可以直接呼叫 SetupDiRegisterDeviceInfo ，並提供 CompareProc 來執行重複偵測。 如果此呼叫成功且找不到重複專案，則裝置安裝可以繼續。 如果找到重複專案， SetupDiRegisterDeviceInfo 會傳回 FALSE，而且安裝應用程式必須終止裝置安裝。
    • 如果最後一個錯誤未ERROR_DI_DO_DEFAULT，則安裝應用程式必須終止裝置安裝。
    SetupDiRegisterDeviceInfo 的呼叫端必須是 Administrators 群組的成員。

規格需求

需求 值
最低支援的用戶端 可在 Microsoft Windows 2000 和更新版本的 Windows 中使用。
目標平台 桌面
標頭 setupapi.h (包括 Setupapi.h)
程式庫 Setupapi.lib
Dll Setupapi.dll

另請參閱

DIF_REGISTERDEVICE

SP_DEVINFO_DATA

SP_DEVINSTALL_PARAMS