SetupDiGetDeviceRegistryPropertyA 函式（setupapi.h）

發行項
11/20/2024

SetupDiGetDeviceRegistryProperty 函式會擷取指定的隨插即用裝置屬性。

語法

WINSETUPAPI BOOL SetupDiGetDeviceRegistryPropertyA(
  [in]            HDEVINFO         DeviceInfoSet,
  [in]            PSP_DEVINFO_DATA DeviceInfoData,
  [in]            DWORD            Property,
  [out, optional] PDWORD           PropertyRegDataType,
  [out, optional] PBYTE            PropertyBuffer,
  [in]            DWORD            PropertyBufferSize,
  [out, optional] PDWORD           RequiredSize
);

參數

[in] DeviceInfoSet

裝置資訊的句柄，其中包含代表要擷取即插即用屬性之裝置的裝置信息元素。

[in] DeviceInfoData

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

[in] Property

下列其中一個值，指定要擷取的屬性：

SPDRP_ADDRESS

函式會擷取裝置的位址。

SPDRP_BUSNUMBER

函式會擷取裝置的總線號碼。

SPDRP_BUSTYPEGUID

函式會擷取裝置總線類型的 GUID。

SPDRP_CAPABILITIES

函式會擷取 DWORD 中下列CM_DEVCAP_Xxx 旗標的位 OR。這些旗標所代表的裝置功能會對應至 DEVICE_CAPABILITIES 結構成員所代表的裝置功能。 CM_DEVCAP_Xxx常數定義於 Cfgmgr32.h.

CM_DEVCAP_Xxx 旗標	對應的DEVICE_CAPABILITIES結構成員
CM_DEVCAP_LOCKSUPPORTED	LockSupported
CM_DEVCAP_EJECTSUPPORTED	退出
CM_DEVCAP_REMOVABLE	卸除式
CM_DEVCAP_DOCKDEVICE	DockDevice
CM_DEVCAP_UNIQUEID	UniqueID
CM_DEVCAP_SILENTINSTALL	SilentInstall
CM_DEVCAP_RAWDEVICEOK	RawDeviceOK
CM_DEVCAP_SURPRISEREMOVALOK	SurpriseRemovalOK
CM_DEVCAP_HARDWAREDISABLED	HardwareDisabled
CM_DEVCAP_NONDYNAMIC	NonDynamic

SPDRP_CHARACTERISTICS

函式會擷取 DWORD 中裝置特性旗標的位 OR。如需這些旗標的描述，這些旗標定義於 Wdm.h 和 Ntddk.h中，請參閱 IoCreateDevice 函式的 DeviceCharacteristics 參數。

SPDRP_CLASS

函式會擷取REG_SZ字串，其中包含裝置裝置設定類別。

SPDRP_CLASSGUID

函式會擷取REG_SZ字串，其中包含代表裝置裝置設定類別的 GUID。

SPDRP_COMPATIBLEIDS

函式會擷取REG_MULTI_SZ字串，其中包含裝置的相容標識符清單。如需相容識別碼的相關信息，請參閱裝置識別字串。

SPDRP_CONFIGFLAGS

函式會擷取 DWORD 值中裝置組態旗標的位 OR。組態旗標是由 Regstr.h中定義的 CONFIGFLAG_Xxx 位掩碼來表示。

SPDRP_DEVICE_POWER_DATA

（Windows XP 和更新版本）函式會擷取包含裝置電源管理資訊的 CM_POWER_DATA 結構。

SPDRP_DEVICEDESC

函式會擷取包含裝置描述的REG_SZ字串。

SPDRP_DEVTYPE

函式會擷取代表裝置類型的 DWORD 值。如需詳細資訊，請參閱指定裝置類型。

SPDRP_DRIVER

函式會擷取字串，以識別裝置軟體密鑰（有時稱為驅動程式密鑰）。如需驅動程式金鑰的詳細資訊，請參閱裝置和驅動程式的登錄樹狀架構和金鑰。

SPDRP_ENUMERATOR_NAME

函式會擷取REG_SZ字串，其中包含裝置列舉值的名稱。

SPDRP_EXCLUSIVE

函式會擷取 DWORD 值，指出使用者是否可以取得裝置的獨佔使用。如果允許獨佔使用，則傳回的值為一，否則為零。如需詳細資訊，請參閱 IoCreateDevice。

SPDRP_FRIENDLYNAME

函式會擷取包含裝置易記名稱的REG_SZ字串。

SPDRP_HARDWAREID

函式會擷取REG_MULTI_SZ字串，其中包含裝置的硬體標識符清單。如需硬體識別碼的相關資訊，請參閱裝置識別字串。

SPDRP_INSTALL_STATE

（Windows XP 和更新版本）函式會擷取 DWORD 值，指出裝置的安裝狀態。安裝狀態是由 Cfgmgr32.h中定義的其中一個 CM_INSTALL_STATE_Xxx 值表示。 CM_INSTALL_STATE_Xxx 值會對應至 DEVICE_INSTALL_STATE 列舉值。

SPDRP_LEGACYBUSTYPE

函式會將裝置的舊版總線類型擷取為INTERFACE_TYPE值（定義於 Wdm.h 和 Ntddk.h中）。

SPDRP_LOCATION_INFORMATION

函式會擷取包含裝置硬體位置的REG_SZ字串。

SPDRP_LOCATION_PATHS

（Windows Server 2003 及更新版本）函式會擷取代表裝置樹狀結構中裝置位置的REG_MULTI_SZ字串。

SPDRP_LOWERFILTERS

函式會擷取包含裝置較低篩選器驅動程式名稱的REG_MULTI_SZ字串。

SPDRP_MFG

函式會擷取包含裝置製造商名稱的REG_SZ字串。

SPDRP_PHYSICAL_DEVICE_OBJECT_NAME

函式會擷取REG_SZ字串，其中包含與裝置 PDO 相關聯的名稱。如需詳細資訊，請參閱 IoCreateDevice。

SPDRP_REMOVAL_POLICY

（Windows XP 和更新版本）函式會將裝置目前的移除原則擷取為 DWORD，其中包含 Cfgmgr32.h中定義的其中一個CM_REMOVAL_POLICY_Xxx 值。

SPDRP_REMOVAL_POLICY_HW_DEFAULT

（Windows XP 和更新版本）函式會將裝置的硬體指定預設移除原則擷取為 DWORD，其中包含 Cfgmgr32.h中定義的其中一個 CM_REMOVAL_POLICY_Xxx 值。

SPDRP_REMOVAL_POLICY_OVERRIDE

（Windows XP 和更新版本）函式會從登錄中擷取裝置的覆寫移除原則（如果有的話），作為 DWORD，其中包含 Cfgmgr32.h中定義的其中一個 CM_REMOVAL_POLICY_Xxx 值。

SPDRP_SECURITY

函式會擷取裝置的 SECURITY_DESCRIPTOR 結構。

SPDRP_SECURITY_SDS

函式會擷取包含裝置安全性描述元的REG_SZ字串。如需安全性描述元字串的相關信息，請參閱安全性描述元定義語言（Windows）。如需安全性描述元字串格式的詳細資訊，請參閱安全性描述元定義語言（Windows）。

SPDRP_SERVICE

函式會擷取包含裝置服務名稱的REG_SZ字串。

SPDRP_UI_NUMBER

函式會擷取設定為裝置 DEVICE_CAPABILITIES 結構成員 UINumber 值的 DWORD 值。

SPDRP_UI_NUMBER_DESC_FORMAT

函式會擷取用來顯示 UINumber 值的格式字串（REG_SZ）。

SPDRP_UPPERFILTERS

函式會擷取包含裝置上層篩選驅動程式名稱的REG_MULTI_SZ字串。

[out, optional] PropertyRegDataType

接收所擷取之屬性之數據類型之變數的指標。這是其中一種標準登錄數據類型。這個參數是選擇性的，而且可以 NULL。

[out, optional] PropertyBuffer

接收所擷取之屬性之緩衝區的指標。如果此參數設定為 NULL，而且 PropertyBufferSize 也設定為零，則函式會傳回 requiredSize中緩衝區所需的大小。

[in] PropertyBufferSize

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

[out, optional] RequiredSize

DWORD 類型的變數指標，這個變數會接收所要求屬性數據所需的 PropertyBuffer 緩衝區大小，以位元組為單位。這個參數是選擇性的，而且可以 NULL。

傳回值

SetupDiGetDeviceRegistryProperty 如果呼叫成功，則會傳回 true TRUE。否則，它會傳回 FALSE，而且可以藉由呼叫 getLastError 來擷取記錄的錯誤。 SetupDiGetDeviceRegistryProperty 如果裝置的要求屬性不存在或屬性數據無效，則會傳回ERROR_INVALID_DATA錯誤碼。

言論

注意

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

要求

要求	價值
最低支援的用戶端	Microsoft Windows 2000 和更新版本的 Windows 中提供。
目標平臺	DesktopFor universal， call CM_Get_DevNode_Registry_Property
標頭	setupapi.h （包括 Setupapi.h）
連結庫	Setupapi.lib

另請參閱

IoGetDeviceProperty

SetupDiGetClassRegistryProperty

SetupDiSetClassRegistryProperty

SetupDiSetDeviceRegistryProperty

共用方式為

SetupDiGetDeviceRegistryPropertyA 函式 （setupapi.h）

語法

參數