Función ObReferenceObjectByHandleWithTag (wdm.h)

Artículo
08/08/2023

La rutina ObReferenceObjectByHandleWithTag incrementa el recuento de referencias del objeto identificado por el identificador especificado y escribe un valor de etiqueta de cuatro bytes en el objeto para admitir el seguimiento de referencia de objetos.

Sintaxis

NTSTATUS ObReferenceObjectByHandleWithTag(
  [in]            HANDLE                     Handle,
  [in]            ACCESS_MASK                DesiredAccess,
  [in, optional]  POBJECT_TYPE               ObjectType,
  [in]            KPROCESSOR_MODE            AccessMode,
  [in]            ULONG                      Tag,
  [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 al objeto que solicita el autor de la llamada. Este parámetro es una máscara de bits de tipo ACCESS_MASK. La interpretación de este campo depende del tipo de objeto. No use ningún derecho de acceso genérico.

[in, optional] ObjectType

Puntero a una estructura opaca que especifica el tipo de objeto. Este parámetro apunta a una estructura de OBJECT_TYPE . Establezca ObjectType en NULL o en uno de los siguientes valores de puntero, que se declaran en el archivo de encabezado Wdm.h: *ExEventObjectType, *ExSemaphoreObjectType, *IoFileObjectType, *PsProcessType, *PsThreadType, *SeTokenObjectType, *TmEnlistmentObjectType, *TmResourceManagerObjectType, *TmTransactionManagerObjectType o *TmTransactionObjectType. Si ObjectType no es NULL, la rutina comprueba que el tipo de objeto proporcionado coincide con el tipo de objeto del objeto que especifica el parámetro Handle .

[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.

[in] Tag

Especifica un valor de etiqueta personalizada de cuatro bytes. Para obtener más información, vea la sección Comentarios que se muestra más adelante.

[out] Object

Puntero a una variable en la que la rutina escribe un puntero en el objeto . En la tabla siguiente se enumeran los tipos de puntero Object designados por los posibles valores de parámetro ObjectType .

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 parámetro en NULL.

Valor devuelto

ObReferenceObjectByHandleWithTag devuelve STATUS_SUCCESS si la llamada se realiza correctamente. Entre los posibles valores devueltos de error se incluyen los siguientes:

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	El autor de la llamada no tiene los derechos de acceso necesarios para el objeto.
STATUS_INVALID_HANDLE	El identificador especificado no es válido.

Comentarios

Esta rutina tiene acceso a la validación del identificador de objeto especificado. Si se puede conceder acceso, la rutina incrementa el recuento de referencias de objetos y proporciona un puntero de objeto al autor de la llamada. Este incremento impide que el objeto se elimine mientras el autor de la llamada usa el objeto . Cuando el objeto ya no es necesario, el autor de la llamada debe disminuir el recuento de referencias llamando a la rutina ObDereferenceObjectWithTag o ObDereferenceObjectDeferDeleteWithTag .

Para obtener más información sobre las referencias a objetos, vea Ciclo de vida de un objeto.

ObReferenceObjectByHandleWithTag no cierra ni invalida el identificador de objeto especificado por el parámetro Handle . Cuando el identificador ya no es necesario, el autor de la llamada puede cerrar el identificador llamando a la rutina ZwClose .

Si el valor del parámetro AccessMode es KernelMode, siempre se permite el acceso solicitado. Si AccessMode es UserMode, el acceso solicitado se compara con los derechos de acceso que el autor de la llamada tiene en el objeto . Solo los controladores de nivel superior pueden especificar de forma segura el valor UserMode para el parámetro AccessMode .

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.

La rutina ObReferenceObjectByHandle es similar a ObReferenceObjectByHandleWithTag, salvo que no permite al autor de la llamada escribir una etiqueta personalizada en un objeto. En Windows 7 y versiones posteriores de Windows, ObReferenceObjectByHandle siempre escribe un valor de etiqueta predeterminado ('tlfD') en el objeto . Una llamada a ObReferenceObjectByHandle tiene el mismo efecto que una llamada a ObReferenceObjectByHandleWithTag que especifica Tag = 'tlfD'.

Para ver un seguimiento de referencia de objeto en las herramientas de depuración de Windows, use la extensión !obtrace kernel-mode debugger. La extensión !obtrace se mejora para mostrar etiquetas de referencia de objetos, si está habilitado el seguimiento de referencia de objetos. De forma predeterminada, el seguimiento de referencia de objetos está desactivado. Use el Editor global de marcas (Gflags) para habilitar el seguimiento de referencia de objetos. Para obtener más información, vea Seguimiento de referencia de objetos con etiquetas.

Requisitos

Requisito	Value
Cliente mínimo compatible	Disponible en Windows 7 y versiones posteriores del sistema operativo Windows.
Plataforma de destino	Universal
Encabezado	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h, Fltkernel.h)
Library	NtosKrnl.lib
Archivo DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
Reglas de cumplimiento de DDI	HwStorPortProhibitedDIs(storport)