Función CmCallbackGetKeyObjectIDEx (wdm.h)
La rutina CmCallbackGetKeyObjectIDEx recupera el identificador único y el nombre de objeto asociados a un objeto de clave del Registro especificado.
Esta rutina está disponible a partir de Windows 8. En versiones anteriores de Windows, usa la rutina CmCallbackGetKeyObjectID en su lugar. Para obtener más información, vea la sección Comentarios a continuación.
Sintaxis
NTSTATUS CmCallbackGetKeyObjectIDEx(
[in] PLARGE_INTEGER Cookie,
[in] PVOID Object,
[out, optional] PULONG_PTR ObjectID,
[out, optional] PCUNICODE_STRING *ObjectName,
[in] ULONG Flags
);
Parámetros
[in] Cookie
Valor de cookie que representa el registro del autor de la llamada para recibir devoluciones de llamada de filtro del Registro. El controlador obtuvo previamente este valor de cookie de la rutina CmRegisterCallback o CmRegisterCallbackEx .
[in] Object
Puntero al objeto de clave del Registro. Este parámetro es el valor de puntero que la rutina de devolución de llamada RegistryCallback del controlador recibió en el miembro Object de una de las estructuras REG_XXX_KEY_INFORMATION .
Advertencia
En determinadas circunstancias, las estructuras de notificación de devolución de llamada del Registro pueden contener punteros de objeto no NULL no válidos. Los controladores de filtrado del Registro no deben pasar estos punteros a esta rutina. Para obtener más información, vea Punteros de objeto de clave no válidos en notificaciones del Registro.
[out, optional] ObjectID
Puntero a una ubicación que recibe un puntero al identificador de clave de la clave del Registro que representa Object . Este identificador es único en todas las claves del Registro. Este parámetro es opcional y puede ser NULL. Para obtener más información, vea la sección Comentarios a continuación.
[out, optional] ObjectName
Puntero a una ubicación que recibe un puntero a una estructura UNICODE_STRING . Esta estructura contiene el nombre de objeto del objeto de clave del Registro que especifica Object . El nombre del objeto es realmente el nombre de ruta de acceso completa de la clave del Registro que representa el objeto. El autor de la llamada es responsable de liberar esta estructura llamando a la rutina CmCallbackReleaseKeyObjectIDEx . Este parámetro es opcional y puede ser NULL. Para obtener más información, vea la sección Comentarios.
[in] Flags
Reservado. Establecer en cero.
Valor devuelto
CmCallbackGetKeyObjectIDEx devuelve STATUS_SUCCESS si la operación se realiza correctamente. Entre los posibles valores devueltos de error se incluyen el siguiente código de estado:
| Código devuelto | Descripción |
|---|---|
| STATUS_INVALID_PARAMETER | El parámetro Cookie, Object o Flags no es válido. |
Comentarios
Los controladores pueden usar CmCallbackGetKeyObjectIDEx para obtener el identificador de clave del Registro, el nombre del objeto o ambos, proporcionando valores no NULL para los parámetros ObjectID o ObjectName .
El autor de la llamada puede obtener el identificador de clave mediante el parámetro ObjectID . Si dos objetos de clave del Registro representan la misma clave del Registro, los identificadores de clave obtenidos de CmCallbackGetKeyObjectIDEx para los dos objetos son idénticos. Si cambia el nombre de la clave del Registro, el identificador de clave obtenido de CmCallbackGetKeyObjectIDEx no cambia. El autor de la llamada puede usar el identificador de clave para realizar un seguimiento confiable de los accesos realizados en una clave del Registro determinada a través de varios objetos de clave e incluso a través de cambios en el nombre de la clave del Registro.
El autor de la llamada puede obtener el nombre del objeto mediante el parámetro ObjectName . El almacenamiento de la estructura UNICODE_STRING que contiene el nombre del objeto sigue siendo válido hasta que el autor de la llamada llama a CmCallbackReleaseKeyObjectIDEx para liberar la estructura.
CmCallbackGetKeyObjectIDEx es una versión mejorada de la rutina CmCallbackGetKeyObjectID , que está disponible a partir de Windows Vista. Los controladores que se ejecutan en versiones de Windows anteriores a Windows 8 deben llamar a CmCallbackGetKeyObjectID en lugar de CmCallbackGetKeyObjectIDEx. Los controladores que solo se ejecutan en Windows 8 y versiones posteriores de Windows deben llamar a CmCallbackGetKeyObjectIDEx en lugar de CmCallbackGetKeyObjectID.
CmCallbackGetKeyObjectIDEx tiene dos características importantes que no están disponibles en CmCallbackGetKeyObjectID.
En primer lugar, CmCallbackGetKeyObjectIDEx permite que un controlador de filtro del Registro controle explícitamente la duración de la estructura ObjectName . El controlador puede llamar a CmCallbackReleaseKeyObjectIDEx en cualquier momento para liberar esta estructura. Por el contrario, el controlador no puede liberar explícitamente la estructura ObjectName recibida de CmCallbackGetKeyObjectID. Esta estructura se libera automáticamente cuando se cierran todos los identificadores de la clave.
En segundo lugar, si un controlador de filtro del Registro llama a CmCallbackGetKeyObjectID para obtener un puntero de estructura ObjectName y, después de esta llamada, el nombre de la clave del Registro cambia, las llamadas posteriores a CmCallbackGetKeyObjectID obtienen un puntero a una copia obsoleta de la estructura ObjectName , que contiene el nombre de clave anterior. La copia obsoleta de esta estructura persiste hasta que se cierran todos los identificadores de la clave. En cambio, la estructura ObjectName obtenida de CmCallbackGetKeyObjectIDEx siempre contiene el nombre de clave más actualizado.
Para obtener más información sobre los controladores de filtro del Registro, consulte Filtrado de llamadas del Registro.
Requisitos
| Requisito | Value |
|---|---|
| Cliente mínimo compatible | Disponible a partir de Windows 8. |
| Plataforma de destino | Universal |
| Encabezado | wdm.h (incluya Wdm.h, Ntddk.h, Ntifs.h) |
| Library | NtosKrnl.lib |
| Archivo DLL | NtosKrnl.exe |
| IRQL | IRQL <= APC_LEVEL |