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