CmCallbackGetKeyObjectIDEx 函式 (wdm.h)
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 |