Função ReadDirectoryChangesExW (winbase.h)
Recupera informações que descrevem as alterações no diretório especificado, que podem incluir informações estendidas se esse tipo de informação for 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 ReadDirectoryChangesExW(
[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,
[in] READ_DIRECTORY_NOTIFY_INFORMATION_CLASS ReadDirectoryNotifyInformationClass
);
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 a DWORD no qual ReadDirectoryChangesExW deve retornar os resultados de leitura. A estrutura desse buffer será definida pela estrutura FILE_NOTIFY_EXTENDED_INFORMATION se o valor do parâmetro ReadDirectoryNotifyInformationClass for ReadDirectoryNotifyExtendedInformation ou pela estrutura FILE_NOTIFY_INFORMATION se ReadDirectoryNotifyInformationClass for ReadDirectoryNotifyInformation.
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 para o qual o parâmetro lpBuffer aponta, 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.
[in] ReadDirectoryNotifyInformationClass
O tipo de informação que ReadDirectoryChangesExW deve gravar no buffer no qual o parâmetro lpBuffer aponta. Especifique ReadDirectoryNotifyInformation para indicar que as informações devem consistir em estruturas FILE_NOTIFY_INFORMATION ou ReadDirectoryNotifyExtendedInformation para indicar que as informações devem consistir em estruturas FILE_NOTIFY_EXTENDED_INFORMATION .
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 ReadDirectoryChangesExW 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 ReadDirectoryChangesExW.
Quando você chama ReadDirectoryChangesExW 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 seja fechado e seu tamanho não seja alterado durante seu tempo de vida. As alterações de diretório que ocorrem entre chamadas para essa função são adicionadas ao buffer e retornadas com a próxima chamada. Se o buffer estourar, ReadDirectoryChangesExW 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 era 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 uma 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.
ReadDirectoryChangesExW 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.
ReadDirectoryChangesExW falha com ERROR_NOACCESS quando o buffer não está alinhado em um limite DWORD .
ReadDirectoryChangesExW falha com ERROR_NOTIFY_ENUM_DIR quando o sistema não pôde 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 momento, o ReadDirectoryChangesExW tem suporte apenas para o sistema de arquivos NTFS.
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
| Requisito | Valor |
|---|---|
| Cliente mínimo com suporte | Windows 10, versão 1709 [somente aplicativos da área de trabalho] |
| Servidor mínimo com suporte | Windows Server 2019 [somente aplicativos da área de trabalho] |
| Plataforma de Destino | Windows |
| Cabeçalho | winbase.h (incluir Windows.h) |
| Biblioteca | Kernel32.lib |
| DLL | Kernel32.dll |
Confira também
Funções do gerenciamento de diretórios