=============================
(\*arms_read_config_cb_t)()
=============================

関数
----

.. c:function:: 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 に知らせることで複数回呼ばれることがある。

引数
----

:c:type:`uint32_t` :c:data:`id`
  モジュールID。ID 自体はSA の機種ごとに定義される。

  モジュールIDの指定はRS が行う。
  種別の異なる複数のコンフィグをRS から受信することもある。
  この場合、コンフィグの数だけコールバックが行われる。
:c:type:`int` :c:data:`type`
  コンフィグ領域。RS から指示された領域のコンフィグを result_buff に格納する。領域の指定は以下のいずれかとなる。
    :c:macro:`ARMS_CONFIG_CANDIDATE`
      反映待ちのコンフィグ
    :c:macro:`ARMS_CONFIG_RUNNING`
      SA の動作に実際に反映されているコンフィグ
    :c:macro:`ARMS_CONFIG_BACKUP`
      ARMS_CONFIG_RUNNING を反映させる前のコンフィグ
:c:type:`char` :c:data:`*result_buff`
  コンフィグを格納すべきlibarms 内のバッファ。バッファとしてNULL が渡される可能性はない。
:c:type:`size_t` :c:data:`result_len`
  result_buff で用意され書き込み可能な領域のバイト数。バッファ長には0 が渡される可能性はない。
:c:type:`int` :c:data:`*next`
  呼ばれたときには、ポインタが指す領域に下記の値が入っている。

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

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

    :c:macro:`(ARMS_FRAG_FIRST | ARMS_FRAG_FINISHED)`
      最初のブロックで、続くブロックはない
    :c:macro:`(ARMS_FRAG_FIRST | ARMS_FRAG_CONTINUE)`
      最初のブロックで、続くブロックがある
    :c:macro:`ARMS_FRAG_CONTINUE`
      最初以外のブロックで、続くブロックがある
    :c:macro:`ARMS_FRAG_FINISHED`
       続くブロックはない

:c:type:`void` :c:data:`*udata`
  :c:func:`arms_event_loop` で指定したポインタ

返り値
------

:c:macro:`0`
  コンフィグの取得が正常に終了(US-ASCII 文字列)
:c:macro:`ARMS_RESULT_BYTES` (バイト数)
  コンフィグの取得が正常に終了(格納データの有効なバイト数)
上記以外の値
  コンフィグ取得失敗

.. note::
  * 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で追加された。
