SetupDiGetCustomDevicePropertyA 函式 (setupapi.h)

發行項
03/01/2024

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

語法

WINSETUPAPI BOOL SetupDiGetCustomDevicePropertyA(
  [in]            HDEVINFO         DeviceInfoSet,
  [in]            PSP_DEVINFO_DATA DeviceInfoData,
  [in]            PCSTR            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型別字串串。 (For more information, see the Remarks section on this reference page.)

[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