Función ReadDirectoryChangesExW (winbase.h)

Artículo
08/27/2023

Recupera información que describe los cambios en el directorio especificado, que puede incluir información ampliada si se especifica ese tipo de información. La función no notifica cambios en el propio directorio especificado.

Para hacer un seguimiento de los cambios en un volumen, consulte los diarios de cambios.

Sintaxis

BOOL ReadDirectoryChangesExW(
  [in]                HANDLE                                  hDirectory,
  [out]               LPVOID                                  lpBuffer,
  [in]                DWORD                                   nBufferLength,
  [in]                BOOL                                    bWatchSubtree,
  [in]                DWORD                                   dwNotifyFilter,
  [out, optional]     LPDWORD                                 lpBytesReturned,
  [in, out, optional] LPOVERLAPPED                            lpOverlapped,
  [in, optional]      LPOVERLAPPED_COMPLETION_ROUTINE         lpCompletionRoutine,
  [in]                READ_DIRECTORY_NOTIFY_INFORMATION_CLASS ReadDirectoryNotifyInformationClass
);

Parámetros

[in] hDirectory

Identificador del directorio que se va a supervisar. Este directorio debe abrirse con el derecho de acceso FILE_LIST_DIRECTORY o un derecho de acceso como GENERIC_READ que incluya el derecho de acceso FILE_LIST_DIRECTORY .

[out] lpBuffer

Puntero al búfer con formato alineado con DWORD en el que ReadDirectoryChangesExW debe devolver los resultados de lectura. La estructura de este búfer se define mediante la estructura FILE_NOTIFY_EXTENDED_INFORMATION si el valor del parámetro ReadDirectoryNotifyInformationClass es ReadDirectoryNotifyExtendedInformation o por la estructura FILE_NOTIFY_INFORMATION si ReadDirectoryNotifyInformationClass es ReadDirectoryNotifyInformationInformation.

Este búfer se rellena de forma sincrónica o asincrónica, en función de cómo se abra el directorio y de qué valor se proporcione al parámetro lpOverlapped . Para obtener más información, vea la sección Comentarios.

[in] nBufferLength

Tamaño del búfer al que apunta el parámetro lpBuffer , en bytes.

[in] bWatchSubtree

Si este parámetro es TRUE, la función supervisa el árbol de directorios raíz en el directorio especificado. Si este parámetro es FALSE, la función supervisa solo el directorio especificado por el parámetro hDirectory .

[in] dwNotifyFilter

Criterios de filtro que comprueba la función para determinar si se ha completado la operación de espera. Este parámetro puede ser uno o más de los siguientes valores.

Valor	Significado
FILE_NOTIFY_CHANGE_FILE_NAME 0x00000001	Cualquier cambio de nombre de archivo en el directorio o subárbol inspeccionados provoca la devolución de una operación de espera de la notificación del cambio. Los cambios incluyen cambiar el nombre, crear o eliminar un archivo.
FILE_NOTIFY_CHANGE_DIR_NAME 0x00000002	Cualquier cambio de nombre de directorio en el directorio o subárbol supervisado hace que se devuelva una operación de espera de notificación de cambio. Los cambios incluyen la creación o eliminación de un directorio.
FILE_NOTIFY_CHANGE_ATTRIBUTES 0x00000004	Cualquier cambio de atributo en el directorio o subárbol inspeccionados provoca la devolución de una operación de espera de la notificación del cambio.
FILE_NOTIFY_CHANGE_SIZE 0x00000008	Cualquier cambio de tamaño de archivo en el directorio o subárbol inspeccionados provoca la devolución de una operación de espera de la notificación del cambio. El sistema operativo detecta un cambio en el tamaño de archivo solo cuando el archivo se escribe en el disco. Para los sistemas operativos que usan el almacenamiento en caché completo, la detección solo aparece cuando la memoria caché se vacía suficientemente.
FILE_NOTIFY_CHANGE_LAST_WRITE 0x00000010	Cualquier cambio de la última escritura de los archivos en el directorio o subárbol inspeccionados provoca la devolución de una operación de espera de la notificación del cambio. El sistema operativo detecta un cambio en la última escritura solo cuando el archivo se escribe en el disco. Para los sistemas operativos que usan el almacenamiento en caché completo, la detección solo aparece cuando la memoria caché se vacía suficientemente.
FILE_NOTIFY_CHANGE_LAST_ACCESS 0x00000020	Cualquier cambio en la última hora de acceso de los archivos en el directorio o subárbol supervisado hace que se devuelva una operación de espera de notificación de cambio.
FILE_NOTIFY_CHANGE_CREATION 0x00000040	Cualquier cambio en la hora de creación de archivos en el directorio o subárbol supervisado hace que se devuelva una operación de espera de notificación de cambio.
FILE_NOTIFY_CHANGE_SECURITY 0x00000100	Cualquier cambio de descriptor de seguridad en el directorio o subárbol supervisado hace que se devuelva una operación de espera de notificación de cambio.

[out, optional] lpBytesReturned

Para las llamadas sincrónicas, este parámetro recibe el número de bytes transferidos al parámetro lpBuffer . Para las llamadas asincrónicas, este parámetro no está definido. Debe usar una técnica de notificación asincrónica para recuperar el número de bytes transferidos.

[in, out, optional] lpOverlapped

Puntero a una estructura SUPERPUESTA que proporciona datos que se usarán durante la operación asincrónica. De lo contrario, este valor es NULL. No se usan los miembros Offset y OffsetHigh de esta estructura.

[in, optional] lpCompletionRoutine

Puntero a una rutina de finalización a la que se llamará cuando se haya completado o cancelado la operación y el subproceso de llamada esté en un estado de espera alertable. Para obtener más información sobre esta rutina de finalización, vea FileIOCompletionRoutine.

[in] ReadDirectoryNotifyInformationClass

Tipo de información que ReadDirectoryChangesExW debe escribir en el búfer en el que apunta el parámetro lpBuffer . Especifique ReadDirectoryNotifyInformation para indicar que la información debe constar de estructuras de FILE_NOTIFY_INFORMATION o ReadDirectoryNotifyExtendedInformation para indicar que la información debe constar de estructuras de FILE_NOTIFY_EXTENDED_INFORMATION .

Valor devuelto

Si la función se realiza correctamente, el valor devuelto es distinto de cero. Para las llamadas sincrónicas, esto significa que la operación se realizó correctamente. Para las llamadas asincrónicas, esto indica que la operación se puso en cola correctamente.

Si la función no se realiza correctamente, el valor devuelto es cero. Para obtener información de error extendida, llame a GetLastError.

Si el redirector de red o el sistema de archivos de destino no admiten esta operación, se produce un error en la función con ERROR_INVALID_FUNCTION.

Comentarios

Para obtener un identificador en un directorio, use la función CreateFile con la marca FILE_FLAG_BACKUP_SEMANTICS .

Una llamada a ReadDirectoryChangesExW se puede completar de forma sincrónica o asincrónica. Para especificar la finalización asincrónica, abra el directorio con CreateFile como se muestra anteriormente, pero especifique además el atributo FILE_FLAG_OVERLAPPED en el parámetro dwFlagsAndAttributes . A continuación, especifique una estructura SUPERPUESTA cuando llame a ReadDirectoryChangesExW.

Cuando se llama por primera vez a ReadDirectoryChangesExW, el sistema asigna un búfer para almacenar información de cambio. Este búfer está asociado al identificador de directorio hasta que se cierra y su tamaño no cambia durante su vigencia. Los cambios de directorio que se producen entre las llamadas a esta función se agregan al búfer y, a continuación, se devuelven con la siguiente llamada. Si el búfer se desborda, ReadDirectoryChangesExW seguirá devolviendo true, pero todo el contenido del búfer se descarta y el parámetro lpBytesReturned será cero, lo que indica que el búfer era demasiado pequeño para contener todos los cambios que se produjeron.

Tras la finalización sincrónica correcta, el parámetro lpBuffer es un búfer con formato y el número de bytes escritos en el búfer está disponible en lpBytesReturned. Si el número de bytes transferidos es cero, el búfer era demasiado grande para que el sistema asignara o demasiado pequeño para proporcionar información detallada sobre todos los cambios que se produjeron en el directorio o subárbol. En este caso, debe calcular los cambios mediante la enumeración del directorio o subárbol.

Para la finalización asincrónica, puede recibir una notificación de una de estas tres maneras:

Uso de la función GetOverlappedResult . Para recibir una notificación a través de GetOverlappedResult, no especifique una rutina de finalización en el parámetro lpCompletionRoutine . Asegúrese de establecer el miembro hEvent de la estructura SUPERPUESTA en un evento único.
Uso de la función GetQueuedCompletionStatus . Para recibir notificaciones a través de GetQueuedCompletionStatus, no especifique una rutina de finalización en lpCompletionRoutine. Asocie el directorio hDirectory con un puerto de finalización llamando a la función CreateIoCompletionPort .
Usar una rutina de finalización. Para recibir notificaciones a través de una rutina de finalización, no asocie el directorio con un puerto de finalización. Especifique una rutina de finalización en lpCompletionRoutine. Se llama a esta rutina cada vez que se ha completado o cancelado la operación mientras el subproceso está en un estado de espera alertable. El sistema no usa el miembro hEvent de la estructura SUPERPUESTA , por lo que puede usarlo usted mismo.

Para obtener más información, consulte E /S sincrónica y asincrónica.

ReadDirectoryChangesExW produce un error con ERROR_INVALID_PARAMETER cuando la longitud del búfer es mayor que 64 KB y la aplicación supervisa un directorio a través de la red. Esto se debe a una limitación de tamaño de paquete con los protocolos subyacentes de uso compartido de archivos.

ReadDirectoryChangesExW produce un error con ERROR_NOACCESS cuando el búfer no está alineado en un límite DWORD .

ReadDirectoryChangesExW produce un error ERROR_NOTIFY_ENUM_DIR cuando el sistema no pudo registrar todos los cambios en el directorio. En este caso, debe calcular los cambios mediante la enumeración del directorio o subárbol.

Si abrió el archivo con el nombre corto, puede recibir notificaciones de cambio para el nombre corto.

ReadDirectoryChangesExW solo se admite actualmente para el sistema de archivos NTFS.

Operaciones de transacción

Si hay una transacción enlazada al identificador de directorio, las notificaciones siguen las reglas de aislamiento de transacción adecuadas.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows 10, versión 1709 [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows Server 2019 [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	winbase.h (incluye Windows.h)
Library	Kernel32.lib
Archivo DLL	Kernel32.dll