Función FindFirstChangeNotificationA (fileapi.h)

Crea un identificador de notificación de cambio y configura las condiciones iniciales del filtro de notificación de cambio. Una espera en un identificador de notificación se realiza correctamente cuando se produce un cambio que coincida con las condiciones de filtro en el directorio o subárbol especificados. La función no notifica cambios en el propio directorio especificado.

Esta función no indica el cambio que satisface la condición de espera. Para recuperar información sobre el cambio específico como parte de la notificación, use el
función ReadDirectoryChangesW.

Sintaxis

HANDLE FindFirstChangeNotificationA(
  [in] LPCSTR lpPathName,
  [in] BOOL   bWatchSubtree,
  [in] DWORD  dwNotifyFilter
);

Parámetros

[in] lpPathName

Ruta de acceso completa del directorio que se va a inspeccionar.

No puede ser una ruta de acceso relativa o una cadena vacía.

De forma predeterminada, el nombre se limita a MAX_PATH caracteres. Para ampliar este límite a 32 767 caracteres anchos, anteponga "\\?\\ " a la ruta de acceso. Para obtener más información, vea Archivos de nomenclatura, rutas de acceso y espacios de nombres.

Propina

A partir de Windows 10, versión 1607, puedes optar por quitar la limitación del MAX_PATH sin tener que prepending "\\?\". Consulte la sección "Limitación máxima de longitud de ruta de acceso" de Archivos de nomenclatura, rutas de acceso y espacios de nombres para obtener más información.

[in] bWatchSubtree

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

[in] dwNotifyFilter

Condiciones de filtro que cumplen una espera de notificación de cambio. Este parámetro puede ser uno o varios de los siguientes valores.

Valor	Significado
FILE_NOTIFY_CHANGE_FILE_NAME 0x00000001	Cualquier cambio de nombre de archivo en el directorio o subárbol supervisado hace que se devuelva una operación de espera de notificación de cambio. Los cambios incluyen cambiar el nombre, crear o eliminar un nombre de 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 supervisado hace que se devuelva una operación de espera de notificación de cambio.
FILE_NOTIFY_CHANGE_SIZE 0x00000008	Cualquier cambio de tamaño de archivo en el directorio o subárbol supervisado hace que se devuelva una operación de espera de notificación de cambio. El sistema operativo detecta un cambio en el tamaño de archivo solo cuando el archivo se escribe en el disco. En el caso de los sistemas operativos que usan un almacenamiento en caché extenso, la detección solo se produce cuando la memoria caché está lo suficientemente vacía.
FILE_NOTIFY_CHANGE_LAST_WRITE 0x00000010	Cualquier cambio en la última hora de escritura de los archivos en el directorio o subárbol supervisado hace que se devuelva una operación de espera de notificación de cambio. El sistema operativo detecta un cambio en la última hora de escritura solo cuando el archivo se escribe en el disco. En el caso de los sistemas operativos que usan un almacenamiento en caché extenso, la detección solo se produce cuando la memoria caché está lo suficientemente vacía.
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.

Valor devuelto

Si la función se ejecuta correctamente, el valor devuelto es un identificador de un objeto de notificación de búsqueda de cambios.

Si se produce un error en la función, el valor devuelto es INVALID_HANDLE_VALUE. Para obtener información de error extendida, llame a GetLastError.

Observaciones

Las funciones de espera pueden supervisar el directorio o subárbol especificados mediante el identificador devuelto por la función findFirstChangeNotification . Se cumple una espera cuando se produce una de las condiciones de filtro en el directorio o subárbol supervisados.

Una vez que se haya satisfecho la espera, la aplicación puede responder a esta condición y continuar supervisando el directorio llamando a la función FindNextChangeNotification y a la función de espera adecuada. Cuando el identificador ya no es necesario, se puede cerrar mediante la función FindCloseChangeNotification.

Es posible que no se devuelvan notificaciones al llamar a findFirstChangeNotification para un sistema de archivos remoto.

Comportamiento simbólico del vínculo: si la ruta de acceso apunta a un vínculo simbólico, se crea el identificador de notificación para el destino.

Si una aplicación se ha registrado para recibir notificaciones de cambio para un directorio que contiene vínculos simbólicos, la aplicación solo se notifica cuando se han cambiado los vínculos simbólicos, no los archivos de destino.

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

Tecnología	Soportado
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)	Ver comentario
Sistema de archivos resistente (ReFS)	Sí

 

Es posible que la aplicación experimente falsos positivos en csvFs pause/resume.

Ejemplos

Para obtener un ejemplo, vea obtener Change_Notificationsde directorio.

Nota

El encabezado fileapi.h define FindFirstChangeNotification como alias que selecciona automáticamente la versión ANSI o Unicode de esta función en función de la definición de la constante de preprocesador UNICODE. La combinación del uso del alias neutral de codificación con código que no es neutral de codificación puede dar lugar a errores de coincidencia que dan lugar a errores de compilación o tiempo de ejecución. Para obtener más información, vea Conventions for Function Prototypes.

Requisitos

Requisito	Valor
cliente mínimo admitido	Windows XP [solo aplicaciones de escritorio]
servidor mínimo admitido	Windows Server 2003 [solo aplicaciones de escritorio]
de la plataforma de destino de	Windows
encabezado de	fileapi.h (incluya Windows.h)
biblioteca de	Kernel32.lib
DLL de	Kernel32.dll

Consulte también

funciones de administración de directorios de

FindCloseChangeNotification

FindNextChangeNotification

ReadDirectoryChangesW