動作情報の取得
==============

libarms から、動作中の情報をAPI を経由して取得・通知することができる。以下にその詳細を示す。

libarms バージョン情報
-----------------------

================================ ====================================================
API 名                           解説
================================ ====================================================
:c:func:`arms_library_ver_major` libarms ライブラリのメジャーバージョン番号を取得する
:c:func:`arms_library_ver_minor` libarms ライブラリのマイナーバージョン番号を取得する
================================ ====================================================

ARMS プロトコルバージョン情報
-----------------------------

================================== ====================================================
API 名                             解説
================================== ====================================================
:c:func:`arms_protocol_ver_major`  ARMS プロトコルのメジャーバージョン番号を取得する
:c:func:`arms_protocol_ver_minor`  ARMS プロトコルのマイナーバージョン番号を取得する
================================== ====================================================

RS 用情報
---------

======================================== ====================================================
API 名                                   解説
======================================== ====================================================
:c:func:`arms_get_rsinfo`                RSがPushに用いるアドレスを取得する
:c:func:`arms_get_rs_url`                SAからRSにメッセージを送る際の送信先URLを取得する
:c:func:`arms_get_rs_tunnel_url`         SSLトンネル接続先RSのURLを取得する
:c:func:`arms_get_proposed_push_port`    Pushに用いるポート番号の提案値を取得する
:c:func:`arms_get_proposed_push_timeout` Pushのタイムアウト時間の提案値を取得する
:c:func:`arms_get_app_event_interval`    :c:func:`arms_app_event_cb_t` 呼び出し間隔を取得
:c:func:`arms_set_app_event_interval`    :c:func:`arms_app_event_cb_t` 呼び出し間隔を設定
======================================== ====================================================

これらの関数は、 :c:func:`arms_pull` によりRS からのPull が完了した後、呼び出すことができる。

:c:func:`arms_get_rsinfo` 、 :c:func:`arms_get_rs_url` 、 :c:func:`arms_get_rs_tunnel_url` を用いて、SA にて適切なフィルタ(RS への接続のみを許可するためのフィルタなど) を構成することが可能となる。

:c:func:`arms_get_proposed_push_port` では、RS から提案される Push 待ち受けポート番号の値を取得することができる。ここで取得した値を :c:func:`arms_event_loop` の port 引数にセットすることが望ましい。

:c:func:`arms_get_proposed_push_timeout` では、RSから提案される Push のタイムアウト時間の提案値を取得することができる。
Push されたコマンドによっては、時間を要する場合もあることが想定されるが(ファームウェアのアップデートや、サポート情報の収集など)、その場合でもこのタイムアウト時間の提案値を超えないように終了することが必要。
タイムアウト時間の提案値はRS管理者が決定するため、もし時間が不足するようであれば管理者に連絡して設定変更を依頼する必要がある。

:c:func:`arms_get_app_event_interval` 、 :c:func:`arms_set_app_event_interval` ではイベントコールバック関数の呼び出し間隔を取得および設定することができる。なお、標準の呼び出し間隔は60秒となっている。
イベントコールバック関数は、主にWAN側アドレスの変更や接続状況の変化をlibarmsに伝えるために用いられるが、
標準ではその検出間隔が60秒となってしまう。これを更に短くしたい場合や長くしたい場合にこのAPIを用いて設定が可能となる。

Heartbeat 送信用情報(特定ベンダ向け)
--------------------------------------

================================ ====================================================
API 名                           解説
================================ ====================================================
:c:func:`arms_get_hbtinfo`       Heartbeat 送信に必要な情報を取得する
================================ ====================================================

この関数は、 :c:func:`arms_pull` によりRS からのPull が完了した後、呼び出すことができる。
libarms Ver5.00 以降は libarms 自身に Heartbeat 送信機能が含まれており、これを利用する場合は
このAPIは呼び出し不要となる。
