FindFirstFileTransactedW 関数 (winbase.h)

  • [アーティクル]

[Microsoft では、開発者がアプリケーションのニーズを達成するために代替手段を利用することを強くお勧めします。 TxF が開発された多くのシナリオは、より簡単で簡単に利用できる手法を使用して実現できます。 さらに、将来のバージョンの Microsoft Windows では TxF を使用できない場合があります。 詳細と TxF の代替手段については、「 トランザクション NTFS を使用する代替手段」を参照してください。

トランザクション操作として特定の名前と一致する名前を持つファイルまたはサブディレクトリをディレクトリで検索します。

この関数は、 FindFirstFileEx 関数のトランザクション形式です。

この関数の最も基本的なバージョンについては、「 FindFirstFile」を参照してください。

構文

HANDLE FindFirstFileTransactedW(
  [in]  LPCWSTR            lpFileName,
  [in]  FINDEX_INFO_LEVELS fInfoLevelId,
  [out] LPVOID             lpFindFileData,
  [in]  FINDEX_SEARCH_OPS  fSearchOp,
        LPVOID             lpSearchFilter,
  [in]  DWORD              dwAdditionalFlags,
  [in]  HANDLE             hTransaction
);

パラメーター

[in] lpFileName

ディレクトリまたはパス、およびファイル名。 ファイル名には、アスタリスク (*) や疑問符 (?) などのワイルドカード文字を含めることができます。

このパラメーターは NULL、無効な文字列 (たとえば、空の文字列や終端の null 文字がない文字列)、末尾の円記号 (\) で終わる値にすることはできません。

文字列がワイルドカード、ピリオド (.)、またはディレクトリ名で終わる場合、ユーザーはルートとパス上のすべてのサブディレクトリにアクセスできる必要があります。

ファイルはローカル コンピューターに存在する必要があります。それ以外の場合、関数は失敗し、最後のエラー コードは ERROR_TRANSACTIONS_UNSUPPORTED_REMOTE に設定されます。

既定では、名前はMAX_PATH文字に制限されています。 この制限を 32,767 文字のワイド文字に拡張するには、パスの先頭に "\\?\" を付加します。 詳細については、「ファイル、パス、および名前空間の名前付け」を参照してください。

ヒント

Windows 10 バージョン 1607 以降では、"\\?\" を前に置かずに、MAX_PATHの制限を削除するようにオプトインできます。 詳細については、「 ファイル、パス、および名前空間の名前付け 」の「最大パス長の制限」セクションを参照してください。

[in] fInfoLevelId

返されるデータの情報レベル。

このパラメーターは、 FINDEX_INFO_LEVELS 列挙値の 1 つです。

[out] lpFindFileData

見つかったファイルまたはサブディレクトリに関する情報を受け取る WIN32_FIND_DATA 構造体へのポインター。

[in] fSearchOp

ワイルドカード一致とは異なる、実行するフィルター処理の種類。

このパラメーターは、 FINDEX_SEARCH_OPS 列挙値の 1 つです。

lpSearchFilter

指定した fSearchOp に構造化された検索情報が必要な場合は、検索条件へのポインター。

現時点では、サポートされている fSearchOp 値のいずれも拡張検索情報を必要としません。 したがって、このポインターは NULL である必要があります。

[in] dwAdditionalFlags

検索を制御する追加のフラグを指定します。

値 説明
FIND_FIRST_EX_CASE_SENSITIVE
1
 検索では大文字と小文字が区別されます。

[in] hTransaction

トランザクションのハンドル。 このハンドルは、 CreateTransaction 関数によって返されます。

戻り値

関数が成功した場合、戻り値は FindNextFile または FindClose の後続の呼び出しで使用される検索ハンドルであり、 lpFindFileData パラメーターには最初に見つかったファイルまたはディレクトリに関する情報が含まれます。

関数が失敗するか、 lpFileName パラメーターの検索文字列からファイルを検索できない場合、戻り値は INVALID_HANDLE_VALUE され、 lpFindFileData の内容は不確定になります。 拡張エラー情報を取得するには、 GetLastError 関数を呼び出します。

Remarks

FindFirstFileTransacted 関数は、検索ハンドルを開き、指定したパターンに一致する名前でファイル システムが最初に見つけたファイルに関する情報を返します。 これは、同じファイル名の文字列パターンを指定した場合に、ディレクトリ一覧アプリケーション (dir コマンドなど) に表示される最初のファイルまたはディレクトリである場合とそうでない場合があります。 これは、 FindFirstFileTransacted が検索結果の並べ替えを行わないためです。 詳細については、「 FindNextFile」を参照してください。

次の一覧は、その他の検索特性を示しています。

  • 検索は、日付やファイルの種類などの属性ではなく、ファイルの名前に対して厳密に実行されます。
  • 検索には、長いファイル名と短いファイル名が含まれます。
  • 末尾の円記号を使用して検索を開こうとすると、常に失敗します。
  • lpFileName パラメーターに無効な文字列、NULL、または空の文字列を渡すことは、この関数の有効な使用ではありません。 この場合の結果は未定義です。
メモ まれに、NTFS ファイル システムのファイル情報が、この関数を呼び出す時点で最新ではない可能性があります。 現在のファイル情報を確実に取得するには、 GetFileInformationByHandle 関数を呼び出します。
 
基になるファイル システムで、ディレクトリ フィルター処理以外の指定された種類のフィルター処理がサポートされていない場合、 FindFirstFileTransacted はエラー ERROR_NOT_SUPPORTEDで失敗します。 アプリケーションでは、FileExSearchNameMatch 型FINDEX_SEARCH_OPS使用し、独自のフィルター処理を実行する必要があります。

検索ハンドルが確立されたら、 FindNextFile 関数でそれを使用して、同じパターンと同じフィルター処理が実行されている他のファイルを検索します。 検索ハンドルが不要な場合は、 FindClose 関数を使用して閉じる必要があります。

前述のように、FindFirstFileTransacted の lpFileName 入力文字列で末尾の円記号 (\) を使用することはできません。そのため、ルート ディレクトリを検索する方法が明確でない場合があります。 ファイルを表示したり、ルート ディレクトリの属性を取得したりする場合は、次のオプションが適用されます。

  • ルート ディレクトリ内のファイルを調べるには、"C:\*" を使用し、 FindNextFile を使用してディレクトリをステップ実行します。
  • ルート ディレクトリの属性を取得するには、 GetFileAttributes 関数を 使用します。
メモ 文字列 "\\?\" を前に置く場合、ルート ディレクトリへのアクセスは許可されません。
 

ネットワーク共有では、 lpFileName を "\\server\service*" の形式で使用できます。 ただし、共有自体を指す lpFileName を使用することはできません。たとえば、"\\server\service" は無効です。

ルート ディレクトリではないディレクトリを調べるには、末尾の円記号を使用せずに、そのディレクトリへのパスを使用します。 たとえば、"C:\Windows" の引数は、"C:\Windows" 内のディレクトリまたはファイルではなく、ディレクトリ "C:\Windows" に関する情報を返します。 "C:\Windows" のファイルとディレクトリを調べるには、"C:\Windows\*" の lpFileName を使用します。

他のスレッドまたはプロセスでは、結果のクエリを実行してから情報に対して操作する時間の間に、この名前のファイルが作成または削除される可能性があることに注意してください。 これがアプリケーションの潜在的な懸念事項である場合、考えられる解決策の 1 つは、 createFile 関数を CREATE_NEW (ファイルが存在する場合は失敗) または OPEN_EXISTING (ファイルが存在しない場合は失敗する) と共に使用することです。

ディレクトリ内のすべてのファイルを一覧表示する 32 ビット アプリケーションを作成していて、アプリケーションが 64 ビット コンピューターで実行されている可能性がある場合は、FindFirstFileTransacted を呼び出す前に Wow64DisableWow64FsRedirection を呼び出し、FindNextFile の最後の呼び出しの後に Wow64RevertWow64FsRedirection を呼び出す必要があります。 詳細については、「 ファイル システム リダイレクター」を参照してください。

パスがシンボリック リンクを指している場合、 WIN32_FIND_DATA バッファーにはターゲットではなくシンボリック リンクに関する情報が含まれます。

Windows 8とWindows Server 2012では、この関数は次のテクノロジでサポートされています。

テクノロジ サポートされています
サーバー メッセージ ブロック (SMB) 3.0 プロトコル いいえ
SMB 3.0 Transparent Failover (TFO) いいえ
SMB 3.0 とスケールアウト ファイル共有 (SO) いいえ
クラスター共有ボリューム ファイル システム (CsvFS) いいえ
Resilient File System (ReFS) いいえ
 

SMB 3.0 は TxF をサポートしていません。

注意

winbase.h ヘッダーは、Unicode プリプロセッサ定数の定義に基づいて、この関数の ANSI または Unicode バージョンを自動的に選択するエイリアスとして FindFirstFileTransacted を定義します。 エンコードに依存しないエイリアスをエンコードニュートラルでないコードと組み合わせて使用すると、コンパイルまたはランタイム エラーが発生する不一致が発生する可能性があります。 詳細については、「 関数プロトタイプの規則」を参照してください。

要件

   
サポートされている最小のクライアント Windows Vista [デスクトップ アプリのみ]
サポートされている最小のサーバー Windows Server 2008 [デスクトップ アプリのみ]
対象プラットフォーム Windows
ヘッダー winbase.h (Windows.h を含む)
Library Kernel32.lib
[DLL] Kernel32.dll

関連項目

ファイル管理機能

FindClose

FindNextFile

GetFileAttributes

SetFileAttributes

シンボリック リンク

トランザクション NTFS

WIN32_FIND_DATA