クライアントライブラリ

ここでは、HIPCクライアントプログラムを作成するためのライブラリを説明する。

クライアントライブラリを通してサーバーと通信を行うには、HIPCメッセージの送信関数と受信関数が必要となる。 POSIX環境では送信関数と受信関数の両方が標準で添付(hipc/posix/clientutils.h)されているので、これをそのまま利用できる。 POSIX以外の環境ではユーザーがこの2つの関数を作成する必要がある。通信用関数の詳細については、通信用コールバック関数の項目を参照のこと。

Doxygen

クライアントライブラリで用いられる型

enum HIPC_errno

HIPCライブラリの多くの関数は、戻り値として列挙型 enum HIPC_errno の値を返す。関数の処理の成功を表す値はHIPC_SUCCESSである。処理に失敗した場合は、その内容に応じた値が返される。詳細は別ページを参照のこと。

hipc_msg

hipc_msgはHIPCメッセージを表す型である。メッセージ1つ分のデータを持つ。クライアントライブラリを利用してセッション操作を行う場合、HIPCメッセージは基本的にライブラリ内で処理される。よって、セッション操作で直接この型の変数を扱うことは少ない。一方で、この型はライブラリがHIPCメッセージを送受信するために呼び出す通信用コールバック関数の引数の1つであるため、ユーザーがこれを作成するときには、hipc_msg型の変数を扱う必要がある。

HIPCセッション操作: <hipc/session.h>

以下の関数とマクロはHIPCセッションを操作するためのものである。 HIPCではクライアントはセッションを通してサーバーと通信を行う。

基本的な操作の流れは、hipc_session型の変数を宣言し、その変数のアドレスを引数にして、hipcOpen()でセッションを開き、hipcGet()とhipcPut()でデータを送受信し、hipcClose()でセッションを閉じるというのがである。hipcOpen()で開いたセッションは、原則hipcClose()で閉じなければならない。ただし、エラー発生時にクライアントプログラム全体を終了させる場合はこの限りではない。

エラーが発生した場合、これらの関数はエラーを返す。エラー情報はhipc_session型の変数内に保持されているため、関数の戻り値をチェックする以外にも、HIPC_ERRCHECKにこの変数のアドレスを渡してエラー発生時点でクライアントプログラムを終了させるという手段も利用できる。

hipcOpen

enum HIPC_errno
hipcOpen(hipc_session * const sess_p,
         struct HIPC_client const *const clbase_p,
         enum HIPC_errno (*rfnc_p) (void *, hipc_msg), void *rarg,
         enum HIPC_errno (*wfnc_p) (void *, const hipc_msg), void *warg)

clbase_pには通常hipcconfigが出力したソースコードに定義されたベースクライアントのアドレスを指定する。

rfnc_pとwfnc_pには、それぞれHIPCメッセージの受信関数と送信関数を指定する。rargとwargは、それぞれの関数が実際に呼び出されるときに第1引数として渡される値である。これらの引数の詳細は通信用コールバック関数の項目を参照のこと。

POSIX環境では、標準で添付されているhipcPosixReadMsgとhipcPosixWriteMsgをrfnc_pとwfnc_pにそれぞれ指定して利用できる。この場合rargとwargには、ファイルディスクリプタに相当するint型変数のアドレスを指定する。

hipcClose

enum HIPC_errno hipcClose(hipc_session * const sess_p)

hipcGet

enum HIPC_errno
hipcGet(hipc_session * const sess_p,
        char const *const str, void *const cimg)

サーバーから情報を得る。文字列strで指定した構造体もしくはそのメンバの値が、cimgに書き込まれる。文字列strの指定方法については識別文字列の書式を参照のこと。 cimgに指定するアドレスはstrの先頭で指定した構造体型の変数の先頭アドレスでなくてはならない。strでメンバを指定した場合も同様である。

hipcPut

enum HIPC_errno
hipcPut(hipc_session * const sess_p,
        char const *const str, void *const cimg)

サーバーへ情報を渡す。文字列strで指定した構造体もしくはそのメンバの値が、cimgに読み込まれる。文字列strの指定方法については識別文字列の書式を参照のこと。 cimgに指定するアドレスはstrの先頭で指定した構造体型の変数の先頭アドレスでなくてはならない。strでメンバを指定した場合も同様である。

hipcSetHandler

enum HIPC_errno
hipcSetHandler(hipc_session * const sess_p,
               char const *const str,
               void *const cimg,
               enum HIPC_errno (*hndlr_p) (struct HIPC_client *,
                                           const hipc_msg, void *, void *),
               void *const arg)

CASTメッセージを受信したときに呼び出す関数を構造体型毎に設定する。文字列strに構造体型名、hndlr_pにその構造体型のCASTメッセージを受信したときに呼び出す関数を指定する。

cimgは対応する構造体型の変数の先頭アドレスを設定する。このcimgには、受信したCASTメッセージのデータが展開される。また、このcimgはhndlr_pを呼び出すときの第3引数にもなる。 cimgにNULLを設定すると、データの展開は行われず、hndlr_pを呼び出すときの第3引数もNULLとなる。

argはhndlr_pへの第4引数である。argとして渡した値がそのまま第4引数としてhndlr_pに渡される。

HIPC_ERRCHECK

HIPC_ERRCHECK(sess_p)

エラーが起きていないかを確認する。エラーが起きていた場合は、エラー情報を表示した後、プログラムを終了させる。

識別文字列の書式

構造体やそのメンバを指定する文字列の書式は、変数名の位置に構造体型名を利用する以外はC言語とほぼ同じ書式を用いる。

通信用コールバック関数

クライアントライブラリのセッション操作(hipc/session.h)では、様々な通信路に対応するため、HIPCメッセージの送受信でコールバック関数を利用する。コールバック関数には、受信用(read function, rfnc)と送信用(write function, wfnc)の2つがある。これらの関数は、ライブラリ内でHIPCメッセージの送受信が必要になったときに呼び出される。

ある1回のセッションで使うコールバック関数の指定は、セッションを開くときのhipcOpen()の引数で行う。具体的には、hipcOpen()の第3引数にメッセージ受信用関数、第5引数に送信用関数を指定する。

ライブラリがコールバック関数を呼び出すときに第1引数として与える値は、hipcOpen()で指定する。通常の使い方では、この第1引数は通信路を利用するのに必要なデータへのポインタである。受信用関数の第1引数の値は、hipcOpen()の第4引数rargで指定する。送信用関数の第1引数の値は、hipcOpen()の第6引数wargで指定する。

以下は、受信用関数rfncと送信用関数wfncのプロトタイプ宣言である。

enum HIPC_errno rfnc(void *arg, hipc_msg msg)
enum HIPC_errno wfnc(void *arg, const hipc_msg msg)

先に述べたように、rfnc()、wfnc()共に、第1引数のargは通信路を利用するのに必要なデータへのポインタである。 argが何の型へのポインタなのかは通信路によって異なる。これは通信路やそのAPIの仕様を基にコールバック関数制作者が決めることになる。なお、送信用関数と受信用関数で、ポインタargが示す型は異なっても良いし、argが示すアドレスが異なっても良い。つまり、別の変数型でも、インスタンスとして別の変数でも良い。

第2引数msgはHIPCメッセージ1つ分のデータを持つ変数である。 rfnc()はmsgへ受信したメッセージを書き込む。 wfnc()はmsgを読んでメッセージを送信する。

戻り値の型はenum HIPC_errnoで、 HIPCメッセージの受信または送信に成功したときはHIPC_SUCCESSを、失敗したときはenum HIPC_errnoで列挙されている値の中からエラーに対応する適切な値を返す。具体的にどのエラーを返すかは、コールバック関数制作者が決めることになる。例えば、hipcPosixReadMsg()は、通信路からのデータの読み込みでエラーが発生した場合にHIPC_ERR_IO_READを返し、hipcPosixWriteMsg()は、通信路へのデータの書き込みでエラーが発生した場合にHIPC_ERR_IO_WRITEを返す。

HIPC_SUCCESSC以外を返すときは、通信用コールバック関数は標準ライブラリのerrnoを適切に設定する。エラーと関連する適切なerrnoの値があるときはその値を、そうでない場合は0をerrnoにセットする。この仕様があるのは、OSによっては通信用APIでエラーが発生したときにerrnoに値をセットするためである。通信用コールバック関数が適切に振る舞えば、このerrnoの値へアクセスできるようにHIPCのクライアントライブラリは作られている。

以上の仕様をコールバック関数を作るときの視点でまとめると以下のようになる。

クライアントユーティリティ: <hipc/posix/clientutils.h>

ファイルディスクリプタを通してHIPCメッセージを読み書きするための関数が宣言されている。 hipcOpen()の引数に指定して使用する。

hipcPosixReadMsg

enum HIPC_errno hipcPosixReadMsg(void *arg, hipc_msg msg)

ファイルディスクリプタからmsgへHIPCメッセージを1つ読み込む。 argにはファイルディスクリプタに相当するint型変数のアドレスを指定する。

hipcPosixWriteMsg

enum HIPC_errno hipcPosixWriteMsg(void *arg, const hipc_msg msg)

ファイルディスクリプタへ1つのHIPCメッセージmsgを書き込む。 argにはファイルディスクリプタに相当するint型変数のアドレスを指定する。

クライアントライブラリ

Doxygen