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

Requisitos

Confira também

CreateFile

CreateIoCompletionPort

Funções do gerenciamento de diretórios

FILE_NOTIFY_EXTENDED_INFORMATION

FILE_NOTIFY_INFORMATION

FileIOCompletionRoutine

GetOverlappedResult

GetQueuedCompletionStatus

OVERLAPPED

READ_DIRECTORY_NOTIFY_INFORMATION_CLASS