Mobile Link インタフェースを使用して、Mobile Link サーバからファイルをダウンロードします。

構文

ul_bool MLFileTransfer ( ml_file_transfer_info * info );                                  

パラメータ

info   ファイル転送情報が格納された構造体。

ML File Transfer パラメータ

ML File Transfer パラメータは、MLFileTransfer 関数にパラメータとして渡される構造体のメンバです。ml_file_transfer_info 構造体は、ヘッダ・ファイル mlfiletransfer.h に定義されています。構造体の各フィールドの定義は次のとおりです。

filename   必須。Mobile Link を実行しているサーバから転送されるファイルの名前。MobiLink は username サブディレクトリを検索してから、デフォルトのルート・ディレクトリを検索します。-ftr オプションを参照してください。

ファイルが見つからなかった場合は、error フィールドにエラーが設定されます。ファイル名にはドライブまたはパスの情報を含めないでください。そのような情報を含めると、ファイルが見えなくなります。

dest_path   ダウンロード・ファイルの格納先となるローカル・パス。このパラメータが空の場合 (デフォルト)、ダウンロード・ファイルは現在のディレクトリに格納されます。

dest_filename   ダウンロード・ファイルのローカル名。このパラメータが空の場合、ファイル名の値が使用されます。

stream   必須。protocol には、TCPIP、TLS、HTTP、HTTPS のいずれか 1 つを指定します。Stream Type 同期パラメータを参照してください。

stream_parms   指定されたストリームのプロトコルのオプション。Ultra Light 同期ストリームのネットワーク・プロトコルのオプションを参照してください。

username   必須。Mobile Link ユーザ名。

password   Mobile Link ユーザ名のパスワード。

version   必須。Mobile Link スクリプトのバージョン。

observer   'observer' フィールドを使用することで、ファイルのダウンロードの進捗状況を確認するコールバックを実現できます。詳細については、後述のコールバック関数の説明を参照してください。

user_data   同期 observer で使用できるようにした、アプリケーション固有の情報。User Data 同期パラメータを参照してください。

force_download   true に設定すると、タイムスタンプからそのファイルが既に存在すると判断される場合でもダウンロードされます。false に設定すると、ファイルはサーバのバージョンとローカルのバージョンが異なる場合にダウンロードされます。この場合、サーバのバージョンによってローカル・クライアントのバージョンが上書きされます。クライアント上に同じ名前のファイルがあると、そのファイルが破棄されてからダウンロードされます。MLFileTransfer は、ファイルのサーバとクライアントのバージョンを比較するために、各ファイルの暗号化ハッシュ値を計算します。ハッシュ値は、ファイルの内容がまったく同じ場合にだけ同じ値になります。

enable_resume   true に設定すると、MLFileTransfer は、通信エラーまたはユーザのキャンセルによって中断した以前のダウンロードを再開します。サーバ上のファイルがローカルの部分ファイルより新しい場合、部分ファイルが破棄され、新しいバージョンがあらためてダウンロードされます。このパラメータより force_download パラメータが優先されます。

num_auth_parms   Mobile Link イベントの認証パラメータに渡される認証パラメータの数。Number of Authentication Parameters パラメータを参照してください。

auth_parms   Mobile Link イベントの認証パラメータにパラメータを渡します。Authentication Parameters 同期パラメータを参照してください。

downloaded_file   次のいずれかに設定されます。

auth_status   Mobile Link のユーザ認証のステータスをレポートします。Mobile Link サーバが、この情報をクライアントに提供します。Authentication Status 同期パラメータを参照してください。

auth_value   カスタム Mobile Link のユーザ認証スクリプトの結果をレポートします。Mobile Link サーバが、この情報をクライアントに提供します。Authentication Value 同期パラメータを参照してください。

file_auth_code   サーバ上の authenticate_file_transfer スクリプト (オプション) のリターン・コードが格納されます。

error   発生したエラーに関する情報が格納されます。

戻り値

備考

転送対象ファイルのソース・ローケーションを設定する必要があります。このロケーションは、Mobile Link サーバ上の Mobile Link ユーザ・ディレクトリ (または Mobile Link サーバ上のデフォルト・ディレクトリ) を指定する必要があります。また、ファイルのターゲット・ロケーションとファイル名を設定することもできます。

たとえば、新しいデータベースまたは置き換えるデータベースを Mobile Link サーバからダウンロードするようにアプリケーションをプログラミングできます。検索される最初のロケーションは各ユーザのサブディレクトリなので、ユーザごとにファイルをカスタマイズできます。サーバのルート・フォルダは、指定ファイルがユーザのフォルダになかった場合に検索されるロケーションなので、デフォルトの転送ファイルは、サーバのルート・フォルダに配置することもできます。

コールバック関数

ファイル転送の進捗状況を observer パラメータを使用して確認するコールバックのプロトタイプは次のとおりです。

typedef void(*ml_file_transfer_observer_fn)( ml_file_transfer_status * status );

コールバックに渡される ml_file_transfer_status オブジェクトは次のように定義されます。

typedef struct ml_file_transfer_status {
    asa_uint64                  file_size;
    asa_uint64                  bytes_received;
    asa_uint64                  resumed_at_size;
    ml_file_transfer_info_a *   info;
    asa_uint16                  flags;
    asa_uint8                   stop;
} ml_file_transfer_status;

file_size   ダウンロード中のファイルの合計サイズ (バイト単位)。

bytes_received   現時点でダウンロード済みのファイルのサイズを示します。再開されたダウンロードの場合は、以前の同期も含みます。

resumed_at_size   ダウンロードの再開で使用され、現在のダウンロードの開始点を示します。

info   MLFileTransfer に渡された info オブジェクトへのポインタ。このポインタを使用して user_data パラメータにアクセスできます。

flags   追加情報が格納されます。MLFileTransfer がネットワーク呼び出しをブロックしており、observer 関数が前回呼び出されたときからダウンロード・ステータスが変わっていない場合、値 MLFT_STATUS_FLAG_IS_BLOCKING が設定されます。

stop   true に設定すると、現在のダウンロードをキャンセルできます。enable_resume パラメータが設定された場合にかぎり、MLFileTransfer を後で呼び出したときにそのダウンロードを再開できます。