Compartilhar via


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