SetupDiGetCustomDevicePropertyW 函式（setupapi.h）

發行項
11/20/2024

SetupDiGetCustomDeviceProperty 函式會從登錄擷取指定的自定義裝置屬性。

語法

WINSETUPAPI BOOL SetupDiGetCustomDevicePropertyW(
  [in]            HDEVINFO         DeviceInfoSet,
  [in]            PSP_DEVINFO_DATA DeviceInfoData,
  [in]            PCWSTR           CustomPropertyName,
  [in]            DWORD            Flags,
  [out, optional] PDWORD           PropertyRegDataType,
  [out]           PBYTE            PropertyBuffer,
  [in]            DWORD            PropertyBufferSize,
  [out, optional] PDWORD           RequiredSize
);

參數

[in] DeviceInfoSet

裝置資訊集句柄，其中包含代表要擷取自定義裝置屬性之裝置的裝置信息元素。

[in] DeviceInfoData

SP_DEVINFO_DATA 結構的指標，指定 deviceInfoSet中的裝置信息專案。

[in] CustomPropertyName

代表自訂屬性的登錄值名稱。

[in] Flags

旗標值，指出應該如何傳回要求的資訊。旗標可以是零或下列其中一項：

DICUSTOMDEVPROP_MERGE_MULTISZ

如果設定，函式會擷取裝置實例特定的屬性值和硬體標識元特定的屬性值，並串連為REG_MULTI_SZ型別字串串。（如需詳細資訊，請參閱本參考頁面上的<<備註> 一節。

[out, optional] PropertyRegDataType

接收所擷取屬性之數據類型之 DWORD 類型的變數指標。數據類型會指定為代表登錄數據類型的其中一個REG_前置常數。這個參數是選擇性的，而且可以 NULL。

[out] PropertyBuffer

接收要求之屬性信息的緩衝區指標。

[in] PropertyBufferSize

PropertyBuffer 緩衝區的大小，以位元組為單位。

[out, optional] RequiredSize

DWORD 類型的變數指標，接收接收所要求資訊所需的緩衝區大小，以位元組為單位。這個參數是選擇性的，而且可以 NULL。如果指定此參數，SetupDiGetCustomDeviceProperty 傳回所需的大小，不論 PropertyBuffer 緩衝區是否夠大，都足以接收要求的資訊。

傳回值

如果作業成功，SetupDiGetCustomDeviceProperty 會傳回 TRUE。否則，函式會傳回 FALSE，而且可以使用呼叫 getLastError 來擷取記錄的錯誤。如果 PropertyBuffer 緩衝區不夠大，無法接收要求的資訊，SetupDiGetCustomDeviceProperty 會傳回 FALSE，而後續呼叫 getLastError 會傳回ERROR_INSUFFICIENT_BUFFER。

言論

SetupDiGetCustomDeviceProperty 擷取與單一裝置實例或符合特定硬體識別碼的所有裝置相關聯的裝置屬性。（如需硬體識別碼的相關信息，請參閱裝置識別字串）。

廠商可以使用 INF DDInstall.HW 區段中 INF AddReg 指示詞來設定裝置實例的屬性，並指定 HKR 登錄根目錄。

只有系統可以設定硬體識別碼的屬性。系統會提供某些硬體識別碼的「圖示」屬性。

函式會先檢查指定的裝置實例是否存在指定的屬性。如果是，則會傳回屬性的值。如果沒有，此函式會檢查屬性是否存在於符合指定裝置實例硬體標識碼的所有裝置上。如果是，則會傳回屬性的值。如果在 Flags中設定DICUSTOMDEVPROP_MERGE_MULTISZ，則函式會傳回與裝置實例和硬體標識符相關聯的屬性值，如果兩者都存在的話。

注意

setupapi.h 標頭會根據 UNICODE 預處理器常數的定義，將 SetupDiGetCustomDeviceProperty 定義為自動選取此函式的 ANSI 或 Unicode 版本。混合使用編碼中性別名與非編碼中性的程序代碼，可能會導致編譯或運行時間錯誤不符。如需詳細資訊，請參閱函式原型的慣例。

要求

要求	價值
最低支援的用戶端	適用於 Windows XP 和更新版本的 Windows。
目標平臺	桌面
標頭	setupapi.h （包括 Setupapi.h）
連結庫	Setupapi.lib
DLL	Setupapi.dll