SetupDiGetClassPropertyKeysExW 函式 (setupapi.h)

  • 發行項

SetupDiGetClassPropertyKeysEx 函式會擷取裝置屬性索引鍵的數位，代表針對裝置安裝類別或本機或遠端電腦上的裝置介面類別所設定的裝置屬性。

語法

WINSETUPAPI BOOL SetupDiGetClassPropertyKeysExW(
  [in]            const GUID *ClassGuid,
  [out, optional] DEVPROPKEY *PropertyKeyArray,
  [in]            DWORD      PropertyKeyCount,
  [out, optional] PDWORD     RequiredPropertyKeyCount,
  [in]            DWORD      Flags,
  [in, optional]  PCWSTR     MachineName,
                  PVOID      Reserved
);

參數

[in] ClassGuid

GUID 的指標，表示裝置安裝類別或裝置介面類別。 SetupDiGetClassPropertyKeysEx 會擷取裝置屬性索引鍵的陣列，代表為指定類別設定的裝置屬性。 如需指定類別類型的詳細資訊，請參閱 Flags 參數。

[out, optional] PropertyKeyArray

緩衝區的指標，接收 DEVPROPKEY 類型的值陣列，其中每個值都是裝置屬性索引鍵，代表為裝置安裝類別設定的裝置屬性。 指標是選擇性的，可以是 NULL。 如需詳細資訊，請參閱本主題稍後的一節。

[in] PropertyKeyCount

PropertyKeyArray 緩衝區的 DEVPROPKEY 類型值大小。 如果 PropertyKeyArray 設定為 NULL，PropertyKeyCount 必須設定為零。

[out, optional] RequiredPropertyKeyCount

接收所要求屬性索引鍵數目的 DWORD 型別變數指標。 指標是選擇性的，可以設定為 NULL。

[in] Flags

下列其中一個值，指定是否要擷取裝置安裝類別類別或裝置介面類別的類別屬性索引鍵。

DICLASSPROP_INSTALLER

ClassGuid 指定裝置安裝類別。 此旗標不能與DICLASSPROP_INTERFACE搭配使用。

DICLASSPROP_INTERFACE

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

[in, optional] MachineName

NULL 終止字串的指標，其中包含計算機的 UNC 名稱，包括 “\” 前置詞。 指標可以是 NULL。 如果指標為 NULL，SetupDiGetClassPropertyKeysEx 會從本機計算機擷取要求的資訊。

警告

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

Reserved

此參數必須設定為 NULL。

傳回值

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

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

傳回碼 Description
ERROR_INVALID_FLAGS
 Flags 的值無效。
ERROR_INVALID_CLASS
 如果指定了DICLASSPROP_INSTALLER旗標，這個錯誤碼表示 ClassGuid 指定的裝置安裝類別不存在。
ERROR_INVALID_REFERENCE_STRING
 ClassGuild 所指定的裝置介面參考字串無效。 指定DICLASSPROP_INTERFACE旗標時，可能會傳回此錯誤。
ERROR_INVALID_DATA
 未指定的數據值無效。 其中一個可能性是 ClassGuid 值無效。
ERROR_INVALID_PARAMETER
 未指定的參數無效。
ERROR_INVALID_USER_BUFFER
 用戶緩衝區無效。 其中一個可能性是 PropertyKeyArray 是 NULL， 而 PropertKeyCount 不是零。
ERROR_INVALID_MACHINENAME
 MachineName 所指定的計算機名稱無效。
ERROR_NO_SUCH_INTERFACE_CLASS
 如果指定了DICLASSPROP_INTERFACE旗標，這個錯誤碼表示 ClassGuid 指定的裝置介面類別不存在。
ERROR_INSUFFICENT_BUFFER
 PropertyKeyArray 緩衝區不夠大，無法保存所有屬性索引鍵，或傳遞至系統呼叫的內部數據緩衝區太小。
ERROR_NOT_ENOUGH_MEMORY
 沒有足夠的系統記憶體可用來完成作業。
ERROR_ACCESS_DENIED
 呼叫端沒有系統管理員許可權。

備註

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

SetupDiGetClassPropertyKeysEx 的呼叫端必須是 Administrators 群組的成員，才能擷取裝置類別的裝置屬性密鑰。

如果 PropertyKeyArray 緩衝區不夠大，無法保存所有要求的屬性索引鍵， 則 SetupDiGetClassPropertyKeysEx 不會擷取任何屬性索引鍵，並傳回ERROR_INSUFFICIENT_BUFFER。 如果呼叫端提供 RequiredPropertyKeyCount 指標， SetupDiGetClassPropertyKeysEx 會將 *RequiredPropertyKeyCount 的值設定為 PropertyKeyArray 緩衝區的 DEVPROPKEY 類型值所需的大小。

若要擷取遠端電腦上的裝置類別屬性，請呼叫 SetupDiGetClassPropertyEx，以及在遠端電腦上設定裝置類別屬性，請呼叫 SetupDiSetClassPropertyEx。

若要擷取本機電腦上的裝置安裝類別或裝置介面類別的屬性索引鍵，請呼叫 SetupDiGetClassPropertyKeys。

規格需求

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

另請參閱

SetupDiGetClassPropertyEx

SetupDiGetClassPropertyKeys

SetupDiSetClassPropertyEx