Funzione ObOpenObjectByPointer (ntifs.h)

Articolo
08/07/2023

La funzione ObOpenObjectByPointer apre un oggetto a cui fa riferimento un puntatore e restituisce un handle all'oggetto .

Sintassi

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
);

Parametri

[in] Object

Puntatore all'oggetto da aprire.

[in] HandleAttributes

Maschera di bit dei flag che specificano gli attributi desiderati per l'handle dell'oggetto. Se il chiamante non è in esecuzione nel contesto del processo di sistema, questi flag devono includere OBJ_KERNEL_HANDLE. Questo parametro è facoltativo e può essere zero. In caso contrario, si tratta di una combinazione OR'ed di uno o più dei valori seguenti.

Contrassegno	Significato
OBJ_EXCLUSIVE	L'oggetto deve essere aperto per l'accesso esclusivo. Se questo flag è impostato e la chiamata a ObOpenObjectByPointer ha esito positivo, l'oggetto non può essere condiviso e non può essere aperto di nuovo finché l'handle non viene chiuso. Questo flag non è compatibile con il flag di OBJ_INHERIT. Questo flag non è valido per gli oggetti file.
OBJ_FORCE_ACCESS_CHECK	Tutti i controlli di accesso devono essere applicati per l'oggetto, anche se l'oggetto viene aperto in modalità kernel. Se questo flag viene specificato, il valore del parametro AccessMode viene ignorato.
OBJ_INHERIT	L'handle può essere ereditato dai processi figlio del processo corrente. Questo flag non è compatibile con il flag OBJ_EXCLUSIVE.
OBJ_KERNEL_HANDLE	È possibile accedere all'handle solo in modalità kernel. Questo flag deve essere specificato se il chiamante non è in esecuzione nel contesto del processo di sistema.

[in, optional] PassedAccessState

Puntatore a una struttura ACCESS_STATE contenente il contesto del soggetto dell'oggetto, ai tipi di accesso concessi e ai tipi di accesso rimanenti desiderati. Questo parametro è facoltativo e può essere NULL. In una routine di creazione dispatch, questo puntatore è disponibile in IrpSp-Parameters.Create.SecurityContext-AccessState>>, dove IrpSp è un puntatore alla posizione dello stack del chiamante nel provider di risorse. Per altre informazioni, vedere IRP_MJ_CREATE.

[in] DesiredAccess

ACCESS_MASK valore che specifica l'accesso desiderato all'oggetto. Questo parametro è facoltativo e può essere zero.

[in, optional] ObjectType

Puntatore al tipo di oggetto. Se il valore di AccessMode è KernelMode, questo parametro è facoltativo e può essere NULL. In caso contrario, deve essere *ExEventObjectType, *ExSemaphoreObjectType, *IoFileObjectType, *PsThreadType, *SeTokenObjectType o *CmKeyObjectType.

Nota

Il tipo di oggetto SeTokenObjectType è supportato con Windows XP e il tipo di oggetto CmKeyObjectType è supportato con Windows 7.

[in] AccessMode

Modalità di accesso da utilizzare per il controllo di accesso. Questo parametro è obbligatorio e deve essere UserMode o KernelMode:

Se AccessMode è KernelMode, il sistema consente sempre l'accesso richiesto indipendentemente da qualsiasi accesso limitato impostato in precedenza un driver( ad esempio, l'accesso limitato in una chiamata precedente a POB_PRE_OPERATION_CALLBACK callback).
Se AccessMode è UserMode, l'accesso richiesto viene confrontato con l'accesso concesso per l'oggetto.

[out] Handle

Puntatore a una variabile allocata dal chiamante che riceve un handle per l'oggetto .

Valore restituito

ObOpenObjectByPointer restituisce STATUS_SUCCESS o un valore NTSTATUS appropriato, ad esempio uno dei seguenti:

Codice restituito	Descrizione
STATUS_ACCESS_DENIED	Il chiamante non ha avuto l'accesso necessario per aprire un handle per l'oggetto. Si tratta di un codice di errore.
STATUS_INSUFFICIENT_RESOURCES	ObOpenObjectByPointer ha rilevato un errore di allocazione del pool. Si tratta di un codice di errore.
STATUS_INVALID_PARAMETER	È stato specificato un valore di flag non valido nel parametro HandleAttributes . Si tratta di un codice di errore.
STATUS_OBJECT_TYPE_MISMATCH	L'oggetto a cui punta il parametro Object non era del tipo specificato nel parametro ObjectType . Si tratta di un codice di errore.
STATUS_PRIVILEGE_NOT_HELD	Il chiamante non dispone del privilegio necessario per creare un handle con l'accesso specificato nel parametro DesiredAccess . Si tratta di un codice di errore.
STATUS_QUOTA_EXCEEDED	Il chiamante è in esecuzione nel contesto di un processo la cui quota di memoria non è sufficiente per allocare l'handle dell'oggetto. Si tratta di un codice di errore.
STATUS_UNSUCCESSFUL	Impossibile creare l'handle dell'oggetto. Si tratta di un codice di errore.

Commenti

Se il parametro Object punta a un oggetto file , ovvero una struttura FILE_OBJECT, ObOpenObjectByPointer può essere chiamato solo dopo la creazione di almeno un handle per l'oggetto file. I chiamanti possono controllare il membro Flags della struttura FILE_OBJECT a cui punta il parametro Object . Se il flag FO_HANDLE_CREATED è impostato, significa che sono stati creati uno o più handle per l'oggetto file, quindi è possibile chiamare ObOpenObjectByPointer.

Qualsiasi handle ottenuto chiamando ObOpenObjectByPointer deve essere rilasciato chiamando ZwClose.

Le routine del driver eseguite in un contesto di processo diverso da quello del processo di sistema devono impostare il flag OBJ_KERNEL_HANDLE nel parametro HandleAttributes . Ciò limita l'uso dell'handle restituito da ObOpenObjectByPointer ai processi in esecuzione in modalità kernel. In caso contrario, l'handle può essere accessibile dal processo nel cui contesto è in esecuzione il driver.