ライブラリの使用方法

JP1/FTP APIライブラリは，JP1/FTPのファイル伝送機能をユーザプログラムから利用するときに使用します。APIライブラリは，32ビット用（ILP32データモデル）および64ビット用（LP64データモデル）を提供しています。

JP1/FTP APIライブラリを使用して，次のことができます。

1つのユーザプログラムから複数のホスト上（同一ホストでもよい）で動作する複数のJP1/FTPに伝送要求を登録できます。
伝送要求の登録には，同期型と非同期型があります。

同期型：伝送が終了するまで待ち，終了結果を取得できます。

非同期型：登録だけをして，あとで終了結果だけを取得できます。

〈このページの構成〉

言語
環境設定
コーディング
伝送終了情報の取得
コンパイルとリンク
ライブラリ使用時の注意事項

言語

ユーザプログラムで使用できる言語を次に示します。

ページの先頭へ

環境設定

/etc/servicesの設定

JP1/FTP Clientのサービス名「ftsc」を設定します。詳しくは，「2.3.3 ポート番号を設定する」を参照してください。

/etc/hostsの設定

クライアント側のJP1/FTPデーモンが動作しているホストのホスト名とIPアドレスを設定します。このホスト名は接続情報構造体，伝送情報構造体で指定します。

/etc/hostsに次の1行を追加してください。

xxx.xxx.xxx.xxx      yyyyyy

（凡例）

xxx.xxx.xxx.xxx ：IPアドレス

yyyyyy：ホスト名

ページの先頭へ

コーディング

JP1/FTPとのコネクション確立情報の指定

JP1/FTPデーモンとのコネクション確立は，fts_ftp_open_ex()の引数に接続情報構造体のアドレスを設定します。

接続情報構造体

typedef struct _FTS_FTP_API_CONN_DATA {
    char hostname[256+1];           /* ホスト名 (クライアント) */
    int priority;                   /* 優先IPバージョン */
    char reserve[1784];             /* 予約領域 */
} FTS_FTP_API_CONN_DATA;

接続情報構造体メンバの内容
- hostname：クライアント側のJP1/FTPデーモンが動作しているホストのホスト名またはIPアドレスを指定します。IPアドレスの場合，IPv4またはIPv6アドレスを指定できます。NULLを指定した場合は，自ホスト名（OSのhostnameコマンドが返すホスト名：物理ホスト）が仮定されます。
  
  FTPクライアントでの自IPアドレスの指定を有効にした場合，この引数での指定がFTPクライアントの自IPアドレスになります。NULLを指定した場合は，FTPクライアントの物理ホストが仮定されます。
  
  FTPクライアントでの自IPアドレスの指定を無効にした場合，FTPクライアントの自IPアドレスは，OSが自動的に割り当てるアドレスになります。FTPクライアントでの自IPアドレスの指定を有効にする定義については，「3.15 複数IPアドレス環境での使用」を参照してください。
- priority：優先するインターネットプロトコルバージョンを指定します。
  
  FTS_AF_INET：IPv4を優先します。
  
  FTS_AF_INET6：IPv6を優先します。
  
  上記以外の場合，FTS_AF_INETを仮定します。
- reserve：予約領域です。「\0」で初期化してください。

注意事項: char型の変数値の最後は，「\0」にしてください。

伝送情報の指定

ファイル伝送要求の登録は，fts_ftp_syn_request_ex(),fts_ftp_asyn_request_ex()の引数に登録済みの伝送カード名や伝送情報構造体のアドレスを設定します。

カード名称による伝送要求の登録

［伝送の登録／実行］で登録した伝送カード名を指定することで，伝送要求を登録できます。
伝送情報構造体による伝送情報の指定

伝送に必要な情報を指定することで，伝送要求を登録できます。

伝送情報構造体

typedef struct _FTS_FTP_API_DATA_EX {
    char cardname[20+1];            /* カード名称 */
    char host[256+1];               /* 相手ホスト名 */
    unsigned int portnum;           /* ポート番号 */
    char username[80];              /* 相手ユーザ名 */
    char password[80];              /* パスワード */
    int type;                       /* 伝送モード */
    int cmd;                        /* 送受信種別 */
    int mode;                       /* 圧縮モード */
    char quote[300+1];              /* FTPコマンド */
    char localname[256+1];          /* ローカルファイル名 */
    char remotename[256+1];         /* リモートファイル名 */
    char end_program[256+1];        /* 正常時起動プログラム名*/
    char abend_program[256+1];      /* 異常時起動プログラム名 */
    char comment[80+1];             /* コメント */
    int fsize;                      /* サイズ確認 */
    int ftps;                       /* FTPS使用 */
    int scertval;                   /* サーバ証明書有効期限確認 */
    char cacertpath[256+1];         /* CA証明書パス名 */
    char crlpath[256+1];            /* CRLパス名 */
    char reserve[716];              /* 予約領域 */
} FTS_FTP_API_DATA_EX;

伝送情報構造体メンバの内容
- cardname：カード名称を指定します。
- host：FTPのホスト名を指定します。ftp>open aaaa
- portnum：FTPのポート番号を指定します。ftp>open aaaa bbbb
- username：ログイン名を指定します。ftp>user aaaa
- password：パスワードを指定します。
- type：伝送モードを指定します。
  
  FTS_TYPE_A：データをASCIIコードと解釈し，送信します。ftp>ascii
  
  FTS_TYPE_I：データをイメージと解釈し，送信します。ftp>binary
- cmd：伝送の種類を指定します。
  
  単／複伝送をORで指定することで，単一ファイル伝送または複数ファイル伝送を組み合わせて指定できます。
  
  伝送の種類
  
  　FTS_CMD_SEND：送信します。ftp>put aaaa bbbb
  
  　FTS_CMD_RECV：受信します。ftp>get cccc ddddd
  
  　FTS_CMD_APPE：送信（追加）します。ftp>append eeee fffff
  
  単／複伝送
  
  　FTS_MLT_AUTO：単一と複数ファイル伝送を自動で切り替えます。デフォルトです。
  
  　FTS_MLT_MULTIPLE：複数ファイル伝送をします。
  
  　FTS_MLT_SINGLE：単一ファイル伝送をします。
  
  　FTS_MLT_AUTOでは，次のように伝送が自動切り替えされます。
  
  　送信の場合：ローカルファイル名に，*または?が使用されているか判定し，*または?が使用されていれば複数ファイル伝送に，使用されていなければ単一ファイル伝送に切り替わります。
  
  　受信の場合：リモートファイル名に，*または?が使用されているか判定し，*または?が使用されていれば複数ファイル伝送に，使用されていなければ単一ファイル伝送に切り替わります。
  
  （例）
  
  　複数ファイルの送信
  
  　cmd = FTS_CMD_SEND | FTS_MLT_MULTIPLE;
  
  　単一ファイルの受信
  
  　cmd = FTS_CMD_RECV | FTS_MLT_SINGLE;
  
  　自動切替で送信（追加）
  
  　cmd = FTS_CMD_APPE | FTS_MLT_AUTO;
  
  　または
  
  　cmd = FTS_CMD_APPE;
  
  　（単／複伝送指定を省略するとFTS_MLT_AUTOになります）
- mode：圧縮伝送を指定します。
  
  FTS_MODE_S：圧縮伝送をしません。
  
  FTS_MODE_C：圧縮伝送をします。
- quote：実行したいFTPコマンドを指定します。
  
  CWD，SITEなどのコマンドをセミコロン（';'）で区切った文字列（文字列の最後は'\0'）で指定します。
  
  指定できるコマンドは，データコネクションを確立しないコマンドに限られます。また，FTPサーバ側でコマンドが実行できるかどうかは，FTPサーバに依存します。
- localname：ローカルファイル名を指定します。
  
  （例）
  
  　ftp>put aaaa bbbb
  
  　ftp>get cccc dddd
- remotename：リモートファイル名を指定します。
  
  （例）
  
  　ftp>put aaaa bbbb
  
  　ftp>get cccc dddd
- end_program：伝送正常終了時に起動するプログラム名をフルパスで指定します。
- abend_program：伝送異常終了時に起動するプログラム名をフルパスで指定します。
- comment：任意の文字列を指定できます。
- fsize：伝送後のファイルサイズ確認の有無を指定します。
  
  FTS_FSIZE_TRUE：サイズ確認をします。
  
  FTS_FSIZE_FALSE：サイズ確認をしません。
- ftps：FTPS使用の有無を指定します。
  
  FTS_FTPS_TRUE：FTPSを使用します。
  
  FTS_FTPS_FALSE：FTPSを使用しません。
- scertval：サーバ証明書の有効期限確認の有無を指定します。
  
  FTS_SCVAL_TRUE：有効期限確認をします。
  
  FTS_SCVAL_FALSE：有効期限確認をしません。
- cacertpath：CA証明書ファイルのパス名をフルパスで指定します。
- crlpath：CRLファイルのパス名をフルパスで指定します。
- reserve：予約領域です。「\0」で初期化してください。

注意事項: char型の変数値の最後は，「\0」にしてください。

ページの先頭へ

伝送終了情報の取得

fts_ftp_syn_request_ex(),fts_ftp_asyn_request_ex()で登録した伝送要求に対する終了情報を取得できます。

fts_ftp_syn_request_ex()で要求を登録した場合

fts_ftp_syn_request_ex()の第4引数に伝送終了情報構造体のアドレスを指定します。
fts_ftp_asyn_request_ex()で要求を登録した場合

fts_ftp_event_ex()の第2引数に伝送終了情報構造体のアドレスを指定します。

伝送終了情報構造体

typedef struct _FTS_FTP_API_RETDATA_EX {
  /* 常時のデータ */
  int trans_status;               /* 伝送終了状態 成功(TRANS_SUCCESS)  */
                                  /* 伝送終了情報 失敗(TRANS_FAILURE)  */
  char cardname[20+1];            /* カード名称 */
  unsigned long trno;             /* 伝送番号 */
  unsigned long trcno;            /* 接続番号 */
 
  /* 伝送成功時のデータ */
  unsigned long trans_size;       /* 伝送データサイズ */
 
  /* 伝送（圧縮）成功時のデータ */
  unsigned long trans_size_comp;  /* 圧縮後伝送データサイズ */
 
  /* 失敗時のデータ */
  int ab_kind;                     /* システムコールエラー(FTS_ERR_SYSTEM) */
                                  /* 論理エラー(FTS_ERR_LOGIC) */
                                  /* プロトコルエラー(FTS_ERR_PROTOCOL) */
                                  /* 強制終了エラー(FTS_ERR_FORCE) */
                                  /* SSL通信エラー(FTS_ERR_SSL) */
  char ab_place[8];               /* エラー発生場所 */
  char ab_func[32];               /* エラー発生モジュール名称 */
  char ab_system[32];             /* システムコール名称 */
  unsigned long ab_errno;         /* エラー番号 */
  char ab_promes[256];            /* プロトコルメッセージ（エラー） */
 
#ifndef FTS_API_64BIT
  char full_trans_size[8];        /* 伝送データサイズ */
  char full_trans_size_comp[8];   /* 圧縮後伝送データサイズ */
#endif
 
  int ab_sslerno;                 /* SSL通信エラー番号 */
  char reserve[1668];             /* 予約領域 */
} FTS_FTP_API_RETDATA_EX;

伝送終了情報構造体メンバの内容
- trans_status：伝送の終了状態を示す次の値を返します。
  
  TRANS_SUCCESS（正常終了）
  
  TRANS_FAILURE（異常終了）
- cardname：伝送のカード名称を返します。
- trno：伝送番号を返します。
- trcno：接続番号を返します。
- trans_size：（正常終了時だけ）
  
  伝送データサイズ（伝送データサイズが4ギガバイト未満のときだけ参照可能です）
- trans_size_comp：（正常終了時だけ）
  
  圧縮後伝送データサイズ（圧縮後伝送データサイズが4ギガバイト未満のときだけ参照可能です）
- ab_kind：（異常終了時だけ）
  
  エラー種別を返します。
  
  FTS_ERR_SYSTEM（システムコールエラー）
  
  FTS_ERR_LOGIC（論理エラー）
  
  FTS_ERR_PROTOCOL（プロトコルエラー）
  
  FTS_ERR_FORCE（強制終了エラー）
  
  FTS_ERR_SSL（SSL通信エラー）
- ab_place：（異常終了時だけ）
  
  エラー発生場所を返します。
- ab_func：（異常終了時だけ）
  
  エラー発生モジュール名称を返します。
- ab_system：（異常終了時だけ）
  
  システムコール名称を返します。
- ab_errno：（異常終了時だけ）
  
  システムコールエラー番号を返します。
  
  値は，次のとおりです。
  
  2000：システム関数（システムコール名称）操作中にタイムアウトを検出しました。
  
  2001：システム関数（システムコール名称）操作中に伝送ファイルサイズのアンマッチを検出しました。
  
  2003：システム関数（システムコール名称）操作中にJP1/FTPで伝送できるファイルサイズの上限を超えました。
  
  その他：システム関数（システムコール名称）が返却した値となりますが，システム関数によって次のように返却対象が異なります。
  
  　getaddrinfo 関数の場合：getaddrinfoの戻り値（Linuxの場合は，負の値となりますが，符号なしに変換されます）
  
  　getnameinfo関数の場合：getnameinfoの戻り値（Linuxの場合は，負の値となりますが，符号なしに変換されます）
  
  　その他の関数の場合：errnoの値
- ab_promes：（異常終了時だけ）
  
  サーバ（着信側）より送られてきたプロトコルメッセージを返します。
- full_trans_size：（正常終了時だけ）
  
  伝送データサイズ（fts_ftp_buftoll()を使用して参照します）
- full_trans_size_comp：（正常終了時だけ）
  
  圧縮後伝送データサイズ（fts_ftp_buftoll()を使用して参照します）
- ab_sslerno：（異常終了時だけ）
  
  SSL通信エラー番号を返します。
- reserve：予約領域です。

ページの先頭へ

コンパイルとリンク

64ビット用を使用する場合，コンパイルオプションにFTS_API_64BITを指定してください。

（例）cc -DFTS_API_64BIT -c sample.c
fts_ftp_buftoll()を使用する場合，コンパイルオプションにFTS_NO_TRANSIZE_LIMITを指定してください。

（例）cc -DFTS_NO_TRANSIZE_LIMIT -c sample.c
次に示すライブラリをリンクしてください。

32ビット用：libftsftp_r.so

64ビット用：libftsftp64_r.so
HP-UXの場合，libpthread.slをリンクしてください。
Solarisの場合，libpthread.soをリンクしてください。
Solarisの場合，-L，-Rオプションを指定してください。
Linuxの場合，リンクオプションに-lpthreadを指定してください。

ページの先頭へ

ライブラリ使用時の注意事項

APIライブラリは，マルチスレッドに対応しています。
次のような使用方法はできません。

1つのfts_ftp_open_ex()で複数のfts_ftp_syn_request_ex(),fts_ftp_asyn_request_ex()を同時に発行（マルチプロセスによるfts_ftp_syn_request_ex()，fts_ftp_asyn_request_ex()の同時実行）
ワイルドカードを指定した場合，取得できる伝送終了情報は，次のとおりです。

正常の場合：最後に伝送したファイルの伝送終了情報

異常の場合：最初に異常になったファイルの伝送終了情報
Linuxの場合，次の環境変数にライブラリのパスを指定してください。

LD_LIBRARY_PATH

（例）bashの場合

LD_LIBRARY_PATH=/opt/jp1_fts/lib/api/apilib

export LD_LIBRARY_PATH

（例）cshの場合

setenv LD_LIBRARY_PATH /opt/jp1_fts/lib/api/apilib
32ビット用では，伝送データサイズまたは圧縮後伝送データサイズが4ギガバイト以上になる場合，伝送終了情報構造体メンバのtrans_sizeおよびtrans_size_compは参照できません。trans_sizeおよびtrans_size_compは，unsigned long型であり，ILP32データモデルの場合，4ギガバイト以上になるとオーバーフローするためです。伝送データサイズまたは圧縮後伝送データサイズが4ギガバイト以上になる場合，伝送終了情報構造体メンバのfull_trans_sizeまたはfull_trans_size_compをfts_ftp_buftoll()で数値に変換して参照してください。
HP-UXの場合，HP-UX 11.0以降のカーネル・スレッドにだけ対応しています。DCEスレッドでは動作できません。
POSIXスレッドにだけ対応しています。
fts_errnoには値を設定できません。参照だけできます。
プロセスで1回fts_ftp_open_ex()をコールし，複数スレッドでfts_ftp_syn_request_ex()を同時にコールすると，伝送はシリアルに行います。同時伝送する場合はfts_ftp_syn_request_ex()のコールごとに，fts_ftp_open_ex()をコールしてください。なお，fts_ftp_open_ex()をコールする回数分，fts_ftp_close()も必要です。
1つの fts_ftp_open_ex()でfts_ftp_syn_request_ex()，fts_ftp_asyn_request_ex()を混在してコールすることはできません。混在させた場合，伝送結果が正常に受け取れません。
全API関数は，スレッドの取り消し点となります。
スレッドの取り消しが行われた場合，取り消されたスレッドで使用していたJP1/FTPデーモンとのコネクションは，fts_ftp_close()で必ず解放してください。解放しないでコネクションを継続して使用した場合，伝送結果が正常に受け取れません。

ページの先頭へ