CLX C++ Libraries
Home >> ftp

Declaration

template <
    class Socket,
    class Acceptor
>
class basic_ftp : public Socket;

typedef basic_ftp<tcp::socket, tcp::acceptor> ftp;

Overview

ftp クラスは FTP (File Transfer Protocol) でファイルの転送を行うためのクラスです. start() メソッドで FTP サーバと接続し,login() メソッドでログイン処理を行った後, 各種メソッドを用いて FTP サーバと通信を行います.

FTP では,ファイルの送受信はデータコネクションを用いて行われます.そのため, ファイル転送を行う場合は,データコネクションの接続方法を指定する必要があります. 接続方法には,FTP サーバからクライアントへ向けてコネクションが確立されるアクティブ接続 (PORT コマンド)とクライアントから FTP サーバへ向けてコネクションが確立される パッシブ接続(PASV コマンド)が存在します.どちらの接続方法を用いるかは, 引数に clx::ftp::active, clx::ftp::passive を指定して選択します. 尚,デフォルトの接続方法はパッシブ接続を用いています.

ftp クラスは,サーバからエラーメッセージが返された場合には ftp_error を例外として送出します. また,ftp クラスはサーバからの応答メッセージを内部に蓄積するように実装しています. responses() メソッドを呼ぶと,サーバからの応答メッセージの一覧を取得することができます.

Example

example_ftp.cpp

#include <iostream>
#include <string>
#include <sstream>
#include "clx/ftp.h"

int main(int argc, char* argv[]) {
    if (argc < 4) {
        std::cerr << "usage " << argv[0] << " host id pass" << std::endl;
        std::exit(-1);
    }
    
    try {
        clx::ftp session(argv[1], 21);
        
        // 各種コマンドのテスト
        session.login(argv[2], argv[3]);
        session.status();
        session.system();
        session.command("HELP");
        session.cd("/public_html");
        session.pwd();
        session.mkdir("tmp");
        session.rmdir("tmp");
        
        /*
         * list(), retrieve(), store() はデータコネクションを使用する.
         * データコネクションを用いるメソッドは,最後の引数に
         * アクティブ接続 (clx::ftp::active) かパッシブ接続 (clx::ftp::passive)
         * を指定する.尚,省略時はパッシブ接続.
         */
        session.list("/public_html");
        session.retrieve("/public_html/index.html", "./result.txt", clx::ftp::binary);
        session.store("./example_ftp.cpp", "/public_html/example_ftp.cpp");
        
        session.remove("/public_html/example_ftp.cpp");
        session.finish();
        
        // print message log
        clx::ftp::response_array::reverse_iterator pos;
        for (pos = session.responses().rbegin();
            pos != session.responses().rend(); ++pos) {
            std::cout << pos->second << std::endl;
            std::cout << std::endl;
        }
    }
    catch (clx::ftp_error& e) {
        std::cerr << e.code() << ": " << e.what() << std::endl;
        std::exit(-1);
    }
    catch (clx::socket_error& e) {
        std::cerr << e.what() << std::endl;
        std::exit(-1);
    }
    catch (std::runtime_error& e) {
        std::cerr << e.what() << std::endl;
        std::exit(-1);
    }
    
    return 0;
}
Result
ProFTPD  

Password required for cielquis.

User cielquis logged in.

Status of 'FTP SERVER'
 Connected from 61.127.142.47 (61.127.142.47)
 Logged in as cielquis
 TYPE: ASCII, STRUcture: File, Mode: Stream
 No data connection
End of status

・・・(中略)・・・

Goodbye.

Template Parameters

Socket
ソケットクラスを指定します.
Acceptor
サーバ用のソケットクラスを指定します.

Related Types

typedef Socket socket_type;
typedef Acceptor acceptor_type;
typedef char char_type;
typedef std::basic_string<char_type> string_type;

typedef std::pair<int, string_type> response_type;
typedef std::deque<response_type> response_array;

Construction and Member Functions

basic_ftp();
basic_ftp(const basic_ftp& cp);
explicit basic_ftp(const string_type& host, int port = 21);
explicit basic_ftp(const char_type* host, int port = 21);
virtual ~basic_ftp();

basic_smtp& start(const string_type& host, int port = 21);
basic_smtp& start(const char_type* host, int port = 21);

void finish();

basic_smtp& login(const string_type& id, const string_type& pass);
basic_smtp& login(const char_type* id, const char_type* pass);

start() メソッドで FTP サーバと接続し,login() メソッドでログイン処理を行います.

string_type pwd();
string_type system();
string_type status(const string_type& name = "");

pwd() メソッドはリモートホストのカレントディレクトリを返します.ただし, pwd() はサーバからの応答をそのまま返します.そのため,カレントディレクトリを表す path 以外の文字列が含まれる場合もあります(テスト環境では,"/public_html" is current directory. という文字列が返された).

system(),status() メソッドはそれぞれ SYST,STAT コマンドの結果を返します. status() メソッドにファイル名/ディレクトリ名を引数として指定した場合は, 指定されたファイル/ディレクトリに関する情報が返されます.これは,後述する list() メソッドと同等の機能となります.

basic_ftp& noop();
basic_ftp& reset();
basic_ftp& cd(const string_type& dir);
basic_ftp& cdup();
basic_ftp& rename(const string_type& from, const string_type& to);
basic_ftp& remove(const string_type& file);
basic_ftp& rmdir(const string_type& dir);
basic_ftp& mkdir(const string_type& dir);
basic_ftp& command(const string_type& cmd);

FTP サーバに対して各種コマンドを送信します.サーバからの応答は responses() メソッドで取得できるキューに格納されます.

reset() メソッドは REIN コマンドを FTP サーバに送信した後, サーバからの応答の履歴を全て消去します.そのため,reset() メソッドを呼び出した場合は再度 login() メソッドを用いてログインする必要があります.

command() メソッドは SITE コマンドを用いて任意のコマンドを FTP サーバへ送信します. 受け付けるコマンドに関しては,接続した FTP サーバに依存します. 受け付けるコマンドは command("HELP") を用いて調べることができます.ただし, 結果(サーバからの応答)は responses() で取得できるサーバからの応答の履歴に格納されます.

string_type list(const string_type& name = "", int mode = passive);

basic_ftp& retrieve(const string_type& from, const string_type& to,
    int type = ascii, int mode = passive);
basic_ftp& store(const string_type& from, const string_type& to,
    int type = ascii, int mode = passive);

int& port();
int port() const;

list(),retrieve(),store() メソッドはデータコネクションを用いて通信を行います. そのため,アクティブ接続 (clx::ftp::active) かパッシブ接続 (clx::ftp::passive) を選択する必要があります.引数が省略された場合はパッシブ接続で通信を行います. アクティブ接続で通信を行う場合,通信に使用するポート番号は port() メソッドで指定することができます.port() メソッドが呼ばれなかった場合は, デフォルトのポート番号で通信を行います.

retrieve() メソッド,および store() メソッドは通信モード (clx::ftp::active or clx::ftp::passive) の他にファイルタイプを指定する必要があります.ファイルタイプは, アスキーモード (clx::ftp::ascii) とバイナリモード (clx::ftp::binary) が存在します. 引数を省略した場合はアスキーモードで通信を行います.これらのメソッドは,宛先 path に指定したファイル名が既に存在する場合は内容を上書きします.

response_array& responses();
const response_array& responses() const;
const response_type& response(size_t index) const;

response() メソッドは,SMTP サーバからの応答メッセージの一覧を取得するためのメソッドです. それぞれの応答メッセージ (response_type) は,応答コードとメッセージのペアで構成されています. サーバからの応答メッセージはキュー (正確には std::deque) で管理しているため, 最新のメッセージが先頭に格納されています.