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.

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 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 assistido faz com que uma operação de espera de notificação de alteração retorne. O sistema operacional detecta uma alteração na última hora 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_LAST_ACCESS
0x00000020
Qualquer alteração no último horário de acesso dos arquivos no diretório ou subárvore observado faz com que uma operação de espera de notificação de alteração seja retornada.
FILE_NOTIFY_CHANGE_CREATION
0x00000040
Qualquer alteração no tempo de criaçã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.
FILE_NOTIFY_CHANGE_SECURITY
0x00000100
Qualquer alteração de 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 seja retornada.

[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.
Para obter mais informações, consulte E/S síncrona e assíncrona.

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

Confira também

CreateFile

CreateIoCompletionPort

Funções do gerenciamento de diretórios

FILE_NOTIFY_INFORMATION

FileIOCompletionRoutine

GetOverlappedResult

GetQueuedCompletionStatus

OVERLAPPED