<hipc/usoc.h>Universal socket (USoc)とは、マイコン毎に異なる通信用APIをHIPCから統一的に扱うための仕組みである。 具体的には入出力関数hipcUsocRead()とhipcUsocWrite()の仕様について定めている。
Usocの関数仕様は簡略化されており、全ての処理が完了するか、そうでなければエラーを返す。 例えば、指示された16バイトのうち12バイトのみ処理されて残り4バイトは未処理という状況では、引き続き処理を続けて16バイト全てを処理して返るか、全バイトの処理を諦めて通信エラーを戻り値にして返るかのどちらかである。
enum HIPC_errno hipcUsocRead(hipc_usoc * so_p, void *buf, const size_t size)sizeが0のときは何もしない。sizeが0でないとき、bufからsizeバイト全ての読み込みを試みる。sizeバイト全てを読み込めたなら、HIPC_SUCCESSを返す。そうでければ、エラーを返す。
enum HIPC_errno hipcUsocWrite(const int fd, const void *buf, const size_t count)sizeが0のときは何もしない。sizeが0でないとき、bufからsizeバイト全ての書き込みを試みる。sizeバイト全てを書き込めたなら、HIPC_SUCCESSを返す。そうでければ、エラーを返す。
<hipc/usocutils.h>ユニバーサルソケットso_pへHIPCメッセージmd_pを書き込む。
enum HIPC_errno hipcUsocWriteMsgd(struct HIPC_usoc * const so_p,
hipc_msgd const *const md_p)ユニバーサルソケットso_pで、構成cfg_pのセッションを待ち受ける。 正常にセッションが受け付けられるとHIPC_SUCCESSが返される。 cfg_pとは異なる構成のセッション開始が要求されるなどの問題が発生した場合は、 内容に応じたエラーが返される。
enum HIPC_errno hipcUsocAcceptSimple(struct HIPC_usoc * const so_p,
const struct HIPC_scfg *const cfg_p)ユニバーサルソケットso_pで、セッションを待ち受ける。 長さn_cfgの構成の配列cfg_aryの中のどれか1つの構成が受け付けられると、 cfg_ppに受け付けた構成がセットされてHIPC_SUCCESSが返される。 受け付けに失敗した場合はエラーが返される。 この関数はHELLOメッセージ全体を一時的にバッファにに読み込むので、 cfg_aryの全ての構成のHELLOメッセージよりも大きいバッファを用意し、 bufにその先頭アドレスを、buf_sizeにそのサイズを指定する。
enum HIPC_errno hipcUsocAccept(struct HIPC_usoc * const so_p,
const struct HIPC_scfg * *const cfg_pp,
const struct HIPC_scfg *const *const cfg_ary,
const unsigned int n_cfg,
unsigned char *const buf, size_t buf_size)<hipc/msgd.h>メッセージデータmdRのヘッダの読み込み先はhipcMsgdHdrPtr(&mdR)でを得ることが出来る。 また、ヘッダ長は常にHIPC_MSGHDR_SIZEである。 よって、クライアントから送られてきたHIPCメッセージのヘッダを hipcUsocReadでso_pからmdRへ読み込むコードは以下の通りとなる。
hipcUsocRead(so_p, hipcMsgdHdrPtr(&mdR), HIPC_MSGHDR_SIZE);ヘッダを読み込んだメッセージデータから、メッセージの基本情報を得るには以下の関数を使う。 それぞれ、タイプ、構造体型番号、オフセット、レンジサイズを返す。
これらの関数はsizeof及びoffsetof演算子と共に利用することで、メンバ毎などの細かなアクセス制御に利用できる。
unsigned char hipcMsgdType(hipc_msgd const *const md_p)
unsigned char hipcMsgdStruno(hipc_msgd const *const md_p)
unsigned char hipcMsgdOffset(hipc_msgd const *const md_p)
unsigned char hipcMsgdRngsize(hipc_msgd const *const md_p)enum HIPC_errno hipcMsgdSetBdyForPut(hipc_msgd * const mdr_p,
void *const stru_p,
const size_t stru_size)hipcMsgdSetBdyForPut()はメッセージデータにPUTメッセージのボディ読み込み開始位置をセットする関数であり、 この位置はhipcMsgdBdyPtr()で得ることが出来る。 また、hipcMsgdBdySize()はボディのサイズを返す。 よって、mdRに既にPUTメッセージのヘッダが読み込まれているときに、 そのヘッダ情報を基に変数prmへメッセージボディの値を書き込むコードは以下のようになる。
hipcMsgdSetBdyForPut(&mdR, &prm, sizeof(prm));
hipcUsocRead(so_p, hipcMsgdBdyPtr(&mdR), hipcMsgdBdySize(&mdR));ここで、mdRのメッセージヘッダの構造体型番号と変数prmの型は対応が取れている必要がある。 通常の使い方なら、メッセージヘッダの構造体型番号がstruct foo型に振られているなら、prmはstruct foo型の変数である。
hipcMsgdSetBdyForPut()の第3引数sizeof(prm)は続くhipcUsocRead()で発生するprmへの書き込みがprmのメモリ範囲に収まっていることを確認するためにある。 与えられた変数のメモリ範囲を超えた書き込みになる場合には、hipcMsgdSetBdyForPut()はエラーを返すので、戻り値は必ずチェックすべきである。
enum HIPC_errno hipcGenmdSuccess(hipc_msgd * const md_p)md_pが指し示すメッセージデータを、データ無しのSUCCESSメッセージにする。 このメッセージはPUTメッセージに対する成功の返答に利用できる。
enum HIPC_errno hipcGenmdSuccessToGet(hipc_msgd * const mds_p,
hipc_msgd const *const mdr_p,
void *const stru_p,
const size_t stru_size)hipcGenmdSuccessToGet()はGETメッセージへの返答となるデータ付きのSUCCESSメッセージを作成するする関数である。 mdRが変数prmへのGETメッセージだったとして、これを基に返答メッセージmdSを作成するコードは以下のようになる。
hipcGenmdSuccessToGet(&mdS, &mdR, &prm, sizeof(prm));通常の使い方なら、prmの型はGETメッセージmdRが含む構造体型番号が振られている構造体型のはずである。
また、この関数は第3引数のsizeof(prm)を使って、実際にmdSをソケットに書き込む際にprmの範囲を超えたメモリアクセスが起きないかチェックし、起きる場合にはエラーを返す。 不適切なメモリアクセスは、プログラムの暴走や情報の漏洩につながる可能性があるので、戻り値は必ずチェックすべきである。
enum HIPC_errno hipcGenmdQuit(hipc_msgd * const md_p,
const enum HIPC_errno hipc_errno,
char *const errdtlstr)md_pが指し示すメッセージデータを、hipc_errnoのエラー番号とerrdtlstrのエラー詳細文字列を持つQUITメッセージにする。
Last modified: 2015/07/27 08:00:59 +09:00