SetupDiGetClassPropertyExW 函式 (setupapi.h)

發行項
03/05/2024

SetupDiGetClassPropertyEx 函式會擷取本機或遠端電腦上裝置安裝類別或裝置介面類別的類別屬性。

語法

WINSETUPAPI BOOL SetupDiGetClassPropertyExW(
  [in]            const GUID       *ClassGuid,
  [in]            const DEVPROPKEY *PropertyKey,
  [out]           DEVPROPTYPE      *PropertyType,
  [out, optional] PBYTE            PropertyBuffer,
  [in]            DWORD            PropertyBufferSize,
  [out, optional] PDWORD           RequiredSize,
  [in]            DWORD            Flags,
  [in, optional]  PCWSTR           MachineName,
                  PVOID            Reserved
);

參數

[in] ClassGuid

GUID 的指標，識別要為其擷取裝置類別之裝置屬性的裝置安裝類別或裝置介面類別。如需指定類別類型的相關信息，請參閱 Flags 參數。

[in] PropertyKey

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

[out] PropertyType

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

[out, optional] PropertyBuffer

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

[in] PropertyBufferSize

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

[out, optional] RequiredSize

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

[in] Flags

下列其中一個值，指定類別是裝置安裝類別還是裝置介面類別：

DICLASSPROP_INSTALLER

ClassGuid 會指定裝置設定類別。此旗標無法與DICLASSPROP_INTERFACE搭配使用。

DICLASSPROP_INTERFACE

ClassGuid 指定裝置介面類別。此旗標無法與DICLASSPROP_INSTALLER搭配使用。

[in, optional] MachineName

NULL 終止字串的指標，其中包含計算機的 UNC 名稱，包括 “\” 前置詞。指標可以設定為 NULL。如果 MachineName 為 NULL，SetupDiGetClassPropertyEx 會從本機電腦擷取要求的裝置類別屬性。

警告

從 Windows 8 和 Windows Server 2012 開始，不支援使用此函式來存取遠端計算機，因為此功能已移除。

Reserved

此參數必須設定為 NULL。

傳回值

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

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

傳回碼	Description
ERROR_INVALID_FLAGS	Flags 的值不是零。
ERROR_INVALID_CLASS	ClassGuid 指定的裝置安裝類別無效。只有在指定DICLASSPROP_INSTALLER旗標時，才會發生此錯誤。
ERROR_INVALID_PARAMETER	未指定的參數無效。
ERROR_INVALID_REG_PROPERTY	PropertyKey 所提供的屬性索引鍵無效。
ERROR_INVALID_REFERENCE_STRING	裝置介面參考字串無效。如果指定DICLASSPROP_INTERFACE旗標，則可以傳回此錯誤。
ERROR_INVALID_DATA	未指定的內部數據值無效。
ERROR_INVALID_USER_BUFFER	用戶緩衝區無效。其中一個可能性是 PropertyBuffer 是 NULL，而 PropertyBufferSize 不是零。
ERROR_INVALID_MACHINENAME	MachineName 所指定的計算機名稱無效。
ERROR_NO_SUCH_INTERFACE_CLASS	ClassGuid 指定的裝置介面類別不存在。只有在指定DICLASSPROP_INTERFACE旗標時，才會發生此錯誤。
ERROR_INSUFFICIENT_BUFFER	傳遞至系統呼叫的內部數據緩衝區太小。
ERROR_NOT_ENOUGH_MEMORY	沒有足夠的系統記憶體可用來完成作業。
ERROR_NOT_FOUND	要求的裝置屬性不存在。
ERROR_ACCESS_DENIED	呼叫端沒有系統管理員許可權。

備註

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

SetupAPI 僅支援 SetupDiGetClassPropertyEx 的 Unicode 版本。

SetupDiGetClassPropertyEx 的呼叫端必須是 Administrators 群組的成員，才能設定裝置介面屬性。

若要取得代表遠端電腦上裝置類別所設定裝置屬性的裝置屬性，請呼叫 SetupDiGetClassPropertyKeysEx。

若要擷取本機電腦上的裝置類別屬性，請呼叫 SetupDiGetClassProperty。

若要在本機計算機上設定裝置類別屬性，請呼叫 SetupDiSetClassProperty，以及在遠端電腦上設定裝置類別屬性，請呼叫 SetupDiSetClassPropertyEx。

規格需求

需求	值
最低支援的用戶端	適用於 Windows Vista 和更新版本的 Windows。
目標平台	DesktopFor universal， call CM_Get_Class_Property_ExW
標頭	setupapi.h (包括 Setupapi.h)
程式庫	Setupapi.lib