(*arms_read_config_cb_t)()

関数

typedef int (*arms_read_config_cb_t)(uint32_t id, int type, char *result_buff, size_t result_len, int *next, void *udata)

呼び出し方向

libarms->アプリケーション

目的

SA が実際に動作に使用しているコンフィグ情報を取得する。 コールバックテーブルへの登録は必須ではない。

説明

指定されたモジュールID のコンフィグ情報を取得する。バッファはlibarms が用意する。 バッファ長が渡されるので、それに収まる場合はそのままバッファに内容を書き出す。 バッファ長が実際のコンフィグ長に満たない場合、フラグを用いて続きがあることをlibarms に知らせることで複数回呼ばれることがある。

引数

uint32_t id

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

モジュールIDの指定はRS が行う。 種別の異なる複数のコンフィグをRS から受信することもある。 この場合、コンフィグの数だけコールバックが行われる。

int type

コンフィグ領域。RS から指示された領域のコンフィグを result_buff に格納する。領域の指定は以下のいずれかとなる。

ARMS_CONFIG_CANDIDATE

反映待ちのコンフィグ

ARMS_CONFIG_RUNNING

SA の動作に実際に反映されているコンフィグ

ARMS_CONFIG_BACKUP

ARMS_CONFIG_RUNNING を反映させる前のコンフィグ

char *result_buff

コンフィグを格納すべきlibarms 内のバッファ。バッファとしてNULL が渡される可能性はない。

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

続くブロックはない

void *udata

arms_event_loop() で指定したポインタ

返り値

0

コンフィグの取得が正常に終了(US-ASCII 文字列)

ARMS_RESULT_BYTES (バイト数)

コンフィグの取得が正常に終了(格納データの有効なバイト数)

上記以外の値

コンフィグ取得失敗

ノート

• 0 であれば、US-ASCII 文字列としてコンフィグをバッファに書き 込めたことを表す。文字列はNUL 文字で終端されているとみなす。
• 上位8 ビットの値が1 (最下位ビットのみ1 で他のビットは0) の場合、 下位24 ビットをコンフィグのバイト数として扱う。 これにより、バイナリコンフィグをサポートする。 簡易に表現できるよう ARMS_RESULT_BYTES() マクロを用意している。 64 ビット整数の場合は、上位40 ビットと下位24 ビットとなる。
• 上記2 つの条件に当てはまらない値はコンフィグ取得失敗とみなす。 これを受け取るとlibarms はRS にコンフィグ取得失敗を通知する。 明示的なマクロはなく、-1 を返すことで上位8 ビットの値が255(全 ビットの値が1) となるため、失敗を通知できる。 バイト数を返すときに、result_len で指定されたバイト数よりも大きな値 あるいはマイナスの値を指定した場合の動作は未定義。

ヒストリ

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