Función ObReferenceObjectByHandleWithTag (wdm.h)
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) |