Función ZwNotifyChangeKey (ntifs.h)

Artículo
01/20/2024

La rutina ZwNotifyChangeKey permite a un controlador solicitar notificaciones cuando cambia una clave del Registro.

Sintaxis

NTSYSAPI NTSTATUS ZwNotifyChangeKey(
  [in]            HANDLE           KeyHandle,
  [in, optional]  HANDLE           Event,
  [in, optional]  PIO_APC_ROUTINE  ApcRoutine,
  [in, optional]  PVOID            ApcContext,
  [out]           PIO_STATUS_BLOCK IoStatusBlock,
  [in]            ULONG            CompletionFilter,
  [in]            BOOLEAN          WatchTree,
  [out, optional] PVOID            Buffer,
  [in]            ULONG            BufferSize,
  [in]            BOOLEAN          Asynchronous
);

Parámetros

[in] KeyHandle

Identificador de la clave para la que se va a registrar una rutina de notificación. Este identificador se crea mediante una llamada correcta a ZwCreateKey o ZwOpenKey. El autor de la llamada debe haber especificado KEY_NOTIFY acceso.

[in, optional] Event

Identificador opcional de un evento creado por el autor de la llamada que se establecerá en el estado Signaled cuando se complete la operación. Si no es NULL, el autor de la llamada se coloca en un estado de espera hasta que la operación se realiza correctamente, en cuyo momento el evento se establece en el estado Signaled.

[in, optional] ApcRoutine

Puntero a una rutina de APC proporcionada por el autor de la llamada para que se ejecute una vez completada la operación. Este parámetro es opcional y puede ser NULL.

[in, optional] ApcContext

Puntero que se pasa como argumento a la rutina de APC a la que apunta ApcRoutine . Este argumento es necesario si ApcRoutine no es NULL y debe convertirse al tipo PVOID. De lo contrario, si ApcRoutine es NULL, establezca este parámetro en NULL también.

El significado de este parámetro depende de si se llama a la rutina desde el modo kernel o desde el modo de usuario:

Para una llamada en modo kernel, establezca este parámetro en uno de los siguientes WORK_QUEUE_TYPE valores de enumeración:
- CriticalWorkQueue
- DelayedWorkQueue
Para una llamada en modo de usuario, este parámetro apunta a un contexto especificado por el autor de la llamada para la rutina de APC.

[out] IoStatusBlock

Puntero a una estructura de IO_STATUS_BLOCK que contiene el estado final e información sobre la operación. Para llamadas correctas que devuelven datos, el número de bytes escritos en Buffer se proporciona en IoStatusBlock-Information>.

[in] CompletionFilter

Máscara de bits de las operaciones que hacen que se notifique al controlador. Especifique una o varias de las marcas siguientes:

Valor	Significado
REG_NOTIFY_CHANGE_NAME	Notificar al autor de la llamada si se agrega o elimina una subclave.
REG_NOTIFY_CHANGE_ATTRIBUTES	Notificar al autor de la llamada los cambios en los atributos de la clave, como la información del descriptor de seguridad.
REG_NOTIFY_CHANGE_LAST_SET	Notificar al autor de la llamada los cambios en un valor de la clave. Esto puede incluir agregar o eliminar un valor, o cambiar un valor existente. (El autor de la llamada no recibe ninguna notificación si el nuevo valor escrito en la clave coincide con el valor anterior de la clave).
REG_NOTIFY_CHANGE_SECURITY	Notificar al autor de la llamada los cambios en el descriptor de seguridad de la clave.

[in] WatchTree

Si es TRUE, se notifica al controlador los cambios en todas las subclaves de la clave especificada. Si es FALSE, el controlador solo se notifica si hay cambios en la clave especificada.

[out, optional] Buffer

Reservado. Especifique NULL.

[in] BufferSize

Reservado. Especifique cero.

[in] Asynchronous

Si es FALSE, la rutina no devuelve hasta que se produce el evento especificado. Si es TRUE, la rutina devuelve inmediatamente.

Valor devuelto

La rutina ZwNotifyChangeKey devuelve STATUS_SUCCESS si se ejecuta correctamente o el valor NTSTATUS adecuado de lo contrario. Si el autor de la llamada especifica TRUE para el parámetro Asincrónico y el evento aún no se ha producido, la rutina devuelve STATUS_PENDING.

Comentarios

Si la llamada a la función ZwNotifyChangeKey se produce en modo de usuario, debe usar el nombre "NtNotifyChangeKey" en lugar de "ZwNotifyChangeKey".

En el caso de las llamadas desde controladores en modo kernel, las versiones NtXxx y ZwXxx de una rutina de Windows Native System Services pueden comportarse de forma diferente en la forma en que controlan e interpretan los parámetros de entrada. Para obtener más información sobre la relación entre las versiones NtXxx y ZwXxx de una rutina, vea Using Nt and Zw Versions of the Native System Services Routines.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows 2000
Plataforma de destino	Universal
Encabezado	ntifs.h (incluya Ntifs.h)
Library	NtosKrnl.lib
Archivo DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
Reglas de cumplimiento de DDI	HwStorPortProhibitedDIs(storport), PowerIrpDDis(wdm)