Función ReadDirectoryChangesW (winbase.h)

Artículo
08/27/2023

Recupera información que describe los cambios en el directorio especificado. 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 ReadDirectoryChangesW(
  [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
);

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 se devolverán los resultados de lectura. La estructura de este búfer se define mediante la estructura FILE_NOTIFY_INFORMATION . Este búfer se rellena de forma sincrónica o asincrónica, según cómo se abra el directorio y qué valor se asigna 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 inspeccionado 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 hora de último acceso de los archivos del directorio o subárbol inspeccionado 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 inspeccionado 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 inspeccionado 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 . En el caso de 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 ha completado o cancelado la operación y el subproceso que realiza la llamada se encuentra en un estado de espera alertable. Para obtener más información sobre esta rutina de finalización, vea FileIOCompletionRoutine.

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. En el caso de 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 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 ReadDirectoryChangesW 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 al llamar a ReadDirectoryChangesW.

Cuando se llama por primera vez a ReadDirectoryChangesW, el sistema asigna un búfer para almacenar información de cambios. 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, ReadDirectoryChangesW 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 notificaciones 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 a 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 a 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, vea E/S sincrónica y asincrónica.

ReadDirectoryChangesW produce un error con ERROR_INVALID_PARAMETER cuando la longitud del búfer es superior a 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.

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

ReadDirectoryChangesW 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.

En Windows 8 y Windows Server 2012, esta función es compatible con las tecnologías siguientes.

Tecnología	Compatible
Protocolo Bloque de mensajes del servidor (SMB) 3.0	Sí
Conmutación por error transparente (TFO) de SMB 3.0	Sí
SMB 3.0 con recursos compartidos de archivos de escalabilidad horizontal (SO)	Sí
Sistema de archivos de Volumen compartido de clúster (CsvFS)	Sí
Sistema de archivos resistente a errores (ReFS)	Sí

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


Cliente mínimo compatible	Windows XP [aplicaciones de escritorio \| aplicaciones para UWP]
Servidor mínimo compatible	Windows Server 2003 [aplicaciones de escritorio \| aplicaciones para UWP]
Plataforma de destino	Windows
Encabezado	winbase.h (incluya Windows.h)
Library	Kernel32.lib
Archivo DLL	Kernel32.dll