ReadDirectoryChangesExW 関数 (winbase.h)
指定のディレクトリ内での変更を説明する情報を取得します。ある種類の情報が指定されている場合、それも含めるように拡大されることがあります。 関数は、指定したディレクトリ自体に対する変更を報告しません。
ボリュームでの変更の追跡については、「変更ジャーナル」をご覧ください。
構文
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
);
パラメーター
[in] hDirectory
監視するディレクトリへのハンドル。 このディレクトリは、FILE_LIST_DIRECTORYアクセス権、または FILE_LIST_DIRECTORY アクセス権 を 含むGENERIC_READ などのアクセス権 で開く必要があります。
[out] lpBuffer
ReadDirectoryChangesExW が読み取り結果を返す DWORD に配置された書式設定されたバッファーへのポインター。 このバッファーの構造は、ReadDirectoryNotifyInformationClass パラメーターの値が ReadDirectoryNotifyExtendedInformation の場合は FILE_NOTIFY_EXTENDED_INFORMATION 構造体、ReadDirectoryNotifyInformationClass が ReadDirectoryNotifyInformationClass の場合はFILE_NOTIFY_INFORMATION構造体によって定義されます。
このバッファーは、ディレクトリの開き方と lpOverlapped パラメーターに指定される値に応じて、同期または非同期に入力されます。 詳細については、「解説」を参照してください。
[in] nBufferLength
lpBuffer パラメーターが指すバッファーのサイズ (バイト単位)。
[in] bWatchSubtree
このパラメーターが TRUE の場合、関数は指定したディレクトリにルート化されたディレクトリ ツリーを監視します。 このパラメーターが FALSE の場合、関数は hDirectory パラメーターで指定されたディレクトリのみを監視します。
[in] dwNotifyFilter
待機操作が完了したかどうかを判断するために関数がチェックするフィルター条件。 このパラメーターには、次の 1 つ以上の値を指定できます。
[out, optional] lpBytesReturned
同期呼び出しの場合、このパラメーターは lpBuffer パラメーターに転送されたバイト数を受け取ります。 非同期呼び出しの場合、このパラメーターは未定義です。 転送されたバイト数を取得するには、非同期通知手法を使用する必要があります。
[in, out, optional] lpOverlapped
非同期操作中に使用するデータを提供する OVERLAPPED 構造体へのポインター。 それ以外の場合、この値は NULL です。 この構造体の Offset メンバーと OffsetHigh メンバーは使用されません。
[in, optional] lpCompletionRoutine
操作が完了または取り消され、呼び出し元スレッドが警告可能な待機状態のときに呼び出される完了ルーチンへのポインター。 この完了ルーチンの詳細については、「 FileIOCompletionRoutine」を参照してください。
[in] ReadDirectoryNotifyInformationClass
lpBuffer パラメーターが指すバッファーに ReadDirectoryChangesExW が書き込む必要がある情報の種類。 ReadDirectoryNotifyInformation を指定して、情報がFILE_NOTIFY_INFORMATION構造体で構成されていることを示すか、ReadDirectoryNotifyExtendedInformation を指定して、情報がFILE_NOTIFY_EXTENDED_INFORMATION構造体で構成されることを示します。
戻り値
関数が成功すると、戻り値は 0 以外になります。 同期呼び出しの場合、これは操作が成功したことを意味します。 非同期呼び出しの場合、これは操作が正常にキューに登録されたことを示します。
関数が失敗した場合は、0 を返します。 詳細なエラー情報を得るには、GetLastError を呼び出します。
ネットワーク リダイレクターまたはターゲット ファイル システムがこの操作をサポートしていない場合、関数は ERROR_INVALID_FUNCTION で失敗します。
注釈
ディレクトリへのハンドルを取得するには、 CreateFile 関数と FILE_FLAG_BACKUP_SEMANTICS フラグを使用します。
ReadDirectoryChangesExW の呼び出しは、同期または非同期で完了できます。 非同期補完を指定するには、上記のように CreateFile を使用してディレクトリを開きますが、dwFlagsAndAttributes パラメーターに FILE_FLAG_OVERLAPPED 属性を指定します。 次に、ReadDirectoryChangesExW を呼び出すときに OVERLAPPED 構造体を指定します。
ReadDirectoryChangesExW を初めて呼び出すと、システムは変更情報を格納するバッファーを割り当てます。 このバッファーは、閉じられ、その有効期間中にサイズが変更されないまで、ディレクトリ ハンドルに関連付けられます。 この関数の呼び出しの間に発生するディレクトリの変更はバッファーに追加され、次の呼び出しで返されます。 バッファーがオーバーフローしても ReadDirectoryChangesExW は true を返しますが、バッファーの内容全体は破棄され、 lpBytesReturned パラメーターは 0 になります。これは、発生したすべての変更をバッファーが小さすぎて保持できなかったことを示します。
同期が正常に完了すると、 lpBuffer パラメーターは書式設定されたバッファーであり、バッファーに書き込まれたバイト数は lpBytesReturned で使用できます。 転送されたバイト数が 0 の場合、バッファーが大きすぎてシステムが割り当てられなかったか、小さすぎて、ディレクトリまたはサブツリーで発生したすべての変更に関する詳細情報を提供できませんでした。 この場合は、ディレクトリまたはサブツリーを列挙して変更を計算する必要があります。
非同期完了の場合は、次の 3 つの方法のいずれかで通知を受け取ることができます。
- GetOverlappedResult 関数を使用する。 GetOverlappedResult 経由で通知を受信するには、lpCompletionRoutine パラメーターに完了ルーチンを指定しないでください。 OVERLAPPED 構造体の hEvent メンバーを一意のイベントに設定してください。
- GetQueuedCompletionStatus 関数の使用。 GetQueuedCompletionStatus を介して通知を受信するには、lpCompletionRoutine で完了ルーチンを指定しないでください。 CreateIoCompletionPort 関数を呼び出して、ディレクトリ ハンドル hDirectory を完了ポートに関連付けます。
- 完了ルーチンの使用。 完了ルーチンを介して通知を受信するには、ディレクトリを完了ポートに関連付けないでください。 lpCompletionRoutine で完了ルーチンを指定します。 このルーチンは、スレッドが警告可能な待機状態にある間に操作が完了または取り消されるたびに呼び出されます。 OVERLAPPED 構造体の hEvent メンバーはシステムで使用されないため、自分で使用できます。
ReadDirectoryChangesExW は、バッファー長が 64 KB を超え、アプリケーションがネットワーク経由でディレクトリを監視している場合に、 ERROR_INVALID_PARAMETER で失敗します。 これは、基になるファイル共有プロトコルのパケット サイズの制限によるものです。
バッファーが DWORD 境界に配置されていない場合、ReadDirectoryChangesExW は ERROR_NOACCESS で失敗します。
ReadDirectoryChangesExW は、システムがディレクトリに対するすべての変更を記録できなかったときに、 ERROR_NOTIFY_ENUM_DIR で失敗します。 この場合は、ディレクトリまたはサブツリーを列挙して変更を計算する必要があります。
短い名前を使用してファイルを開いた場合は、短い名前の変更通知を受け取ることができます。
ReadDirectoryChangesExW は現在、NTFS ファイル システムでのみサポートされています。
トランザクション操作
ディレクトリ ハンドルにバインドされたトランザクションがある場合、通知は適切なトランザクション分離規則に従います。要件
| 要件 | 値 |
|---|---|
| サポートされている最小のクライアント | Windows 10バージョン 1709 [デスクトップ アプリのみ] |
| サポートされている最小のサーバー | Windows Server 2019 [デスクトップ アプリのみ] |
| 対象プラットフォーム | Windows |
| ヘッダー | winbase.h (Windows.h を含む) |
| Library | Kernel32.lib |
| [DLL] | Kernel32.dll |