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