ObOpenObjectByPointer 函式 (ntifs.h)

發行項
02/26/2024

ObOpenObjectByPointer 函式會開啟指標所參考的物件，並傳回物件的句柄。

語法

NTSTATUS ObOpenObjectByPointer(
  [in]           PVOID           Object,
  [in]           ULONG           HandleAttributes,
  [in, optional] PACCESS_STATE   PassedAccessState,
  [in]           ACCESS_MASK     DesiredAccess,
  [in, optional] POBJECT_TYPE    ObjectType,
  [in]           KPROCESSOR_MODE AccessMode,
  [out]          PHANDLE         Handle
);

參數

[in] Object

要開啟之物件的指標。

[in] HandleAttributes

旗標的位掩碼，指定物件句柄所需的屬性。如果呼叫端未在系統進程內容中執行，這些旗標必須包含OBJ_KERNEL_HANDLE。此參數是選擇性的，而且可以是零。否則，它是下列一或多個值的 OR 組合。

旗標	意義
OBJ_EXCLUSIVE	對象要開啟以供獨佔存取。如果已設定此旗標，且對 ObOpenObjectByPointer 的呼叫成功，則對象無法共用，而且無法在句柄關閉之前再次開啟。此旗標與 OBJ_INHERIT 旗標不相容。此旗標對檔案物件無效。
OBJ_FORCE_ACCESS_CHECK	即使物件是以核心模式開啟，所有存取檢查都會強制執行物件。如果指定這個旗標，則會忽略 AccessMode 參數的值。
OBJ_INHERIT	句柄可由目前進程的子進程繼承。此旗標與 OBJ_EXCLUSIVE 旗標不相容。
OBJ_KERNEL_HANDLE	句柄只能在核心模式中存取。如果呼叫端未在系統進程內容中執行，則必須指定這個旗標。

[in, optional] PassedAccessState

包含對象主體內容、授與存取類型，以及剩餘所需存取類型的 ACCESS_STATE 結構的指標。此參數是選擇性的，可以是 NULL。在建立分派例程中，您可以在 IrpSp-Parameters.Create.SecurityContext-AccessState>> 中找到此指標，其中 IrpSp 是 IRP 中呼叫端本身堆疊位置的指標。 (如需詳細資訊，請參閱 IRP_MJ_CREATE.)

[in] DesiredAccess

ACCESS_MASK 值，指定物件所需的存取權。此參數是選擇性的，而且可以是零。

[in, optional] ObjectType

物件類型的指標。如果 AccessMode 的值是 KernelMode，這個參數是選擇性的，而且可以是 NULL。否則，它必須是 *ExEventObjectType、*ExSemaphoreObjectType、*IoFileObjectType、*PsThreadType、*SeTokenObjectType 或 *CmKeyObjectType。

注意

Windows XP 支援 SeTokenObjectType 物件類型，而 CmKeyObjectType 物件類型則支援以 Windows 7 為星號。

[in] AccessMode

要用於存取檢查的存取模式。此參數是必要的，而且必須是 UserMode 或 KernelMode：

如果 AccessMode 是 KernelMode，系統一律允許要求的存取權，不論先前設定驅動程式 (的任何限制存取，例如，在先前呼叫中限制存取 POB_PRE_OPERATION_CALLBACK回呼) 。
如果 AccessMode 是 UserMode，則要求的存取權會與物件的授與存取權進行比較。

[out] Handle

接收物件句柄之呼叫端配置的變數指標。

傳回值

ObOpenObjectByPointer 會傳回STATUS_SUCCESS或適當的 NTSTATUS 值，例如下列其中一項：

傳回碼	Description
STATUS_ACCESS_DENIED	呼叫端沒有開啟物件句柄的必要存取權。這是錯誤碼。
STATUS_INSUFFICIENT_RESOURCES	ObOpenObjectByPointer 發生集區配置失敗。這是錯誤碼。
STATUS_INVALID_PARAMETER	HandleAttributes 參數中指定了無效的旗標值。這是錯誤碼。
STATUS_OBJECT_TYPE_MISMATCH	Object 參數所指向的物件不是 ObjectType 參數中指定的類型。這是錯誤碼。
STATUS_PRIVILEGE_NOT_HELD	呼叫端沒有建立具有 DesiredAccess 參數中所指定存取權的必要許可權。這是錯誤碼。
STATUS_QUOTA_EXCEEDED	呼叫端是在記憶體配額不足以配置物件句柄的進程內容中執行。這是錯誤碼。
STATUS_UNSUCCESSFUL	無法建立物件句柄。這是錯誤碼。

備註

如果 Object 參數指向檔案物件 (，則FILE_OBJECT結構) ，只有在至少為檔案物件建立一個句柄之後，才能呼叫 ObOpenObjectByPointer 。呼叫端可以檢查 Object 參數指向之FILE_OBJECT結構的 Flags 成員。如果已設定FO_HANDLE_CREATED旗標，這表示已為檔案物件建立一或多個句柄，因此呼叫 ObOpenObjectByPointer 是安全的。

呼叫 ObOpenObjectByPointer 取得的任何句柄最終都必須藉由呼叫 ZwClose 來釋放。

在系統進程以外的進程內容中執行的驅動程式例程必須在 HandleAttributes 參數中設定OBJ_KERNEL_HANDLE旗標。這會限制 使用 ObOpenObjectByPointer 所傳回的句柄，以核心模式執行的進程。否則，進程可以在其中執行驅動程序的內容中存取句柄。