Función ObReferenceObjectByPointerWithTag (wdm.h)
La rutina ObReferenceObjectByPointerWithTag incrementa el recuento de referencias del objeto especificado y escribe un valor de etiqueta de cuatro bytes en el objeto para admitir el seguimiento de referencia de objetos.
Sintaxis
NTSTATUS ObReferenceObjectByPointerWithTag(
[in] PVOID Object,
[in] ACCESS_MASK DesiredAccess,
[in, optional] POBJECT_TYPE ObjectType,
[in] KPROCESSOR_MODE AccessMode,
[in] ULONG Tag
);
Parámetros
[in] Object
Puntero al objeto . El autor de la llamada obtiene este puntero cuando crea el objeto o desde una llamada anterior a la rutina ObReferenceObjectByHandleWithTag después de abrir el 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. Este parámetro puede ser NULL si AccessMode es KernelMode. 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
Indica el modo de acceso que se va a usar para la comprobación de acceso. Establezca este parámetro en uno de los siguientes valores de enumeración MODE :
UserMode
KernelMode
Los controladores de nivel inferior deben especificar KernelMode.
[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.
Valor devuelto
ObReferenceObjectByPointerWithTag devuelve STATUS_SUCCESS si la llamada es correcta. Entre los valores devueltos de error posibles 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 al que apunta el parámetro Object o ObjectType es NULL , pero AccessMode es UserMode. |
Comentarios
Esta rutina tiene acceso a la validación del objeto especificado. Si se puede conceder acceso, la rutina incrementa el recuento de referencias de objetos. 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.
La rutina ObReferenceObjectByPointer es similar a ObReferenceObjectByPointerWithTag, salvo que no permite al autor de la llamada escribir una etiqueta personalizada en un objeto. En Windows 7 y versiones posteriores de Windows, ObReferenceObjectByPointer siempre escribe un valor de etiqueta predeterminado ('tlfD') en el objeto. Una llamada a ObReferenceObjectByPointer tiene el mismo efecto que una llamada a ObReferenceObjectByPointerWithTag que especifica Tag = 'tlfD'.
Para ver un seguimiento de referencia de objetos en las herramientas de depuración de Windows, use la extensión del depurador de modo kernel-obtrace. En Windows 7, 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 de marcas globales (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 | <= DISPATCH_LEVEL |
| Reglas de cumplimiento de DDI | HwStorPortProhibitedDDIs(storport) |