CmCallbackGetKeyObjectIDEx 函式 (wdm.h)

發行項
02/27/2024

CmCallbackGetKeyObjectIDEx 例程會擷取與指定登錄機碼對象相關聯的唯一標識碼和物件名稱。

從 Windows 8 開始，即可使用此例程。在舊版 Windows 中，請改用 CmCallbackGetKeyObjectID 例程。如需詳細資訊，請參閱下面的＜備註＞一節。

語法

NTSTATUS CmCallbackGetKeyObjectIDEx(
  [in]            PLARGE_INTEGER   Cookie,
  [in]            PVOID            Object,
  [out, optional] PULONG_PTR       ObjectID,
  [out, optional] PCUNICODE_STRING *ObjectName,
  [in]            ULONG            Flags
);

參數

[in] Cookie

Cookie 值，表示要接收登錄篩選回呼的呼叫端註冊。驅動程式先前已從 CmRegisterCallback 或 CmRegisterCallbackEx 例程取得此 Cookie 值。

[in] Object

登錄機碼物件的指標。此參數是驅動程式的 RegistryCallback 回呼例程在其中一個 REG_XXX_KEY_INFORMATION 結構之 Object 成員中收到的指標值。

警告

在某些情況下，登錄回呼通知結構可能包含無效的非 NULL 物件指標。登錄篩選驅動程式不得將這類指標傳遞至此例程。如需詳細資訊，請參閱登錄通知中的無效索引鍵對象指標。

[out, optional] ObjectID

指向位置的指標，該位置會接收 Object 所代表之登錄機碼標識碼的指標。此標識碼在登錄中的所有機碼中都是唯一的。這個參數是選擇性的，而且可以是 NULL。如需詳細資訊，請參閱下面的一節。

[out, optional] ObjectName

接收 UNICODE_STRING 結構指標之位置的指標。這個結構包含 Object 指定之登錄機碼對象名稱。物件名稱實際上是物件所代表登錄機碼的完整路徑名稱。呼叫端負責呼叫 CmCallbackReleaseKeyObjectIDEx 例程來釋放此結構。這個參數是選擇性的，而且可以是 NULL。如需詳細資訊，請參閱＜備註＞。

[in] Flags

保留的。設定為零。

傳回值

如果作業成功，CmCallbackGetKeyObjectIDEx 會傳回STATUS_SUCCESS。可能的錯誤傳回值包括下列狀態代碼：

傳回碼	Description
STATUS_INVALID_PARAMETER	Cookie、物件或 Flags 參數無效。

備註

驅動程式可以使用 CmCallbackGetKeyObjectIDEx 來取得登錄機碼標識碼、物件名稱或兩者，方法是提供 ObjectID 或 ObjectName 參數的非 NULL 值。

呼叫端可以透過 ObjectID 參數取得金鑰標識碼。如果兩個登錄機碼物件代表相同的登錄機碼，則從兩個物件的 CmCallbackGetKeyObjectIDEx 取得的機碼標識碼完全相同。如果登錄機碼的名稱變更，則從 CmCallbackGetKeyObjectIDEx 取得的密鑰標識子不會變更。呼叫端可以使用機碼標識碼，可靠地追蹤透過多個機碼物件對特定登錄機碼進行的存取，甚至是跨登錄機碼名稱的變更。

呼叫端可以透過 ObjectName 參數取得物件名稱。包含物件名稱 的UNICODE_STRING 結構的記憶體會維持有效狀態，直到呼叫端呼叫 CmCallbackReleaseKeyObjectIDEx 以釋放結構為止。

CmCallbackGetKeyObjectIDEx 是 CmCallbackGetKeyObjectID 例程的改良版本，從 Windows Vista 開始提供。在早於 Windows 8 版本的 Windows 中執行的驅動程式應該呼叫 CmCallbackGetKeyObjectID，而不是 CmCallbackGetKeyObjectIDEx。只有在 Windows 8 和更新版本的 Windows 中執行的驅動程式應該呼叫 CmCallbackGetKeyObjectIDEx，而不是 CmCallbackGetKeyObjectID。

CmCallbackGetKeyObjectIDEx 有兩個重要功能，無法從 CmCallbackGetKeyObjectID 取得。

首先， CmCallbackGetKeyObjectIDEx 可讓登錄篩選驅動程序明確控制 ObjectName 結構的存留期。驅動程式可以隨時呼叫 CmCallbackReleaseKeyObjectIDEx 以釋放此結構。相反地，驅動程式無法明確釋放從 CmCallbackGetKeyObjectID 收到的 ObjectName 結構。當索引鍵的所有句柄關閉時，會自動釋放這個結構。

其次，如果登錄篩選驅動程式呼叫 CmCallbackGetKeyObjectID 以取得 ObjectName 結構指標，而且在此呼叫之後，登錄機碼的名稱會變更， 後續對 CmCallbackGetKeyObjectID 的呼叫會取得 ObjectName 結構過時複本的指標，其中包含舊的機碼名稱。此結構的過時複本會持續存在，直到關閉密鑰的所有句柄為止。相反地，從 CmCallbackGetKeyObjectIDEx 取得的 ObjectName 結構一律包含最新的密鑰名稱。

如需登錄篩選驅動程式的詳細資訊，請參閱篩選登錄呼叫。

規格需求

需求	值
最低支援的用戶端	從 Windows 8 開始提供。
目標平台	Universal
標頭	wdm.h (包括 Wdm.h、Ntddk.h、Ntifs.h)
程式庫	NtosKrnl.lib
Dll	NtosKrnl.exe
IRQL	IRQL <= APC_LEVEL