Função ReadDirectoryChangesW (winbase.h)
Recupera informações que descrevem as alterações no diretório especificado. A função não relata alterações no próprio diretório especificado.
Para controlar as alterações em um volume, confira alterar diários.
Sintaxe
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
Um identificador para o diretório a ser monitorado. Esse diretório deve ser aberto com o direito de acesso FILE_LIST_DIRECTORY ou um direito de acesso, como GENERIC_READ que inclui o direito de acesso FILE_LIST_DIRECTORY .
[out] lpBuffer
Um ponteiro para o buffer formatado alinhado ao DWORD no qual os resultados de leitura devem ser retornados. A estrutura desse buffer é definida pela estrutura FILE_NOTIFY_INFORMATION . Esse buffer é preenchido de forma síncrona ou assíncrona, dependendo de como o diretório é aberto e qual valor é dado ao parâmetro lpOverlapped . Para obter mais informações, consulte a seção Comentários.
[in] nBufferLength
O tamanho do buffer apontado pelo parâmetro lpBuffer , em bytes.
[in] bWatchSubtree
Se esse parâmetro for TRUE, a função monitorará a árvore de diretório com raiz no diretório especificado. Se esse parâmetro for FALSE, a função monitorará apenas o diretório especificado pelo parâmetro hDirectory .
[in] dwNotifyFilter
Os critérios de filtro que a função verifica para determinar se a operação de espera foi concluída. Esse parâmetro pode usar um dos valores a seguir.
[out, optional] lpBytesReturned
Para chamadas síncronas, esse parâmetro recebe o número de bytes transferidos para o parâmetro lpBuffer . Para chamadas assíncronas, esse parâmetro é indefinido. Você deve usar uma técnica de notificação assíncrona para recuperar o número de bytes transferidos.
[in, out, optional] lpOverlapped
Um ponteiro para uma estrutura OVERLAPPED que fornece dados a serem usados durante a operação assíncrona. Caso contrário, esse valor será NULL. Os membros Offset e OffsetHigh dessa estrutura não são usados.
[in, optional] lpCompletionRoutine
Um ponteiro para uma rotina de conclusão a ser chamada quando a operação tiver sido concluída ou cancelada e o thread de chamada estiver em um estado de espera alertável. Para obter mais informações sobre essa rotina de conclusão, consulte FileIOCompletionRoutine.
Valor retornado
Se a função for bem-sucedida, o valor retornado será diferente de zero. Para chamadas síncronas, isso significa que a operação foi bem-sucedida. Para chamadas assíncronas, isso indica que a operação foi enfileirada com êxito.
Se a função falhar, o valor retornado será zero. Para obter informações de erro estendidas, chame GetLastError.
Se o redirecionador de rede ou o sistema de arquivos de destino não der suporte a essa operação, a função falhará com ERROR_INVALID_FUNCTION.
Comentários
Para obter um identificador para um diretório, use a função CreateFile com o sinalizador FILE_FLAG_BACKUP_SEMANTICS .
Uma chamada para ReadDirectoryChangesW pode ser concluída de forma síncrona ou assíncrona. Para especificar a conclusão assíncrona, abra o diretório com CreateFile conforme mostrado acima, mas especifique o atributo FILE_FLAG_OVERLAPPED no parâmetro dwFlagsAndAttributes . Em seguida, especifique uma estrutura OVERLAPPED ao chamar ReadDirectoryChangesW.
Quando você chama ReadDirectoryChangesW pela primeira vez, o sistema aloca um buffer para armazenar informações de alteração. Esse buffer é associado ao identificador de diretório até que ele seja fechado e seu tamanho não seja alterado durante seu tempo de vida. As alterações de diretório que ocorrem entre chamadas a essa função são adicionadas ao buffer e retornadas com a próxima chamada. Se o buffer estourar, ReadDirectoryChangesW ainda retornará true, mas todo o conteúdo do buffer será descartado e o parâmetro lpBytesReturned será zero, o que indica que o buffer era muito pequeno para conter todas as alterações que ocorreram.
Após a conclusão síncrona bem-sucedida, o parâmetro lpBuffer é um buffer formatado e o número de bytes gravados no buffer está disponível em lpBytesReturned. Se o número de bytes transferidos for zero, o buffer será muito grande para o sistema alocar ou muito pequeno para fornecer informações detalhadas sobre todas as alterações que ocorreram no diretório ou na subárvore. Nesse caso, você deve calcular as alterações enumerando o diretório ou a subárvore.
Para conclusão assíncrona, você pode receber notificação de uma das três maneiras:
- Usando a função GetOverlappedResult . Para receber notificação por meio de GetOverlappedResult, não especifique uma rotina de conclusão no parâmetro lpCompletionRoutine . Defina o membro hEvent da estrutura OVERLAPPED como um evento exclusivo.
- Usando a função GetQueuedCompletionStatus . Para receber notificação por meio de GetQueuedCompletionStatus, não especifique uma rotina de conclusão em lpCompletionRoutine. Associe o identificador de diretório hDirectory a uma porta de conclusão chamando a função CreateIoCompletionPort .
- Usando uma rotina de conclusão. Para receber notificação por meio de uma rotina de conclusão, não associe o diretório a uma porta de conclusão. Especifique uma rotina de conclusão em lpCompletionRoutine. Essa rotina é chamada sempre que a operação é concluída ou cancelada enquanto o thread está em um estado de espera alertável. O membro hEvent da estrutura OVERLAPPED não é usado pelo sistema, portanto, você pode usá-lo por conta própria.
ReadDirectoryChangesW falha com ERROR_INVALID_PARAMETER quando o comprimento do buffer é maior que 64 KB e o aplicativo está monitorando um diretório pela rede. Isso ocorre devido a uma limitação de tamanho de pacote com os protocolos de compartilhamento de arquivos subjacentes.
ReadDirectoryChangesW falha com ERROR_NOACCESS quando o buffer não está alinhado em um limite DWORD .
ReadDirectoryChangesW falha com ERROR_NOTIFY_ENUM_DIR quando o sistema não consegue registrar todas as alterações no diretório. Nesse caso, você deve calcular as alterações enumerando o diretório ou a subárvore.
Se você abriu o arquivo usando o nome curto, poderá receber notificações de alteração para o nome curto.
No Windows 8 e Windows Server 2012, essa função é compatível com as tecnologias a seguir.
| Tecnologia | Com suporte |
|---|---|
| Protocolo SMB (SMB) 3.0 | Sim |
| TFO (Failover transparente) do SMB 3.0 | Sim |
| SMB 3.0 com compartilhamentos de arquivos de expansão (SO) | Sim |
| Sistema de arquivos de Volume Compartilhado Clusterizado (CsvFS) | Sim |
| ReFS (Sistema de Arquivos Resiliente) | Sim |
Operações transacionadas
Se houver uma transação associada ao identificador de diretório, as notificações seguirão as regras de isolamento de transação apropriadas.Requisitos
| Cliente mínimo com suporte | Windows XP [aplicativos da área de trabalho | aplicativos UWP] |
| Servidor mínimo com suporte | Windows Server 2003 [aplicativos da área de trabalho | Aplicativos UWP] |
| Plataforma de Destino | Windows |
| Cabeçalho | winbase.h (inclua Windows.h) |
| Biblioteca | Kernel32.lib |
| DLL | Kernel32.dll |