ObOpenObjectByPointer 函式（ntifs.h）

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 物件類型，而且支援以 Windows 7 星號 CmKeyObjectType 物件類型。

[in] AccessMode

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

如果 AccessModeKernelMode，則不論先前設定驅動程式的任何限制存取為何，系統一律允許要求存取權（例如，POB_PRE_OPERATION_CALLBACK 回呼回呼之前呼叫中受限制的存取）。
如果 AccessModeUserMode，則要求的存取權會與物件的授與存取權進行比較。

[out] Handle

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

傳回值

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

傳回碼	描述
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 只能在至少為檔案物件建立一個句柄之後呼叫。呼叫端可以檢查旗標 FILE_OBJECT 結構的成員，Object 參數所指向。如果已設定FO_HANDLE_CREATED旗標，這表示已為檔案物件建立一或多個句柄，因此可以安全地呼叫 ObOpenObjectByPointer。

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

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