ReadDirectoryChangesExW

指定したディレクトリ内の変更内容を記述する情報を取得する。情報の種類によっては拡張情報を含めることもできる。

ReadDirectoryChangesExW hDirectory, lpBuffer, nBufferLength, bWatchSubtree, dwNotifyFilter, lpBytesReturned, lpOverlapped, lpCompletionRoutine, ReadDirectoryNotifyInformationClass

hDirectory : [intptr] 監視対象ディレクトリへのハンドル。このディレクトリは FILE_LIST_DIRECTORY アクセス権、または FILE_LIST_DIRECTORY を含む GENERIC_READ などのアクセス権で開く必要がある。
lpBuffer : [intptr] ReadDirectoryChangesExW が読み取り結果を返すべき、DWORD にアラインされた書式付きバッファへのポインタ。このバッファの構造は、ReadDirectoryNotifyInformationClass パラメータの値が ReadDirectoryNotifyExtendedInformation の場合は FILE_NOTIFY_EXTENDED_INFORMATION 構造体で、ReadDirectoryNotifyInformation の場合は FILE_NOTIFY_INFORMATION 構造体で定義される。このバッファは、ディレクトリの開き方と lpOverlapped パラメータに与えられた値に応じて、同期または非同期に埋められる。詳細は Remarks セクションを参照。
nBufferLength : [int] lpBuffer パラメータが指すバッファのサイズ(バイト単位)。
bWatchSubtree : [int] このパラメータが TRUE の場合、関数は指定したディレクトリをルートとするディレクトリツリーを監視する。FALSE の場合、関数は hDirectory パラメータで指定されたディレクトリのみを監視する。
dwNotifyFilter : [int] 待機操作が完了したかを判定するために関数がチェックするフィルタ条件。
lpBytesReturned : [var] 同期呼び出しの場合、このパラメータは lpBuffer パラメータへ転送されたバイト数を受け取る。非同期呼び出しの場合、このパラメータは未定義である。転送されたバイト数の取得には非同期通知手法を使用しなければならない。
lpOverlapped : [var] 非同期操作中に使用するデータを提供する OVERLAPPED 構造体へのポインタ。それ以外の場合はこの値は NULL である。この構造体の Offset および OffsetHigh メンバは使用されない。
lpCompletionRoutine : [int] 操作が完了またはキャンセルされ、呼び出し側スレッドがアラート可能な待機状態にあるときに呼び出される完了ルーチンへのポインタ。この完了ルーチンの詳細は FileIOCompletionRoutine を参照。
ReadDirectoryNotifyInformationClass : [int] ReadDirectoryChangesExW が lpBuffer パラメータが指すバッファへ書き込む情報の種類。情報を FILE_NOTIFY_INFORMATION 構造体で構成する場合は ReadDirectoryNotifyInformation を、FILE_NOTIFY_EXTENDED_INFORMATION 構造体で構成する場合は ReadDirectoryNotifyExtendedInformation を指定する。

(プラグイン / モジュール : kernel32.dll)

解説

指定したディレクトリ内の変更内容を記述する情報を取得する。情報の種類によっては拡張情報を含めることもできる。

[戻り値]
関数が成功した場合、戻り値は 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
つの方法のいずれかで通知を受け取ることができる。
（以下省略）

情報