Função FindFirstChangeNotificationA (fileapi.h)

Cria um identificador de notificação de alteração e configura as condições iniciais de filtro de notificação de alteração. Uma espera em um identificador de notificação é bem-sucedida quando ocorre uma alteração correspondente às condições de filtro no diretório ou subárvore especificado. A função não relata alterações no próprio diretório especificado.

Essa função não indica a alteração que atendeu à condição de espera. Para recuperar informações sobre a alteração específica como parte da notificação, use o
Função ReadDirectoryChangesW .

Sintaxe

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

Parâmetros

[in] lpPathName

O caminho completo do diretório a ser observado.

Não pode ser um caminho relativo ou uma cadeia de caracteres vazia.

Por padrão, o nome é limitado a MAX_PATH caracteres. Para estender esse limite para 32.767 caracteres largos, acrescente "\\?\" ao caminho. Para obter mais informações, confira Nomear arquivos, caminhos e namespaces.

Dica

A partir do Windows 10, versão 1607, você pode optar por remover a limitação de MAX_PATH sem acrescentar "\\?\". Consulte a seção "Limitação máxima do comprimento do caminho" de Arquivos de Nomenclatura, Caminhos e Namespaces para obter detalhes.

[in] bWatchSubtree

Se esse parâmetro for TRUE, a função monitorará a árvore de diretório com raiz no diretório especificado; se for FALSE, ele monitorará apenas o diretório especificado.

[in] dwNotifyFilter

As condições de filtro que atendem a uma espera de notificação de alteração. Esse parâmetro pode usar um dos valores a seguir.

Valor	Significado
FILE_NOTIFY_CHANGE_FILE_NAME 0x00000001	Qualquer alteração de nome de arquivo no diretório ou subárvore observado faz com que uma operação de espera de notificação de alteração retorne. As alterações incluem renomear, criar ou excluir um nome de arquivo.
FILE_NOTIFY_CHANGE_DIR_NAME 0x00000002	Qualquer alteração de nome de diretório no diretório ou subárvore observado faz com que uma operação de espera de notificação de alteração retorne. As alterações incluem a criação ou exclusão de um diretório.
FILE_NOTIFY_CHANGE_ATTRIBUTES 0x00000004	Qualquer alteração de atributo no diretório ou subárvore observado faz com que uma operação de espera de notificação de alteração retorne.
FILE_NOTIFY_CHANGE_SIZE 0x00000008	Qualquer alteração de tamanho de arquivo no diretório ou subárvore observado faz com que uma operação de espera de notificação de alteração retorne. O sistema operacional detecta uma alteração no tamanho do arquivo somente quando o arquivo é gravado no disco. Para sistemas operacionais que usam cache extensivo, a detecção ocorre somente quando o cache é liberado o suficiente.
FILE_NOTIFY_CHANGE_LAST_WRITE 0x00000010	Qualquer alteração no último tempo de gravação de arquivos no diretório ou subárvore observado faz com que uma operação de espera de notificação de alteração retorne. O sistema operacional detecta uma alteração no último tempo de gravação somente quando o arquivo é gravado no disco. Para sistemas operacionais que usam cache extensivo, a detecção ocorre somente quando o cache é liberado o suficiente.
FILE_NOTIFY_CHANGE_SECURITY 0x00000100	Qualquer alteração do descritor de segurança no diretório ou subárvore observado faz com que uma operação de espera de notificação de alteração retorne.

Retornar valor

Se a função for bem-sucedida, o valor retornado será um identificador para um objeto de notificação de alteração de localização.

Se houver falha na função, o valor retornado será INVALID_HANDLE_VALUE. Para obter informações de erro estendidas, chame GetLastError.

Comentários

As funções de espera podem monitorar o diretório ou subárvore especificado usando o identificador retornado pela função FindFirstChangeNotification . Uma espera é atendida quando uma das condições de filtro ocorre no diretório monitorado ou na subárvore.

Depois que a espera for atendida, o aplicativo poderá responder a essa condição e continuar monitorando o diretório chamando a função FindNextChangeNotification e a função de espera apropriada. Quando o identificador não é mais necessário, ele pode ser fechado usando a função FindCloseChangeNotification .

As notificações podem não ser retornadas ao chamar FindFirstChangeNotification para um sistema de arquivos remoto.

Comportamento simbólico do link – se o caminho apontar para um link simbólico, o identificador de notificação será criado para o destino.

Se um aplicativo tiver se registrado para receber notificações de alteração para um diretório que contém links simbólicos, o aplicativo só será notificado quando os links simbólicos forem alterados, não os arquivos de destino.

Em Windows 8 e Windows Server 2012, essa função é compatível com as tecnologias a seguir.

Tecnologia	Com suporte
Protocolo SMB 3.0	Sim
TFO (Failover Transparente) do SMB 3.0	Sim
SMB 3.0 com compartilhamentos de arquivos de expansão (SO)	Sim
CsvFS (Sistema de Arquivos de Volume Compartilhado clusterizado)	Consulte o comentário
ReFS (Sistema de Arquivos Resiliente)	Sim

 

O aplicativo pode ter falsos positivos na pausa/retomada de CsvFs.

Exemplos

Para obter um exemplo, consulte Obtendo Change_Notifications de diretório.

Observação

O cabeçalho fileapi.h define FindFirstChangeNotification como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante de pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.

Requisitos

Cliente mínimo com suporte	Windows XP [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server 2003 [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	fileapi.h (inclua Windows.h)
Biblioteca	Kernel32.lib
DLL	Kernel32.dll

Confira também

Funções de gerenciamento de diretório

FindCloseChangeNotification

FindNextChangeNotification

ReadDirectoryChangesW