CFtpConnection クラス

  • [アーティクル]

インターネット サーバーへの FTP 接続を管理し、そのサーバー上のディレクトリとファイルを直接操作できるようにします。

構文

class CFtpConnection : public CInternetConnection

メンバー

パブリック コンストラクター

名前 説明
CFtpConnection::CFtpConnection CFtpConnection オブジェクトを構築します。

パブリック メソッド

名前 説明
CFtpConnection::Command FTP サーバーに直接コマンドを送信します。
CFtpConnection::CreateDirectory サーバー上にディレクトリを作成します。
CFtpConnection::GetCurrentDirectory この接続の現在のディレクトリを取得します。
CFtpConnection::GetCurrentDirectoryAsURL この接続の現在のディレクトリを URL として取得します。
CFtpConnection::GetFile 接続されているサーバーからファイルを取得します。
CFtpConnection::OpenFile 接続されているサーバー上のファイルを開きます。
CFtpConnection::P utFile サーバーにファイルを配置します。
CFtpConnection::Remove サーバーからファイルを削除します。
CFtpConnection::RemoveDirectory 指定したディレクトリをサーバーから削除します。
CFtpConnection::Rename サーバー上のファイルの名前を変更します。
CFtpConnection::SetCurrentDirectory 現在の FTP ディレクトリを設定します。

解説

FTP は、MFC WinInet クラスによって認識される 3 つのインターネット サービスの 1 つです。

FTP インターネット サーバーと通信するには、最初に CInternetSession のインスタンスを作成してから、 CFtpConnection オブジェクトを作成する必要があります。 CFtpConnection オブジェクトを直接作成することはありません。代わりに、CInternetSession::GetFtpConnection を呼び出して、CFtpConnection オブジェクトを作成し、そのオブジェクトへのポインターを返します。

他の MFC インターネット クラスと連携 CFtpConnection 方法の詳細については、「WinInet を使用したInternet プログラミング 」の記事を参照してください。 サポートされている他の 2 つのサービス (HTTP と gopher) との通信の詳細については、クラス CHttpConnection と CGopherConnection を参照してください。

例

CFtpFileFind クラスの概要の例を参照してください。

継承階層

CObject

CInternetConnection

CFtpConnection

要件

Header: afxinet.h

CFtpConnection::CFtpConnection

このメンバー関数は、 CFtpConnection オブジェクトを構築するために呼び出されます。

CFtpConnection(
    CInternetSession* pSession,
    HINTERNET hConnected,
    LPCTSTR pstrServer,
    DWORD_PTR dwContext);

CFtpConnection(
    CInternetSession* pSession,
    LPCTSTR pstrServer,
    LPCTSTR pstrUserName = NULL,
    LPCTSTR pstrPassword = NULL,
    DWORD_PTR dwContext = 0,
    INTERNET_PORT nPort = INTERNET_INVALID_PORT_NUMBER,
    BOOL bPassive = FALSE);

パラメーター

pSession
関連する CInternetSession オブジェクトへのポインター。

hConnected
現在のインターネット セッションの Windows ハンドル。

pstrServer
FTP サーバー名を含む文字列へのポインター。

dwContext
操作のコンテキスト識別子。 dwContext は、 CInternetSession::OnStatusCallback によって返される操作の状態情報を識別します。 既定値は 1 に設定されています。しかし、操作の特定のコンテキスト ID を明示的に割り当てることができます。 オブジェクトとその作業は、そのコンテキスト ID に関連付けられます。

pstrUserName
ログインするユーザーの名前を指定する null で終わる文字列へのポインター。 NULL の場合、既定値は匿名です。

pstrPassword
ログインに使用するパスワードを指定する null で終わる文字列へのポインター。 pstrPasswordとpstrUserNameの両方が NULL の場合、既定の匿名パスワードはユーザーの電子メール名です。 pstrPasswordが NULL (または空の文字列) であっても、pstrUserName が NULL でない場合は、空白のパスワードが使用されます。 次の表では、 pstrUserName と pstrPassword の 4 つの設定の動作について説明します。

pstrUserName pstrPassword FTP サーバーに送信されたユーザー名 FTP サーバーに送信されたパスワード
NULL または " " NULL または " " "anonymous" ユーザーのメール名
NULL 以外の文字列 NULL または " " pstrUserName " "
NULL 非 NULL 文字列 ERROR ERROR
NULL 以外の文字列 NULL 以外の文字列 pstrUserName pstrPassword

nPort
サーバーで使用する TCP/IP ポートを識別する番号。

bPassive
この FTP セッションのパッシブまたはアクティブ モードを指定します。 TRUE に設定すると、Win32 API dwFlag がINTERNET_FLAG_PASSIVEに設定されます。

解説

CFtpConnection オブジェクトを直接作成することはありません。 代わりに、 CInternetSession::GetFtpConnection を呼び出して、 CFptConnection オブジェクトを作成します。

CFtpConnection::Command

FTP サーバーに直接コマンドを送信します。

CInternetFile* Command(
    LPCTSTR pszCommand,
    CmdResponseType eResponse = CmdRespNone,
    DWORD dwFlags = FTP_TRANSFER_TYPE_BINARY,
    DWORD_PTR dwContext = 1);

パラメーター

pszCommand
送信されるコマンドが含まれている文字列へのポインター。

eResponse
FTP サーバーからの応答が必要かどうかを指定します。 値は、次のいずれかです。

  • CmdRespNone 応答は想定されません。
  • CmdRespRead 応答が必要です。
  • CmdRespWrite 使用されません。

CmdResponseType は CFtpConnection のメンバーであり、 afxinet.h で定義されています。

dwFlags
この関数を制御するフラグが含まれている値。 完全な一覧については、 FTPCommand を参照してください。

dwContext
コールバックでアプリケーションのコンテキストを識別するために使用されるアプリケーション定義の値が含まれている値へのポインター。

戻り値

正常終了した場合は 0 以外を返します。それ以外の場合は 0 を返します。

解説

このメンバー関数は、Windows SDK で説明されているように、 FTPCommand 関数の機能をエミュレートします。

エラーが発生した場合、MFC は型 CInternetException の例外をスローします。

CFtpConnection::CreateDirectory

このメンバー関数を呼び出して、接続されているサーバーにディレクトリを作成します。

BOOL CreateDirectory(LPCTSTR pstrDirName);

パラメーター

pstrDirName
作成するディレクトリの名前を含む文字列へのポインター。

戻り値

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

解説

GetCurrentDirectoryを使用して、サーバーへのこの接続の現在の作業ディレクトリを決定します。 リモート・システムがルート・ディレクトリーに接続したと想定しないでください。

pstrDirName パラメーターには、現在のディレクトリに対する部分的なファイル名または完全修飾ファイル名を指定できます。 円記号 (\) またはスラッシュ (/) は、いずれかの名前のディレクトリ区切り記号として使用できます。 CreateDirectory は、ディレクトリ名の区切り記号を使用する前に適切な文字に変換します。

CFtpConnection::GetCurrentDirectory

このメンバー関数を呼び出して、現在のディレクトリの名前を取得します。

BOOL GetCurrentDirectory(CString& strDirName) const;

BOOL GetCurrentDirectory(
    LPTSTR pstrDirName,
    LPDWORD lpdwLen) const;

パラメーター

strDirName
ディレクトリの名前を受け取る文字列への参照。

pstrDirName
ディレクトリの名前を受け取る文字列へのポインター。

lpdwLen
次の情報を含む DWORD へのポインター。

エントリ時: pstrDirName によって参照されるバッファーのサイズ。

戻り値: pstrDirNameに格納される文字数。 メンバー関数が失敗し、ERROR_INSUFFICIENT_BUFFERが返された場合、 lpdwLen には、文字列を受け取るためにアプリケーションが割り当てる必要があるバイト数が含まれます。

戻り値

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

解説

代わりにディレクトリ名を URL として取得するには、 GetCurrentDirectoryAsURL を呼び出します。

パラメーター pstrDirName または strDirName は、現在のディレクトリを基準にして部分的に修飾されたファイル名または完全修飾ファイル名にすることができます。 円記号 (\) またはスラッシュ (/) は、いずれかの名前のディレクトリ区切り記号として使用できます。 GetCurrentDirectory は、ディレクトリ名の区切り記号を使用する前に適切な文字に変換します。

CFtpConnection::GetCurrentDirectoryAsURL

このメンバー関数を呼び出して、現在のディレクトリの名前を URL として取得します。

BOOL GetCurrentDirectoryAsURL(CString& strDirName) const;

BOOL GetCurrentDirectoryAsURL(
    LPTSTR pstrName,
    LPDWORD lpdwLen) const;

パラメーター

strDirName
ディレクトリの名前を受け取る文字列への参照。

pstrDirName
ディレクトリの名前を受け取る文字列へのポインター。

lpdwLen
次の情報を含む DWORD へのポインター。

エントリ時: pstrDirName によって参照されるバッファーのサイズ。

戻り値: pstrDirNameに格納される文字数。 メンバー関数が失敗し、ERROR_INSUFFICIENT_BUFFERが返された場合、 lpdwLen には、文字列を受け取るためにアプリケーションが割り当てる必要があるバイト数が含まれます。

戻り値

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

解説

GetCurrentDirectoryAsURL は、 GetCurrentDirectory と同じように動作します

パラメーター strDirName は、現在のディレクトリを基準にして部分的に修飾されたファイル名または完全修飾ファイル名を指定できます。 円記号 (\) またはスラッシュ (/) は、いずれかの名前のディレクトリ区切り記号として使用できます。 GetCurrentDirectoryAsURL は、ディレクトリ名の区切り記号を使用する前に適切な文字に変換します。

CFtpConnection::GetFile

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
ファイル取得のコンテキスト識別子。 dwContextの詳細については、「Remarks」を参照してください。

戻り値

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

解説

GetFile は、FTP サーバーからのファイルの読み取りとローカルへの格納に関連するすべてのオーバーヘッドを処理する高レベルルーチンです。 ファイル データのみを取得するアプリケーション、またはファイル転送を厳密に制御する必要があるアプリケーションでは、代わりに OpenFile と CInternetFile::Read を使用する必要があります。

dwFlagsがFILE_TRANSFER_TYPE_ASCIIされている場合、ファイル データの変換により、コントロール文字と書式設定文字も Windows に相当するものに変換されます。 既定の転送はバイナリ モードで、ファイルはサーバーに格納されているのと同じ形式でダウンロードされます。

pstrRemoteFileとpstrLocalFileは、現在のディレクトリを基準にして部分的に修飾されたファイル名または完全修飾ファイル名を指定できます。 円記号 (\) またはスラッシュ (/) は、いずれかの名前のディレクトリ区切り記号として使用できます。 GetFile は、ディレクトリ名の区切り記号を使用する前に適切な文字に変換します。

コンテキスト識別子を選択した値に設定するには既定の dwContext をオーバーライドします。 コンテキスト識別子は、CInternetSession オブジェクトによって作成されたCFtpConnection オブジェクトのこの特定の操作に関連付けられています。 値は CInternetSession::OnStatusCallback に返され、識別される操作の状態を指定します。 コンテキスト識別子の詳細については、「 Internet First Steps: WinInet 」を参照してください。

CFtpConnection::OpenFile

このメンバー関数を呼び出して、FTP サーバーにあるファイルを読み取りまたは書き込み用に開きます。

CInternetFile* OpenFile(
    LPCTSTR pstrFileName,
    DWORD dwAccess = GENERIC_READ,
    DWORD dwFlags = FTP_TRANSFER_TYPE_BINARY,
    DWORD_PTR dwContext = 1);

パラメーター

pstrFileName
開くファイルの名前を含む文字列へのポインター。

dwAccess
ファイルへのアクセス方法を決定します。 GENERIC_READでもGENERIC_WRITEでもかまいませんが、両方を指定することはできません。

dwFlags
後続の転送が発生する条件を指定します。 これには、次の FTP_TRANSFER_* クラスの定数のいずれかを指定できます。

  • FTP_TRANSFER_TYPE_ASCII FTP ASCII (タイプ A) 転送方法を使用したファイル転送。 コントロールと書式設定の情報をローカルの同等の情報に変換します。

  • FTP_TRANSFER_TYPE_BINARY ファイルは、FTP の Image (Type I) 転送方法を使用してデータを転送します。 このファイルは、データが存在するとおりに、変更なしで転送されます。 これが既定の転送方法です。

dwContext
ファイルを開くコンテキスト識別子。 dwContextの詳細については、「Remarks」を参照してください。

戻り値

CInternetFile オブジェクトへのポインター。

解説

OpenFile は、次の状況で使用する必要があります。

  • アプリケーションには、FTP サーバー上のファイルとして送信および作成する必要があるデータがありますが、そのデータはローカル ファイルに含まれていません。 ファイル OpenFile 開くと、アプリケーションは CInternetFile::Write を使用して FTP ファイル データをサーバーに送信します。

  • アプリケーションは、ファイルをディスクに書き込むのではなく、サーバーからファイルを取得し、アプリケーションによって制御されるメモリに配置する必要があります。 アプリケーションは、OpenFileを使用してファイルを開いた後、CInternetFile::Read を使用します。

  • アプリケーションでは、ファイル転送を細かく制御する必要があります。 たとえば、アプリケーションでは、ファイルのダウンロード中にファイル転送状態の進行状況を示す進行状況コントロールを表示できます。

OpenFileを呼び出した後、CInternetFile::Closeを呼び出すまで、アプリケーションは CInternetFile::Read、CInternetFile::Write、CInternetConnection::Close、または CFtpFileFind::FindFile のみを呼び出すことができます。 同じ FTP セッションに対する他の FTP 関数の呼び出しは失敗し、エラー コードがFTP_ETRANSFER_IN_PROGRESSに設定されます。

pstrFileName パラメーターには、現在のディレクトリを基準とする部分修飾ファイル名または完全修飾ファイル名を指定できます。 円記号 (\) またはスラッシュ (/) は、いずれかの名前のディレクトリ区切り記号として使用できます。 OpenFile では、使用する前に、ディレクトリ名の区切り記号が適切な文字に変換されます。

コンテキスト識別子を選択した値に設定するには既定の dwContext をオーバーライドします。 コンテキスト識別子は、CInternetSession オブジェクトによって作成されたCFtpConnection オブジェクトのこの特定の操作に関連付けられています。 値は CInternetSession::OnStatusCallback に返され、識別される操作の状態を指定します。 コンテキスト識別子の詳細については、「 Internet First Steps: WinInet 」を参照してください。

CFtpConnection::P utFile

FTP サーバーにファイルを格納するには、このメンバー関数を呼び出します。

BOOL PutFile(
    LPCTSTR pstrLocalFile,
    LPCTSTR pstrRemoteFile,
    DWORD dwFlags = FTP_TRANSFER_TYPE_BINARY,
    DWORD_PTR dwContext = 1);

パラメーター

pstrLocalFile
ローカル システムから送信するファイルの名前を含む文字列へのポインター。

pstrRemoteFile
FTP サーバー上に作成するファイルの名前を含む文字列へのポインター。

dwFlags
ファイルの転送の条件を指定します。 OpenFileで説明されているFTP_TRANSFER_* クラスの定数のいずれかを指定できます。

dwContext
ファイルを配置するためのコンテキスト識別子。 dwContextの詳細については、「Remarks」を参照してください。

戻り値

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

解説

PutFile は、FTP サーバーへのファイルの格納に関連するすべての操作を処理する高レベルのルーチンです。 データのみを送信するアプリケーション、またはファイル転送をより細かく制御する必要があるアプリケーションでは、 OpenFile と CInternetFile::Write を使用する必要があります。

dwContext の既定値をオーバーライドして、コンテキスト識別子を独自の値に設定します。 コンテキスト識別子は、CInternetSession オブジェクトによって作成されたCFtpConnection オブジェクトのこの特定の操作に関連付けられています。 値は CInternetSession::OnStatusCallback に返され、識別される操作の状態を指定します。 コンテキスト識別子の詳細については、「 Internet First Steps: WinInet 」を参照してください。

CFtpConnection::Remove

接続されたサーバーから指定したファイルを削除するには、このメンバー関数を呼び出します。

BOOL Remove(LPCTSTR pstrFileName);

パラメーター

pstrFileName
削除するファイル名を含む文字列へのポインター。

戻り値

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

解説

pstrFileName パラメーターには、現在のディレクトリを基準とする部分修飾ファイル名または完全修飾ファイル名を指定できます。 円記号 (\) またはスラッシュ (/) は、いずれかの名前のディレクトリ区切り記号として使用できます。 Remove関数は、ディレクトリ名の区切り記号を使用する前に適切な文字に変換します。

CFtpConnection::RemoveDirectory

このメンバー関数を呼び出して、接続されているサーバーから指定されたディレクトリを削除します。

BOOL RemoveDirectory(LPCTSTR pstrDirName);

パラメーター

pstrDirName
削除するディレクトリを含む文字列へのポインター。

戻り値

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

解説

GetCurrentDirectory を使用して、サーバーの現在の作業ディレクトリを特定します。 リモート・システムがルート・ディレクトリーに接続したと想定しないでください。

pstrDirName パラメーターには、現在のディレクトリに対する部分的または完全修飾ファイル名を指定できます。 円記号 (\) またはスラッシュ (/) は、いずれかの名前のディレクトリ区切り記号として使用できます。 RemoveDirectory は、ディレクトリ名の区切り記号を使用する前に適切な文字に変換します。

CFtpConnection::Rename

このメンバー関数を呼び出して、接続されているサーバー上の指定されたファイルの名前を変更します。

BOOL Rename(
    LPCTSTR pstrExisting,
    LPCTSTR pstrNew);

パラメーター

pstrExisting
名前を変更するファイルの現在の名前を含む文字列へのポインター。

pstrNew
ファイルの新しい名前を含む文字列へのポインター。

戻り値

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

解説

pstrExisting および pstrNew パラメーターには、現在のディレクトリを基準にした部分的に修飾されたファイル名または完全修飾ファイル名を指定できます。 円記号 (\) またはスラッシュ (/) は、いずれかの名前のディレクトリ区切り記号として使用できます。 Rename は、ディレクトリ名の区切り記号を使用する前に適切な文字に変換します。

CFtpConnection::SetCurrentDirectory

FTP サーバー上の別のディレクトリに変更するには、このメンバー関数を呼び出します。

BOOL SetCurrentDirectory(LPCTSTR pstrDirName);

パラメーター

pstrDirName
ディレクトリの名前を含む文字列へのポインター。

戻り値

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

解説

pstrDirName パラメーターには、現在のディレクトリに対する部分的または完全修飾ファイル名を指定できます。 円記号 (\) またはスラッシュ (/) は、いずれかの名前のディレクトリ区切り記号として使用できます。 SetCurrentDirectory は、ディレクトリ名の区切り記号を使用する前に適切な文字に変換します。

GetCurrentDirectory を使用して、FTP サーバーの現在の作業ディレクトリを特定します。 リモート・システムがルート・ディレクトリーに接続したと想定しないでください。

関連項目

CInternetConnection クラス
階層図
CInternetConnection クラス
CInternetSession クラス