Función ObReferenceObjectByHandle (wdm.h)

  • Artículo

La rutina ObReferenceObjectByHandle proporciona validación de acceso en el identificador de objeto y, si se puede conceder acceso, devuelve el puntero correspondiente al cuerpo del objeto.

Sintaxis

NTSTATUS ObReferenceObjectByHandle(
  [in]            HANDLE                     Handle,
  [in]            ACCESS_MASK                DesiredAccess,
  [in, optional]  POBJECT_TYPE               ObjectType,
  [in]            KPROCESSOR_MODE            AccessMode,
  [out]           PVOID                      *Object,
  [out, optional] POBJECT_HANDLE_INFORMATION HandleInformation
);

Parámetros

[in] Handle

Especifica un identificador abierto para un objeto .

[in] DesiredAccess

Especifica los tipos de acceso solicitados al objeto . La interpretación de este campo depende del tipo de objeto. No use ningún derecho de acceso genérico. Para obtener más información, consulte ACCESS_MASK.

[in, optional] ObjectType

Puntero al tipo de objeto. ObjectType puede ser *ExEventObjectType, *ExSemaphoreObjectType, *IoFileObjectType, *PsProcessType, *PsThreadType, *SeTokenObjectType, *TmEnlistmentObjectType, *TmResourceManagerObjectType, *TmTransactionManagerObjectType o *TmTransactionObjectType.

Si ObjectType no es NULL, el sistema operativo comprueba que el tipo de objeto proporcionado coincide con el tipo de objeto del objeto que handle especifica.

[in] AccessMode

Especifica el modo de acceso que se va a usar para la comprobación de acceso. Debe ser UserMode o KernelMode. Los controladores siempre deben especificar UserMode para los identificadores que reciben del espacio de direcciones del usuario.

[out] Object

Puntero a una variable que recibe un puntero al cuerpo del objeto. La tabla siguiente contiene los tipos de puntero.

Parámetro ObjectType Tipo de puntero de objeto
*ExEventObjectType PKEVENT
*ExSemaphoreObjectType PKSEMAPHORE
*IoFileObjectType PFILE_OBJECT
*PsProcessType PEPROCESS o PKPROCESS
*PsThreadType PETHREAD o PKTHREAD
*SeTokenObjectType PACCESS_TOKEN
*TmEnlistmentObjectType PKENLISTMENT
*TmResourceManagerObjectType PKRESOURCEMANAGER
*TmTransactionManagerObjectType PKTM
*TmTransactionObjectType PKTRANSACTION

Las estructuras a las que hacen referencia los tipos de puntero son opacas y los controladores no pueden acceder a los miembros de la estructura. Dado que las estructuras son opacas, PEPROCESS es equivalente a PKPROCESS y PETHREAD es equivalente a PKTHREAD.

[out, optional] HandleInformation

Los controladores establecen este valor en NULL.

Valor devuelto

ObReferenceObjectByHandle devuelve STATUS_SUCCESS si la llamada se realiza correctamente. Entre los posibles valores devueltos se incluyen los siguientes códigos de error:

Código devuelto Descripción
STATUS_OBJECT_TYPE_MISMATCH El parámetro ObjectType especifica el tipo de objeto incorrecto para el objeto identificado por el parámetro Handle .
STATUS_ACCESS_DENIED No se puede conceder al autor de la llamada los derechos de acceso solicitados al objeto .
STATUS_INVALID_HANDLE El parámetro Handle no es un identificador de objeto válido.

Comentarios

Un puntero al cuerpo del objeto se recupera de la entrada de la tabla de objetos y se devuelve al autor de la llamada mediante el parámetro Object .

Si AccessMode es UserMode, el acceso solicitado se compara con el acceso concedido para el objeto. Si AccessMode es KernelMode, el identificador debe originarse en el espacio de direcciones del kernel.

A partir de Windows 7, si AccessMode es KernelMode y se recibe el identificador del espacio de direcciones del usuario, el comprobador de controladores emite la comprobación de errores C4, subcódigo F6.

Si la llamada se realiza correctamente, se devuelve un puntero al cuerpo del objeto al autor de la llamada y se incrementa el recuento de referencias del puntero. Al incrementar este recuento, se impide que se elimine el objeto mientras se hace referencia al puntero. El autor de la llamada debe disminuir el recuento de referencias con ObDereferenceObject tan pronto como se haga con el objeto .

Requisitos

Requisito Value
Cliente mínimo compatible Disponible a partir de Windows 2000.
Plataforma de destino Universal
Encabezado wdm.h (incluya Wdm.h, Ntddk.h, Ntifs.h)
Library NtosKrnl.lib
Archivo DLL NtosKrnl.exe
IRQL PASSIVE_LEVEL
Reglas de cumplimiento de DDI HwStorPortProhibitedDIs(storport), IrqlObPassive(wdm), TargetRelationNeedsRef(wdm)

Consulte también

ACCESS_MASK

ObDereferenceObject

ObReferenceObject

ObReferenceObjectByPointer