(*arms_command_cb_t)()

関数

typedef int (*arms_command_cb_t)(uint32_t id, int action, const char *buff, size_t buff_len, char *result_buff, size_t result_len, int *next, void *udata)

呼び出し方向

libarms->アプリケーション

目的

汎用のコマンド実行指示を処理する。 コールバックテーブルへの登録は必須ではない。

説明

モジュールID ごとに定義されたコマンド実行を指示する。 処理内容があらかじめ定義されている共通アクションと、 機器固有のコマンドを実行する汎用アクションが用意されている。

引数

uint32_t id

モジュールID。ID 自体はSA の機種ごとに定義される。

モジュールID を使用しないaction もある。action の項で個別に記載する。

int action
モジュールID ごとに定義されたアクション。SA の機種に依存しない共通のアクションが定義されている。値の一覧は次のとおり。
ARMS_PUSH_CLEAR_STATUS

モジュールの状態を初期状態に戻す。 buff にはモジュールへの付加情報が文字列あるいはバイナリで格納される。 必要があれば実行結果を result_buff に格納する。

id を使用する。指定されたモジュールに対する操作となる。

ARMS_PUSH_PING

buff で指定された対象に ICMP ECHO パケットを送信し、それに対する応答となる ICMP ECHO REPLY パケットを待ち、その結果を result_buff に格納する。

id を使用しない。0 が渡されるが無視してよい。

ARMS_PUSH_TRACEROUTE

buff で指定された対象にtraceroute 処理を実行し、その結果をresult_buff に格納する。

id を使用しない。0 が渡されるが無視してよい。

ARMS_PUSH_MD_COMMAND

汎用アクションを実行する。 buff には機種依存のコマンドが文字列あるいはバイナリで格納される。 この実行結果をresult_buff に格納する。

id を使用する。指定されたモジュールに対する操作となる。

ARMS_PUSH_DUMP_DEBUG

ログやコンフィグなど、デバッグ情報をresult_buff に格納する。

id を使用しない。0 が渡されるが無視してよい。

const char *buff

action ごとの個別パラメータを格納すべきlibarms 内のバッファ。 バッファとしてNULL が渡される可能性はない。 action が ARMS_PUSH_CLEAR_STATUS の場合、 buff はサーバから送られたリクエスト情報(テキストあるいはバイナリ) そのものとなる。 そのとき buff_len で示されるサイズ分のデータが文字列あるいはバイナリ形式で格納され、その直後にNUL 文字が格納される。

action が ARMS_PUSH_PING の場合、buff を arms_ping_arg_t * にキャストする必要がある。

action が ARMS_PUSH_TRACEROUTE の場合、buff を arms_traceroute_arg_t * にキャストする必要がある。

size_t buff_len

バッファ長。0 が渡されることもある。

ARMS_PUSH_CLEAR_STATUS 以外の場合、バッファ長には0 が渡される可能性はない。 buff に収められているデータのバイト数を表す。

char *result_buff

action ごとの処理結果情報を格納すべきlibarms 内のバッファ。 バッファとしてNULL が渡される可能性はない。

action が ARMS_PUSH_PING の場合、result_buff を arms_ping_report_t * にキャストする必要がある。

action が ARMS_PUSH_TRACEROUTE の場合、result_buff を arms_traceroute_info_t * にキャストする必要がある。

size_t result_len
バッファ長。 result_buff として確保されたバッファ領域のバイト数を表す。 バッファ長には0 が渡される可能性はない。
int *next

呼ばれたときには、ポインタが指す領域に下記の値が入っている。

ARMS_FRAG_FIRST
そのモジュールにおいて最初の呼び出し
ARMS_FRAG_CONTINUE
そのモジュールにおいて二度目以降の呼び出し

渡されたバッファ長がコールバックの実行結果を収めるには小さく、実行結果の分割取得を利用する場合、ブロックの情報(フラグ) を書き込む必要がある。

(ARMS_FRAG_FIRST | ARMS_FRAG_FINISHED)
最初のブロックで、続くブロックはない
(ARMS_FRAG_FIRST | ARMS_FRAG_CONTINUE)
最初のブロックで、続くブロックがある
ARMS_FRAG_CONTINUE
最初以外のブロックで、続くブロックがある
ARMS_FRAG_FINISHED
続くブロックはない。 action に ARMS_PUSH_MD_COMMAND 以外が指定された場合、NULL が渡される。 その場合分割取得は行わないため書き込み処理は不要である。
void *udata
arms_event_loop() で指定したポインタ

返り値

0
指定アクションの処理が正常に終了(result_buff は US-ASCII 文字列)
ARMS_RESULT_BYTES (バイト数)
ARMS_PUSH_MD_COMMAND あるいは ARMS_PUSH_DUMP_DEBUG が正常に終了。result_buff に格納したデータが US-ASCII 文字列でない場合に格納したバイト数を示す。
上記以外の非0
異常終了(エラーコード)
ARMS_EAPPEXEC
コマンドが存在しない、コマンドのパラメータエラーなど、アプリケーションレベルでのエラーが発生した
ARMS_ESYSTEM
メモリ不足など、動作環境が原因のエラーが発生した

ノート

バイト数を返すときに、result_len で指定されたバイト数よりも大きな値あるいはマイナスの値を指定した場合の動作は未定義。

ヒストリ

このAPIはVer2.10で追加された。

目次

前のトピックへ

(*arms_get_status_cb_t)()

次のトピックへ

(*arms_state_cb_t)()

リンク