次の方法で共有

FindFirstFileTransactedA 関数 (winbase.h)

  • [アーティクル]

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

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

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

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

構文

HANDLE FindFirstFileTransactedA(
  [in]  LPCSTR             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 文字がない文字列など)、末尾の円記号 (\) で終わる することはできません。

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

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

先端

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

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

[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 関数を呼び出します。

備考

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

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

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

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

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

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

ネットワーク共有では、"\\server\service*" の形式で lpFileName を使用できます。 ただし、共有自体を指す 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 透過的フェールオーバー (TFO) いいえ
SMB 3.0 とスケールアウト ファイル共有 (SO) いいえ
クラスター共有ボリューム ファイル システム (CsvFS) いいえ
回復性のあるファイル システム (ReFS) いいえ
 

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

手記

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

必要条件

要件 価値
サポートされる最小クライアント Windows Vista [デスクトップ アプリのみ]
サポートされる最小サーバー Windows Server 2008 [デスクトップ アプリのみ]
ターゲット プラットフォーム の ウィンドウズ
ヘッダー winbase.h (Windows.h を含む)
ライブラリ Kernel32.lib
DLL Kernel32.dll

関連項目

ファイル管理機能の

FindClose

FindNextFile の

GetFileAttributes

SetFileAttributes の

シンボリック リンク の

トランザクション NTFS の

WIN32_FIND_DATA