CFtpConnection::GetFile

[アーティクル]
09/17/2008

更新 : 2007 年 11 月

FTP サーバーからファイルを取り出し、ローカルコンピュータに保存します。

BOOL GetFile(
   LPCTSTR pstrRemoteFile,
   LPCTSTR pstrLocalFile,
   BOOL bFailIfExists = TRUE,
   DWORD dwAttributes = FILE_ATTRIBUTE_NORMAL,
   DWORD dwFlags = FTP_TRANSFER_TYPE_BINARY,
   DWORD_PTR dwContext = 1 
);

パラメータ

pstrRemoteFile
FTP サーバーから取り出すファイルの名前が入っている NULL で終わる文字列へのポインタ。
pstrLocalFile
ローカルシステムに作成するファイルの名前が入っている NULL で終わる文字列へのポインタ。
bFailIfExists
ファイル名が既存のファイルで使用されているかどうかを表します。ローカルファイル名が既に存在していて、このパラメータが TRUE の場合、GetFile は処理に失敗します。それ以外の場合、GetFile は既存のファイルを消去します。
dwAttributes
ファイルの属性を指定します。以下に示す FILE_ATTRIBUTE_* フラグを任意に組み合わせたものです。
- FILE_ATTRIBUTE_ARCHIVE ファイルがアーカイブファイルであることを示します。アプリケーションは、ファイルにバックアップまたは削除のマークを付けるために、この属性を使います。
- FILE_ATTRIBUTE_COMPRESSED ファイルまたはディレクトリが圧縮されていることを示します。ファイルの場合、圧縮とはファイル内の全データが圧縮されていることを意味します。フォルダの場合、新たに作成されるファイルとサブフォルダが、既定で圧縮されることを意味します。
- FILE_ATTRIBUTE_DIRECTORY ファイルがディレクトリであることを示します。
- FILE_ATTRIBUTE_NORMAL ファイルには、ほかの属性は設定されていません。この属性は、単独で使用された場合だけ有効です。ほかのファイル属性が設定されている場合はそちらが優先され、FILE_ATTRIBUTE_NORMAL は無効になります。
- FILE_ATTRIBUTE_HIDDEN ファイルが隠しファイルであることを示します。このファイルは、標準のフォルダ一覧には含まれません。
- FILE_ATTRIBUTE_READONLY ファイルが読み取り専用であることを示します。アプリケーションはファイルの読み出しはできますが、書き込みまたは削除はできません。
- FILE_ATTRIBUTE_SYSTEM ファイルはオペレーティングシステムの一部分か、オペレーティングシステムだけで使用されます。
- FILE_ATTRIBUTE_TEMPORARY ファイルは、一時的な記憶用に使用されます。アプリケーションが書き込みをするのは、確実に必要な場合だけに限ります。ファイルはすぐに削除されるため、ファイルのデータのほとんどはメディアに書き込まれずにメモリ内に残ります。
dwFlags
転送方法を指定します。これは、Windows SDK の「FtpGetFile」で説明されている、dwFlags のいずれかです。
dwContext
ファイル取り出しのコンテキスト ID。dwContextの詳細については、「解説」を参照してください。

戻り値

正常終了した場合は 0 以外を返します。それ以外の場合は 0 を返します。呼び出しに失敗した場合は、Win32 の関数 GetLastError を呼び出してエラーの原因を調査できます。

解説

GetFile は、FTP サーバーからのファイル読み出しとローカルへの保存に関連するオーバーヘッドのすべてを処理する高水準ルーチンです。ファイルデータを取り出すだけのアプリケーション、またはファイル転送において細かい制御を必要とするアプリケーションでは、代わりに OpenFile と CInternetFile::Read を使用してください。

dwFlags が FILE_TRANSFER_TYPE_ASCII である場合、ファイルデータの転送において、コントロールとフォーマット文字が Windows の対応するものに変換されます。既定の転送はバイナリモードであり、ファイルはサーバーに保存されている形式でダウンロードされます。

pstrRemoteFile と pstrLocalFile は、現在のフォルダに対する相対の部分的なファイル名、または完全なファイル名のどちらも可能です。円記号 (\) またはスラッシュ (/) を、それぞれの名前のフォルダ名の区切り記号として使用できます。GetFile は、フォルダを使用する前に、フォルダ名の区切り記号を適切な文字に変換します。

コンテキスト ID に独自の値を設定するには、dwContext の既定値をオーバーライドします。コンテキスト ID は、CInternetSession オブジェクトで作成された CFtpConnection オブジェクトによるこの処理に関連付けられています。値は CInternetSession::OnStatusCallback に返され、指定された操作のステータスを提供します。コンテキスト ID の詳細については、「WinInet の基礎」を参照してください。