SetupDiGetDevicePropertyW 函式 (setupapi.h)

  • 發行項

SetupDiGetDeviceProperty 函式會擷取裝置實例屬性。

語法

WINSETUPAPI BOOL SetupDiGetDevicePropertyW(
  [in]            HDEVINFO         DeviceInfoSet,
  [in]            PSP_DEVINFO_DATA DeviceInfoData,
  [in]            const DEVPROPKEY *PropertyKey,
  [out]           DEVPROPTYPE      *PropertyType,
  [out, optional] PBYTE            PropertyBuffer,
  [in]            DWORD            PropertyBufferSize,
  [out, optional] PDWORD           RequiredSize,
  [in]            DWORD            Flags
);

參數

[in] DeviceInfoSet

裝置 資訊集 的句柄，其中包含要擷取裝置實例屬性的裝置實例。

[in] DeviceInfoData

SP_DEVINFO_DATA 結構的指標，表示要擷取裝置實例屬性的裝置實例。

[in] PropertyKey

DEVPROPKEY 結構的指標，表示所要求裝置實例屬性的裝置屬性索引鍵。

[out] PropertyType

DEVPROPTYPE 型別變數的指標，可接收所要求裝置實例屬性的 property-data-type 標識符，其中 property-data-type identifier 是基底數據類型標識符之間的位 OR，如果修改基底數據類型，則為 property-data-type 修飾詞。

[out, optional] PropertyBuffer

接收要求之裝置實例屬性之緩衝區的指標。 只有在緩衝區夠大，足以保存所有屬性值數據時，SetupDiGetDeviceProperty 才會擷取要求的屬性。 指標可以是 NULL。 如果指標設定為 NULL 且提供 RequiredSize，SetupDiGetDeviceProperty 會以位元組為單位傳回屬性的大小，以位元組為單位。* RequiredSize。

[in] PropertyBufferSize

PropertyBuffer 緩衝區的大小，以位元組為單位。 如果 PropertyBuffer 設定為 NULL，PropertyBufferSize 必須設定為零。

[out, optional] RequiredSize

如果擷取屬性，則為接收裝置實例屬性大小之 DWORD 型別變數的指標，如果緩衝區不夠大，則為所需的緩衝區大小。 此指標可以設定為 NULL。

[in] Flags

此參數必須設定為零。

傳回值

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

下表包含此函式可能會記錄的一些較常見的錯誤碼。

傳回碼 Description
ERROR_INVALID_FLAGS
 Flags 的值不是零。
ERROR_INVALID_HANDLE
 DevInfoSet 指定的裝置資訊集無效。
ERROR_INVALID_PARAMETER
 提供的 參數無效。 其中一個可能性是裝置資訊元素無效。
ERROR_INVALID_REG_PROPERTY
 PropertyKey 所提供的屬性索引鍵無效。
ERROR_INVALID_DATA
 未指定的內部數據值無效。
ERROR_INVALID_USER_BUFFER
 用戶緩衝區無效。 其中一個可能性是 PropertyBuffer 是 NULL ， 而 PropertBufferSize 不是零。
ERROR_NO_SUCH_DEVINST
 DevInfoData 指定的裝置實例不存在。
ERROR_INSUFFICIENT_BUFFER
 PropertyBuffer 緩衝區太小而無法保存要求的屬性值，或傳遞至系統呼叫的內部數據緩衝區太小。
ERROR_NOT_ENOUGH_MEMORY
 沒有足夠的系統記憶體可用來完成作業。
ERROR_NOT_FOUND
 要求的裝置屬性不存在。
ERROR_ACCESS_DENIED
 呼叫端沒有系統管理員許可權。

備註

SetupDiGetDeviceProperty 是 統一裝置屬性模型的一部分。

SetupAPI 僅支援 Unicode 版本的 SetupDiGetDeviceProperty。

若要取得代表為裝置實例設定之裝置屬性的裝置屬性，請呼叫 SetupDiGetDevicePropertyKeys。

若要設定裝置實例屬性，請呼叫 SetupDiSetDeviceProperty。

規格需求

需求 值
最低支援的用戶端 可在 Windows Vista 和更新版本的 Windows 中使用。
目標平台 DesktopFor universal， call CM_Get_DevNode_Property
標頭 setupapi.h (包括 SetupAPI.h)
程式庫 SetupAPI.lib
Dll SetupAPI.dll
API 集合 ext-ms-win-setupapi-classinstallers-l1-1-0 (於 Windows 8)

另請參閱

SetupDiGetDevicePropertyKeys

SetupDiSetDeviceProperty