FtpFindFirstFileW

指定された FTP セッションのディレクトリを検索する。ファイルとディレクトリのエントリは WIN32_FIND_DATA 構造体としてアプリケーションに返される。(Unicode)

FtpFindFirstFileW hConnect, lpszSearchFile, lpFindFileData, dwFlags, dwContext

hConnect : [intptr] InternetConnect から返された FTP セッションへのハンドル。
lpszSearchFile : [wstr] FTP サーバーのファイルシステム上の有効なディレクトリパスまたはファイル名を指定する null 終端文字列へのポインタ。文字列にはワイルドカードを含めることができるが、空白は許可されない。lpszSearchFile の値が NULL または空文字列の場合、関数はサーバー上のカレントディレクトリで最初のファイルを検索する。
lpFindFileData : [var] 見つかったファイルまたはディレクトリの情報を受け取る WIN32_FIND_DATA 構造体へのポインタ。
dwFlags : [int] 
dwContext : [int] 本検索を任意のアプリケーションデータと関連付けるアプリケーション定義の値を指定する変数へのポインタ。本パラメータは、アプリケーションが既に InternetSetStatusCallback を呼び出してステータスコールバック関数を設定している場合にのみ使用される。

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

解説

指定された FTP セッションのディレクトリを検索する。ファイルとディレクトリのエントリは WIN32_FIND_DATA
構造体としてアプリケーションに返される。(Unicode)

[戻り値]
ディレクトリ列挙が正常に開始された場合は要求に対する有効なハンドルを、そうでない場合は NULL
を返す。具体的なエラーメッセージを取得するには GetLastError を呼び出す。一致するファイルが見つからない場合などに
GetLastError が ERROR_INTERNET_EXTENDED_ERROR
を返した場合は、InternetGetLastResponseInfo 関数を呼び出して拡張エラーテキストを取得すること
(Handling Errors を参照)。

[備考]
FtpFindFirstFile では、WIN32_FIND_DATA
構造体に返されるファイル時刻はローカルタイムゾーンであり、協定世界時 (UTC) 形式ではない。FtpFindFirstFile は
FindFirstFile 関数に類似している。ただし、特定の FTP セッション内で同時に発生できる FtpFindFirstFile
は 1 つだけであることに注意すること。したがって、列挙は FTP セッションハンドルと相関する。これは FTP
プロトコルがセッションごとに 1 つのディレクトリ列挙のみを許可しているためである。FtpFindFirstFile
を呼び出した後、InternetCloseHandle を呼び出すまで、アプリケーションは指定した FTP セッションハンドルで
FtpFindFirstFile を再度呼び出すことができない。そのハンドルで FtpFindFirstFile を呼び出すと、関数は
ERROR_FTP_TRANSFER_IN_PROGRESS で失敗する。呼び出し側アプリケーションが FtpFindFirstFile
によって返された HINTERNET ハンドルの使用を終えたら、InternetCloseHandle
関数で閉じなければならない。FtpFindFirstFile によるディレクトリ列挙の開始後、InternetFindNextFile
関数を使用して列挙を継続できる。FTP
プロトコルには列挙の標準的な手段がないため、ファイル作成日時など、ファイルに関する一般的な情報の一部は常に利用できるとは限らず、正確でない場合もある。そのような場合、FtpFindFirstFile
と InternetFindNextFile
は、利用可能な情報に基づく最善の推測で利用できない情報を埋める。例えば、作成日や最終アクセス日は、しばしばファイルの更新日と同じになる。アプリケーションは
FtpOpenFile と InternetCloseHandle の呼び出しの間に FtpFindFirstFile
を呼び出すことができない。WinINet API の他のすべての側面と同様に、本関数は DllMain
やグローバルオブジェクトのコンストラクタ・デストラクタの中から安全に呼び出すことはできない。注意: WinINet
はサーバー実装をサポートしていない。さらに、サービスから使用すべきでもない。サーバー実装やサービスでは Microsoft Windows
HTTP Services (WinHTTP) を使用すること。
> [!NOTE] > wininet.h ヘッダーは FtpFindFirstFile をエイリアスとして定義しており、UNICODE
プリプロセッサ定数の定義に基づいて本関数の ANSI 版または Unicode
版を自動的に選択する。エンコーディング中立のエイリアスとエンコーディング中立でないコードを混在させると、コンパイルエラーや実行時エラーの原因となるミスマッチが発生する可能性がある。詳細は
[Conventions for Function
Prototypes](/windows/win32/intl/conventions-for-function-prototypes)
を参照のこと。

情報