cmCallbackGetKeyObjectID 函式 (wdm.h)

發行項
02/27/2024

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

從 Windows 8 開始，登錄篩選驅動程式應該呼叫 CmCallbackGetKeyObjectIDEx 例程，而不是 CmCallbackGetKeyObjectID。如需詳細資訊，請參閱下面的＜備註＞一節。

語法

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

參數

[in] Cookie

驅動程式先前透過呼叫 CmRegisterCallback 或 CmRegisterCallbackEx 例程取得的 Cookie 值。

[in] Object

驅動程式的 RegistryCallback 回呼例程在其中一個REG_XXX 的 Object 成員中收到的指標值_KEY_INFORMATION結構。

警告

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

[out, optional] ObjectID

位置的指標，接收 代表 Object 所指定登錄機碼的唯一標識符指標。這個參數是選擇性的，而且可以是 NULL。

[out, optional] ObjectName

接收 UNICODE_STRING 結構指標之位置的指標。這個結構包含 Object 指定之登錄機碼對象名稱。物件名稱實際上是物件所代表登錄機碼的完整路徑名稱。呼叫端不得寫入此 UNICODE_STRING 結構或釋放它。這個參數是選擇性的，而且可以是 NULL。

傳回值

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

傳回碼	Description
STATUS_INVALID_PARAMETER	Cookie 或 Object 參數無效。

備註

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

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

在驅動程式取得標識碼或名稱之後，標識碼或名稱會有效，直到驅動程式的 RegistryCallback 例程收到句柄關閉的預先通知為止。

驅動程式不得修改物件名稱。

如果兩個登錄機碼物件代表相同的登錄機碼，則兩個物件的機碼標識符相同。

如需 CmCallbackGetKeyObjectID 和登錄篩選作業的詳細資訊，請參閱篩選登錄呼叫。