Inter-Client Exchange Library(日本語訳)

  アプリケーションは、(select を通じて) ICE 接続上に未読のデータがあることを知った時、関数 IceProcessMessages を呼び出す。メッセージの処理 を参照。IceProcessMessages において 0 でない主命令コードの付いた ICE メッセージ・ヘッダを読み取った時( 0 は ICE プロトコルが使用する)、同関数は、メッセージの残りの部分を読み込み、開封し、場合によっては、処理するための関数を呼び出さなければならない。

  ProtocolSetup を提起したクライアントの下にメッセージが届いた場合、コールバック IcePoProcessMsgProc を呼び出す。

  ProtocolSetup を受理したクライアントの下にメッセージが届いた場合、コールバック IcePaProcessMsgProc を呼び出す。

  メッセージを読み込むためのマクロが定義されているので、上記の両コールバックはこれを利用する(「ICE メッセージを読む」を参照)。バイト順の交換が必要になることもあり得るという点に注意する。ICE ヘッダの length フィールドのバイト順交換は、必要があれば ICElib にて行われる。

  両コールバックにおいて、引数 client_data には ProtocolSetup の際に登録したクライアント・データへのポインタが格納されている。IcePoProcessMsgProc の場合、クライアント・データは IceProtocolSetup 呼出しの中で設定される(訳註：SMlib では SmcConn がクライアント・データとして渡される)。IcePaProcessMsgProc の場合、クライアント・データはコールバック IceProtocolSetupProc の中で設定される(訳註：SMlib では SmsConn がクライアント・データとして渡される)。

  コールバック IcePoProcessMsgProc では、引数 reply_wait を確認する必要がある。もし replay_wait が NULL であれば、ICE ライブラリは次のように判断する。即ち、この関数はコールバックを通じてクライアントにメッセージを届けるものと見做される。例えば、ここでのメッセージ がセッション管理における「Save Yourself」メッセージであるとすると、当関数はコールバック経由でクライアントに「Save Yourself」を通知するということである。このようなコールバックが実際にどのように定義されるかは、実装次第である。

  一方、reply_wait が NULL でない場合、クライアントは先に自身が送信したメッセージに対する返信もしくはエラー報告を待ち受けているものと見做される。reply_wait は IceReplyWaitInfo 型である。

  IceReplyWaitInfo 構造体にはメッセージの主/従命令コードと通し番号が入っているが、これは、現在待ち受けている返信が為される所以となったメッセージのものである。同構造体には、返信メッセージが書き込まれる領域へのポインタも含まれている(プロトコル・ライブラリにおいて、この IcePointer を返信用の適当な型に読み替える)。大抵、返信メッセージには固定長の部分が存在し、そして、この固定長データ部分を内部に保持する構造体へのポインタは、返信を待っているクライアントが用意する。可変長のデータがある場合、コールバック IcePoProcessMsgProc において追加の記憶領域が確保され、その領域へのポインタが先の固定長構造体の中に格納される。もしデータが丸ごと可変長であれば(例えば可変長文字列一 つ)、返信を待ち受ける方のクライアントは、ポインタ一つを保持できる固定長領域へのポインタを渡すだけで良い。そして、コールバック IcePoProcessMsgProc が記憶領域を新たに確保し、その領域へのポインタを(渡されたポインタの指し示す固定長領域に)書き込む。返信を受け取ったクライアントは、自身のために割り当てられた記憶領域の解放作業を引き受けるものとする。

  reply_wait が NULL ではなく、且つ IcePoProcessMsgProc において同 reply_wait に対する返信もしくはエラー報告がある場合(つまりコールバックが生成されなかった場合)、引数 reply_ready_ret を True に設定する。エラーを返すのは、待ち受けられている返信にそのエラーが直接関連している時だけである、という点に注意する。それ以外の時は、IcePoProcessMsgProc は内部でエラーを処理するか、実装ライブラリのエラー・ハンドラ(処理器)を呼び出す。

  reply_wait が NULL の場合は reply_ready_ret も NULL であろうから、このポインタに如何なる値も書き込まないよう気をつけなければならない。

  一方、コールバック IcePaProcessMsgProc では、クライアントへメッセージを渡すにあたって、常にコールバックを利用する。例えば、ここでのメッセージがセッション管理における「Interact Request」メッセージであるとすると、この関数ではコールバック経由でクライアントに「Interact Request」を通知することになる。

  コールバック IcePaProcessMsgProc が IcePoProcessMsgProc のように reply_wait を利用しないのは次の理由による。即ち、サーバとして振舞うプロセスは、返信を待って他の入力を弾くわけにはいかないからである(接続を試みる方のクライ アントが異常な動作をした結果、際限なくメッセージをブロックする(返信が来るまで関数から戻らない)ようになると、他のクライアントとは通信できなく なってしまう)。

  先に述べたように、プロトコル・ライブラリは、自身が対応している認証方式を ICE ライブラリに登録しなければならない。各認証方式に対して、二つのコールバックを登録することができる。

  IcePoAuthProc は、ProtocolSetup を提起したクライアントのために呼び出されるコールバックである。このコールバックは、他のクライアントから送られてくる先頭メッセージ 「Authentication Required」もしくは後続メッセージ「Authentication Next Phase」に応えることができなければならない。

  認証方式によっては、作業の完遂に複数の段階を要することもある。その為、クライアントの認証作業中に IcePoAuthProc を複数回呼び出すことがあり得る。そして、その複数の呼出しの合間にも保持し続けなければならない状態情報があるであろう。各 ProtocolSetup の開始時点では *auth_state_ptr は NULL であり、この関数(IcePoAuthProc)を通じて状態の初期化と同ポインタの設定を行う。このポインタは、後続の本コールバックの呼出しにおい て、先行コールバックが記録した状態情報を取得するのに用いられる。

  必要であれば、関数 IceConnectionString を呼び出すことで、ProtocolSetup を受理するクライアントのネットワーク ID を取得することができる。

  free を用いて reply_data_ret と error_string_ret の両ポインタを解放するのは ICElib の仕事である。

  auth_data のポインタが揮発性の(volatile)記憶領域を指していることもあり得る。コールバックの呼出し完了以後もデータを保持する必要があれば、忘れずに複製を作っておく。

  IcePoAuthProc は、次の四つの値の何れか一つを返す。

  IcePaAuthProc は、ProtocolSetup を受信したクライアントのために呼び出されるコールバックである。

  認証方式によっては、作業の完遂に複数の段階を要することもある。その為、クライアントの認証作業中に IcePaAuthProc を複数回呼び出すことがあり得る。そして、その複数の呼出しの合間にも保持し続けなければならない状態情報があるであろう。各 ProtocolSetup の開始時点では、auth_datalen は 0、*auth_state_ptr は NULL であり、この関数(IcePaAuthProc)を通じて状態の初期化とポインタの設定を行う。このポインタは、後続の本コールバックの呼出しにおいて、 先行コールバックが記録した状態情報を取得するのに用いられる。

  必要であれば、関数 IceConnectionString を呼び出すことで、ProtocolSetup を受理するクライアントのネットワーク ID を取得することができる。

  auth_data のポインタが揮発性の(volatile)記憶領域を指していることもあり得る。コールバックの呼出し完了以後もデータを保持する必要があれば、忘れずに複製を作っておく。

  reply_data_ret と error_string_ret の両ポインタを伝送し、且つ free を用いて解放するのは、ICElib の仕事である。

  IcePaAuthProc は、次の四つの値の何れか一つを返す。

  ICE 接続を待ち受けている他のクライアントとの間に接続を開設するには、IceOpenConnection を用いる。

  IceOpenConnection は、成功すれば、不透明な(opaque) ICE 接続オブジェクトを返す。失敗すれば、NULL を返す。

  引数 network_ids_list には、コンマで区切ったネットワーク ID 群の並びを渡す。まず先頭のネットワーク ID を使って接続を試みる。これが失敗すれば、二番目のネットワーク ID を使って試行し、これが失敗すれば以下同様。各ネットワーク ID は次の書式をとる。

  大抵のプロトコル・ライブラリは、内部で IceOpenConnection を呼び出す、ある種の開設関数(open function)を備えることになるであろう。IceOpenConnection を呼び出した時、既設の ICE 接続の利用が認められることもある(接続相手のクライアントが同一の場合)。一方、ICE 接続の共用が望ましくないこともある。

  引数 context によって、ICE 接続の共用の可否を判断する。context が NULL であれば、当関数の呼出者は常に接続の共有を試みる。context が NULL でなければ、呼出方は、自身が指定したものとは異なる、NULL でない context と結びついた既設の ICE 接続を用いない。

  加えて、major_opcode_check に 0 でない主命令コードの値が渡された場合、既設の ICE 接続でその主命令コードが使用されていない時に限って、同接続を利用する。これを使えば、二つのクライアントの間で、同一プロトコルを用いた ICE 接続を複数設けるよう指示することも可能である。

  認証に必要な処理は ICE ライブラリの内部で行われる。認証データを取得する方法は実装によって異なる。^[1]

  IceOpenConnection の呼出しが終わると、クライアントは ProtocolSetup を送受信できるようになる(IceRegisterForProtocolSetup を呼び出している方は送信、IceRegisterForProtocolReply を呼び出している方は受信が可能)。

  ICE 接続を受け入れようとするクライアントは、接続要求を察知できるように、まず IceListenForConnections または IceListenForWellKnownConnections を呼び出さなければならない。これらの関数の結果、不透明な待受けオブジェクト(opaque "listen" objects)の配列が取得できる。利用可能な伝送方式(transport method)の種類一つにつき(例、Unix Domain、TCP、DECnet など)、一つのオブジェクトが割り当てられる。

  通常、クライアントは、各伝送方式中の利用可能な名前(訳註：ポート番号、オブジェクト名、経路名)の生成と、待受けオブジェクト群(listen objects)の取得を ICElib に依頼する。そうしたクライアントは次に、IceComposeNetworkIdList を用いて ICElib が定めた名前(訳註：ポート番号、オブジェクト名、経路名)を取り出し、接続開設を試みる他のクライアントから、それらの名前が利用できるようにする。時 には、予め決められた伝送オブジェクト名(transport object names)で接続を待ち受けなければならないこともあろう。そうしたクライアントは、IceListenForWellKnownConnections を用いて、待受けオブジェクト群(listen objects)の名前(訳註：ポート番号、オブジェクト名、経路名)を指定することができる。

  IceListenForConnections の戻り値は、失敗すれば 0、成功すれば正の値である。

  IceListenForWellKnownConnections は、既知の伝送方式(transport)の一つ一つを port_id の頭に付加する方法で、ネットワーク ID の一覧を構成し、その結果を用いて待受けオブジェクト群(listen objects)を作成する。port_id には、ICE ネットワーク ID 中のポート番号(portnumber)、オブジェクト名(objname)、もしくは経路(path)の部分が入る。あるネットワーク ID に対して待受けオブジェクト(listen object)が作成できなかった場合、そのネットワーク ID は無視する。一つも待受けオブジェクトが作成されなければ、IceListenForWellKnownConnections は失敗を意味する戻り値を返す。

  IceListenForWellKnownConnections の戻り値は、失敗すれば 0、成功すれば正の値である。

  待受けオブジェクトを閉鎖・解放するには、IceFreeListenObjs を用いる。

  待受けオブジェクト(listen object)に対する新たな接続を検出するには、その待受けオブジェクトに結び付けられている記述子に対して、select を使用する。

  記述子を取得するには、IceGetListenConnectionNumber を用いる。

  待受けオブジェクトに結び付けられたネットワーク ID の文字列表現を取得するには、IceGetListenConnectionString を用いる。

  ネットワーク ID は次の書式で記述される。

  ネットワーク ID 群をコンマで区切って並べた文字列(IceOpenConnection に渡せる形式)を作るには、IceComposeNetworkIdList を用いる。

  ICE 接続の開設を試みた時、認証に失敗し、且つ開始方クライアントが認証を要求していない場合、開始方クライアントに接続の最後の機会を与えるべく、ホスト名 に基づく認証手続き(host based authentication procedure)を呼び出すことができる。各待受けオブジェクトには、この種のコールバックが一つ備わっている。関数 IceSetHostBasedAuthProc を用いて、このコールバックの設定を行う。

  各待受けオブジェクトは、初期状態において、ホスト名に基づく認証手続きを何ら有していない。既にホスト名認証が 設定されている場合、引数 host_based_auth_proc に NULL を渡すことによって、同認証手続きを消去することができる。

  引数 host_name には「protocol/ hostname」の形をとる文字列を渡す。ここでの「protocol」には、{tcp、decnet、local} の何れか一つが入る。

  IceHostBasedAuthProc から True が返れば、たとえ元々の認証に失敗していても、接続は許可される。常に True を返す IceHostBasedAuthProc を登録することで、認証機能を実質的に無効にすることができる点に注意する。

  ホスト名に基づく認証は ProtocolSetup の段階でも使用可能である。この段階で使うコールバックは、関数 IceRegisterForProtocolReply で指定する(プロトコルの登録を見よ)。

  IceListenForConnections で取得した待受けオブジェクト(listen object)にて接続の試みを検知した後、IceAcceptConnection を呼び出す。この関数は、新しく不透明な ICE 接続オブジェクト返す。

  引数 status_ret は、次の値のどれか一つに設定される。

  一般に、新しい接続を検知するには、待受けオブジェクトに結び付けられたファイル記述子に対して select を実行する。新しい接続が見つかった時は、関数 IceAcceptConnection を呼び出す。IceAcceptConnection は、仮設状態の新 ICE 接続を返すことがある。これは、接続が有効になる前の段階で、認証を行うことがあるためである。ICE ライブラリは仮設状態の接続が有効になるまでの間、他の接続要求を弾くわけにはいかないので(接続を試みるクライアントが不適切な動きをすると、際限なく 接続要求をブロックしてしまう(接続が有効になるまで関数から返らない))、アプリケーション側で接続が有効な状態に変わるのを待たなければならない。

  次の擬似コードによって、接続を受理する過程を例示する。

new_ice_conn = IceAcceptConnection (listen_obj, &accept_status);
if (accept_status != IceAcceptSuccess)
{
     ファイル記述子を閉じて戻る
}

status = IceConnectionStatus (new_ice_conn);
time_start = time_now;

while (status == IceConnectPending)
{
     select() on {new_ice_conn, all open connections}

     for (each ice_conn in the list of open connections)
          if (data ready on ice_conn)
          {
               status = IceProcessMessages (ice_conn, NULL, NULL);
               if (status == IceProcessMessagesIOError)
                    IceCloseConnection(ice_conn);
          }
     if data ready on new_ice_conn
     {
          /*
          * IceProcessMessages は、接続が仮設でなくなる
          * まで呼び出される。これによって、接続設定要求
          * と認証手続きを処理する。
          */

          IceProcessMessages ( new_ice_conn, NULL, NULL);
          status = IceConnectionStatus (new_ice_conn);
     }
     else
     {
          if (time_now - time_start > MAX_WAIT_TIME)
               status = IceConnectRejected;
     }
}

if (status == IceConnectAccepted)
{
     Add new_ice_conn to the list of open connections
}
else
{
     IceCloseConnection
     new_ice_conn
}

  IceAcceptConnection が呼び出され、接続が有効になると、クライアントは ProtocolSetup を送受信できるようになる(IceRegisterForProtocolSetup を呼び出している方は送信、IceRegisterForProtocolReply を呼び出している方は受信が可能)。

  IceOpenConnection や IceAcceptConnection で作成された ICE 接続を閉じるには、IceCloseConnection を用いる。

  ある接続を実際に閉じるには、以下の条件が満たされなければならない、

  IceCloseConnection は、次の値の何れか一つを返す。

  ICE 接続の相手方クライアントが終了交渉(shutdown negotiation)を提起することなく接続を断ったことが分かった時は、関数 IceSetShutdownNegotiation を呼び出して、終了交渉を行わない設定に切り替える。これによって、IceCloseConnection が壊れた接続に対して書き込んでしまうことを防ぐ。

  ICE 接続の終了交渉に関する設定を調べるには、IceCheckShutdownNegotiation を用いる。

  IceCheckShutdownNegotiation が True を返すのは、引数で指定した接続において終了交渉が行われるよう設定されている時である。そうでない場合、False が返る。どの接続も、初期状態では交渉を行う設定になっている。この設定は、関数 IceSetShutdownNegotiation を使わなければ変更できない。

  看視手続き(watch procedure)を新たに登録するには、IceAddConnectionWatch を用いる。登録された看視手続きは、ICElib が IceOpenConnection や IceAcceptConnection によって新しい接続を開く度に、あるいは IceCloseConnection によって接続を閉じる度に、呼び出されることになる。

  IceAddConnectionWatch の戻り値は、失敗すれば 0、成功すれば正の値である。

  幾度かの IceOpenConnection の呼出しの結果、同一の ICE 接続が共用されることもあるという点に注意する。このような場合、看視手続きは、最初に接続が確立された時(認証成功後)にしか呼び出されない。同様に、接続が共有されている可能性があるので、IceCloseConnection を通じて実際に接続が切断された時に限り、看視手続きが呼び出される(IceConn の解放直前)。

  新しい接続が作成された時に select mask にファイル記述子を加え、接続が破棄された時にファイル記述子を取り除くアプリケーションにとって、この看視手続きはとても役に立つものである。接続が共 有されている可能性があるので、select mask に対して何時ファイル記述子を加えたり除いたりすべきなのかを、看視手続き無しに知るのは難しい。

  ICE ライブラリに複数の看視手続き(watch procedures)を登録できる。手続きが複数ある時の呼出し順序は、何ら想定すべきでない。

  看視手続き登録の時点において、ICE ライブラリに一つでも ICE 接続が作成されていれば、そうした ICE 接続の一つ一つに対して、直ちに同看視手続きが呼び出される。その際、引数 opening に True を渡す。

  看視手続きの関数型は IceWatchProc である。

  opening が True の時、クライアントは、接続終了まで保持する必要のあるデータを指すように、ポインタ *watch_data を設定する。看視手続きはその後、opening に False を渡して、再び呼び出される。

  看視手続きを削除するには、IceRemoveConnectionWatch を用いる。

     CARD8	major_opcode;
     CARD8	minor_opcode;
     CARD8	data[2];
     CARD32	length B32;

  ICE ライブラリは、メッセージの生成に用いる出力バッファ(output buffer)を保持している。ICE を基層とするプロトコルのライブラリでは、メッセージ群をまとめて一括処理することや、出力バッファを適宜放流する(flush)ことが可能である。

  ICE 接続において入出力エラーが発生した場合、以後の全ての書込み操作は無視される。更なる情報は、エラー処理を見よ。

  ICE 出力バッファの容量を知るには、IceGetOutBufSize を用いる。

  ICE 出力バッファを放流する(flush)には、IceFlush を用いる。

  出力バッファは、メッセージの生成に不十分な空き領域しかない場合、暗々裏に放流されることがあるので注意する。

  以下のマクロは ICE メッセージの生成に使用できる。

  IceGetHeader を用いて、引数で指定した ICE 接続におけるメッセージ・ヘッダを準備する。この準備作業では、メッセージ(*pmsg)の主・従命令コードを設定し、メッセージ長を表す(*pmsg の) length 欄をヘッダ長と同じ値に合わせる。この後ろに可変長のデータが続く場合は、メッセージの length 欄を更新するものとする。

  IceGetHeaderExtra を用いて、大きさの確定した(比較的小さな)可変長データを伴うメッセージを生成する。このメッセージの全身(complete message)は ICE 出力バッファに納まらなければならない。

  IceSimpleMessage を用いて、ICE ヘッダ・メッセージと同じ大きさの、且つそれ以上の後続データを持たないメッセージを生成する。

  IceErrorHeader によって、エラー・メッセージのヘッダを準備する。

  ICE で接続された二者のクライアントが、同一のプロトコルに対して相異なる主命令コードを用いている可能性のあることに注意する。上記マクロに渡す offending_major_opcode は、エラー・メッセージを送信した方のクライアントに割り当てられた主命令コードである。

  全てのプロトコルに共通の一般エラー(generic errors)には、0x8000~0xFFFF の範囲の値で表されるクラス(class)がある。詳細は規格文書 Inter-Client Exchange Protocol を見よ。

  プロトコル毎のエラーのクラスは、0x0000~0x7fff の範囲で表す。

  ICE 接続にデータを書き込むには、マクロ IceWriteData を用いる。データが ICE 出力バッファに収まる時は、そこにデータを転写する。そうでない時は、ICE 出力バッファを放流した上で、直接データを送信する。

  このマクロは IceGetHeader 及び IceErrorHeader と組み合わせて使用する。

  データを 16 ビット単位で書き込むには、IceWriteData16 を用いる。

  データを 32 ビット単位で書き込むには、IceWriteData32 を用いる。

  ICE 出力バッファへの転写作業を省くには、IceSendData を用い、ネットワーク接続を通じて直接データを送信する。この際、必要であれば、まず ICE 出力バッファが放流される。

  32 ビットもしくは 64 ビットの境界に揃えるには、IceWritePad を用いる。詰め物は最大で 7 バイトまで指定できる。

  ICE ライブラリは、メッセージの読み込みに用いる入力バッファを保持している。ICE ライブラリが、入力待機せずに適宜読み込みを行う様に実装された場合(nonblocking reads)、読み込み作業の度に 0 個以上のメッセージの全身(complete message)が入力バッファに読み込まれる。結果として、この節で説明する、メッセージ読み込みを行うマクロの全てについて、次のことが言える。即 ち、引数で指定された接続において実際の読み込み作業が行われるのは、入力バッファ中にデータが既に存在しない時に限られる。

  ICE 入力バッファの容量を知るには、IceGetInBufSize を用いる。

  メッセージを読み込む時は、入出力エラーの有無を確認するよう気をつけなければならない。読込みの際に、メッセー ジ中の何処かで何らかの入出力エラーが発生した場合、そのメッセージは捨てるものとする。以下で説明するマクロの何れかを用いてメッセージを読み込んだ後 には、マクロ IceValidIO を用いて、接続上で入出力エラーが発生したか否かを調べることができる。ある ICE 接続において入出力エラーが発生してしまった後は、全ての読み込み操作は無視される。更なる情報は、エラーの処理を見よ。

  以下のマクロを用いて ICE メッセージを読み込むことができる。

  IceReadSimpleMessage を用いて、次のようなメッセージを処理する。即ち、大きさが ICE ヘッダと同じ 8 バイトであり、且つヘッダ中の予備の 2 バイトを使って付加データを保持しているメッセージを処理する。ICE ライブラリは、メッセージの主命令コードを得るために、常にこの最初の 8 バイトを読み込む、という点に注意する。IceReadSimpleMessage は、単にこの 8 バイトへのポインタを返すだけであり、実際には如何なるデータも入力バッファに読み込まない。

  可変長データを伴うメッセージの読込みには、二通りのやり方がある。一つは、IceReadCompleteMessage を用いて、メッセージの全身を一度に読み込む方法である。もう一つは、先にメッセージ・ヘッダを読み込み(ICE ヘッダの 8 バイトより大きいこともある)、次いで可変長データ部分を適度に区切って読み込む方法である。後者については、IceReadMessageHeader と IceReadData を見よ。

  ICE 入力バッファに十分な空きがあれば、IceReadCompleteMessage はメッセージの全身を ICE 入力バッファに読み込む。空きがなければ、可変長データ部分を容れるバッファを新たに確保する。このマクロの呼出しの後、引数 pdata を NULL と比べて、バッファを確保するのに十分なメモリが存在したことを確かめるものとする。

   IceReadCompleteMessage を呼び出してメッセージを処理した後には、IceDisposeCompleteMessage を呼び出すものとする。

  可変長データを容れるためにバッファを確保しなければならなかった場合(ICE 入力バッファに収まらなかったが故に)、そのバッファはこのマクロを通じて、ICElib の手で解放される。

  IceReadMessageHeader は、メッセージのヘッダだけを読み込む。残りのデータは、IceReadData 系のマクロで読み込むことになる。このメッセージ読込みの手法は、可変長データ部分を適度に区切って読み込まなければならない時に採用する。

  利用者が用意したバッファに直接データを読み込むには、IceReadData を用いる。

  データを 16 ビット単位で読み込むには、IceReadData16 を用いる。(訳註：X11R7.7/lib/libICE-1.0.8 では未実装。引数 swap を無視して IceReadData と同じ作業を実行している。)

  データを 32 ビット単位で読み込むには、IceReadData32 を用いる。(訳註：X11R7.7/lib/libICE-1.0.8 では未実装。引数 swap を無視して IceReadData と同じ作業を実行している。)

  32 ビットもしくは 64 ビットの境界に揃えるには、IceReadPad を用いる。詰め物は最大で 7 バイトまで指定できる。