RAP は、ClientMessage イベントを使った通信から始まる。最初のメッセージはアプリケーションが受信する。同メッセージの形式は以下の通り。
message_type = Atom("ExternalAgent")
format = 32
data.l[0] = Atom("RAP")
data.l[1] = Atom("IceNetworkIds")
data.l[2] = エージェントのウィンドウ
この形式は Xtea の規格と互換性がある。data[0] は使いたいプロトコルの名前である。data[1] は、エージェントの ICE ネットワーク ID 群が格納されているプロパティの名前である。data[2] は、同プロパティが属するウィンドウである。
RAP はバイナリ・プロトコル(a binary protocol)であり、以下の通則に遵う。
CARD8 8-bit unsigned integer(符号無し整数) CARD16 16-bit unsigned integer(符号無し整数) CARD32 32-bit unsigned integer(符号無し整数) INT16 16-bit signed integer(符号付き整数) WINDOW 32-bit value WIDGET 32-bit value XREQ wire format の xReq 構造体 XEVENT wire format の xEvent 構造体 LIST OF FOO は、以下の形式の FOO の配列から成る。 number CARD32 FOO[0] ... FOO[number-1] CARD16 LIST OF FOO は、以下の形式の FOO の配列から成る。 number CARD16 FOO[0] ... FOO[number-1]
RAP では、メッセージの基本的な区分を三つ定めている。
REQUEST リクエスト(要求)は、エージェントからクライアントに向かい、必ずクライアントからのリプライ(返答)が続く。 REPLY リプライ(返答)は、リクエスト(要求)を受けて生成され、クライアントからエージェントに向かう。 NOTIFY 通知は、同期的返答を必要としない(asynchronous)メッセージである。 クライアントからエージェントに向かい、後者に前者の状態が変更されたことを通知する。
全てのメッセージには、下記のヘッダ情報が附いている。
CARD8 majorOpcode RAP 用に割り当てられた値 CARD8 minorOpcode メッセージの型を指定する CARD16 sequenceNumber メッセージの個体(instances)を識別する CARD32 length メッセージの全長
全てのリプライは、下記の情報も保持して良い。
CARD16 replySequence リプライ(返答)の切っ掛けとなった往信メッセージの続き番号
続き番号(sequence numbers)を使う動作は、現実装では存在しない。メッセージの順序付けの方法は未解決の課題である。メッセージ・ヘッダ中で続き番号用に空けられている 2 バイトは、現在使用していない。現実装では、大抵の返答メッセージは、往信メッセージの続き番号を記憶する追加領域を持たない。
以下に記すのは、各メッセージの形式の定義である。
CARD16 replySequence CARD16 error code STRING error string
RapError は、異状を引き起こすリクエスト(要求)があった時に生成する。「error code」は、エラーの型を一意に特定する。「error string」で詳しい情報を提供する。未完成ではあるが、RAP エラーの一覧を挙げれば、以下の通り。
RapNoError
RapNoSuchObject
RapNoSuchResource
RapNoSuchGraphicsContext
RapCannotConvertType
RapErrorAddNotify
CARD16 replySequence
RapAcknowledge はリクエスト(要求)に対する肯定応答である。受領された(ACK'ed)メッセージの続き番号以外、何らデータを含まない。
RapHelloRequest は、クライアントの接続が始まった直後に、エージェントによって生成される。このメッセージは、エージェントとクライアントの間で応答確認情報(handshaking information)を遣り取りできるようにと考えて導入した。
今のところ何もデータを運ばない。
CARD32 window クライアントの最上位ウィンドウの ID
RapHelloReply は、RapHelloRequest を受けて、クライアントが生成する。ゆくゆくは、このメッセージを使って、互礼情報(handshaking information)(リソースの型、使えるコールバック、未実装のメッセージ、等)をエージェントに返すつもりである。現在はクライアントのウィンドウ ID をエージェントに送り返すだけである。
RapQueryTreeRequest はエージェントが生成する。同メッセージを用いて、クライアントに、同者の各シェル(shells)が持つウィジェット木全体の情報を送るように要求する。本メッセージは如何なる情報も運ばない。
entries LIST OF entries each entry: widget entries LIST OF widget entries: each widget entry: widget WIDGET parent WIDGET name STRING class STRING window WIDGET managed CARD32 toolkit STRING
RapQueryTreeReply は、RapQueryTreeRequest メッセージを受けて生成される。本メッセージには、アプリケーション中の全ウィジェット木に関する情報が入る。返って来るウィジェット群が親子の順になっていることも、本プロトコルの要件である(エージェントの実装を簡単にするため)。
「widget」によって、クライアント中のこのオブジェクトを一意に表す。「parent」はウィジェットの一つ上の先祖である(この値はオブジェクトが親を持たなければ 0 となる)。「class」と「name」には、同オブジェクトを表す Xrm 形式の文字列が入る。「window」には、ウィジェットが使用しているウィンドウの XID が入る。ウィジェットが未だ具現化されていなければ(unrealized)、0 が返る。ウィジェットがガジェット(ウィンドウを用いないオブジェクト)の場合、2 が返る。これは Editres プロトコルと一致することに注意せよ。
「toolkit」は文字列であり、ウィジェット・セットもしくはウィジェットの属するツールキットを表す(R6 の Editres で追加?)。
RapFullQueryTreeRequest を用いて、全てのウィジェットと、各ウィジェットの全てのリソースと、各リソースの全ての値とを取得するべく、リクエスト(要求)を送出する。
entries LIST OF entries
each entry:
widget entries LIST OF widget entries:
each widget entry:
widget WIDGET
resources: LIST OF resources
each resource:
name STRING
class STRING
kind [normal=0 | constraint=1]
native type STRING
return type STRING
value data LIST OF CARD8
parent WIDGET
name STRING
class STRING
window WINDOW
managed CARD32
toolkit STRING
RapFullQueryTreeReply は RapFullQueryTreeRequest に対する返答である。本メッセージは基本的に RapQueryTreeReply と RapGetResourcesReply と RapGetValuesReply を連繋したものである。ウィジェット木中の各ウィジェット毎に、当該ウィジェットの全てのリソースを返し、同様に各リソースの全ての値も返す。
「native type」は、リソースの表現型をクライアントに記憶されているままの姿で表したものである。「return type」は、エージェントに実際に返って来るリソースの表現の型である。「value data」は常にバイトの配列で返る。
widgets LIST OF WIDGETS
RapGetResourcesRequest を用いて、ウィジェット識別子の配列をクライアントに渡す。それを受けて、クライアントは、配列中の各ウィジェットの名前、クラス、型、種別(kind)(normal または constraint)を返す。
entries LIST OF entries each entry: widget WIDGET error code CARD16 [ error string STRING ] [ resources: LIST OF resources each resource: name STRING class STRING kind CARD32 type STRING ]
RapGetResourcesReply を用いて、ウィジェットの配列の中の全てのリソースの配列を返す。要求を受けた各ウィジェット毎に、GetResourcesReply はウィジェット識別子とエラー・コードを返す。エラー・コードは、当該ウィジェットでエラーが起きたか否かを表す(エラーが起きなければ RapErrorNone)。
エラーの有無に従って、エラー文字列または取得したウィジェットのリソース数が返る。エラーが無ければ、リソースの配列が後ろに続く。リソース配列の各要素には、当該リソースの名前、クラス、種別(kind)、型が含まれる。
(訳註：UltraSonix.source/RAP/agent-in.c 等を見ると RapErrorNone ではなく RapNoError が使われている。)GCc LIST OF GContextIDS
RapGetGCValuesRequest を用いて、GContextId の配列をクライアントに渡す。それを受けて、クライアントは、配列で指定された各 GC の全 GCValues を返す。GContextID の配列が空のままエージェントから送信された場合、クライアントは自身の全ての GC の全ての値を返す。
entries LIST OF entries
each entry:
gc GContext
error code CARD16
[ error string STRING ]
[ values: XGCValues ]
RapGetGCValuesReply を用いて、GContextID の配列の全要素に応じた GCValues の配列を返す。GContextID の配列が空のままエージェントから送信された場合、クライアントは自身の全ての GC の全ての値を返す。
widget WIDGET resource names LIST OF STRINGS
RapGetValuesRequest を用いて、エージェントは指定したウィジェットからリソース値の配列を取得する。同情報は RapGetValuesReply を通じて戻って来る。
widget WIDGET values LIST OF values each value: name STRING error code CARD16 [ error string STRING ] [ native type STRING return type STRING value data LIST OF CARD8 ]
RapGetValuesReply は、リクエスト(要求)を送ってきたエージェントに対して、リソース値の配列を送り返す。この呼出しには、取得しようとしている「values」が属しているウィジェットと、戻って来る値の個数とが含まれている。
各「value」には、リソースの名前と、同リソースに対するリクエストが失敗したが否かを示すエラー・コードが入る。エラーが起きた場合、「value」にはエラー文が格納される。エラーが起きなければ、「value」には、リソース値の元の型「native type」、実際に転送されて来る型、次いで実際のデータが詰まった可変長のバイト配列が格納される。
name STRING type STRING value STRING widgets LIST OF WIDGETS
RapSetValuesRequest を用いて、エージェントは一群のウィジェット中の特定リソースの値を変更できる。本メッセージが運ぶのは、リソースの名前と値(文字列で指定)と、リソースの設定が行われるウィジェットの配列とである。このメッセージの結果、RapSetValuesReply が生成される。「type」は、転送中の「value」が纏う型であり、現時点では XtRString である。
このメッセージは、まだ実装してない。
name STRING type STRING value STRING entries LIST OF entries each entry: widget WIDGET error code CARD16 error string STRING
RapSetValuesReply を通じて、RapSetValuesRequest メッセージを発したエージェントに、その成否を知らせる。本メッセージは、リソース名、型、値の情報と、ウィジェット、エラー・コード(おそらく RapErrorNone)、エラー文から成る項目(entry)の配列とを返す。
このメッセージは、まだ実装してない。
callback ids CARD16 LIST OF CARD16
このリクエスト(要求)によって、非同期的通知(asynchronous notifications：返答を要しない一方向の通知)のためのコールバック群がクライアントにインストールされる。個々のコールバックを表すトークン(符号)は実装次第となろう(HelloReply で使用可能なコールバックの一覧を届けさせる?)。配列中のコールバックの数は CARD16 で記す。現在、五つのコールバックは全て、RAP プロトコルの初期化の過程で自動的にインストールされる。
クライアントは RapError または RapAck で応じる。
callback ids CARD16 LIST OF CARD16
このリクエストによって、非同期的通知のためのコールバック群をクライアントから取り外す。個々のコールバックを表すトークン(符号)は実装次第となろう。クライアントは RapError または RapAck で応じる。
このメッセージは、まだ実装してない。
widgets LIST OF WIDGETS
このメッセージは、まだ実装してない。
entries LIST OF entries each entry: widget WIDGET error code CARD16 [ error string STRING ] [ window WINDOW ]
このメッセージは、まだ実装してない。
windows LIST OF WINDOW
このメッセージは、まだ実装してない。
entries LIST OF entry each entry: window WINDOW error code CARD16 error string STRING widget WIDGET
このメッセージは、まだ実装してない。
widgets LIST OF WIDGET
このメッセージは、まだ実装してない。
entries LIST OF entry each entry: widget WIDGET error code CARD16 [ error string STRING ] [ window WINDOW managed CARD8 x INT16 y INT16 width CARD16 height CARD16 border width CARD16 ]
このメッセージは、まだ実装してない。
このメッセージは、まだ定義してない。
このメッセージは、まだ定義してない。
このメッセージは、まだ定義してない。
このメッセージは、まだ定義してない。
event ids CARD16 LIST OF CARD16
このリクエストによって、エージェントに通知して欲しいイベント群を登録する。エージェント側が関心を持つイベントの数は、CARD16 で指定する。実際の X イベントの型がクライアントに渡る。
request ids CARD16 LIST OF CARD16
この要求によって、エージェントに通知して欲しいリクエスト(要求)の一群を登録する。エージェント側が関心を持つリクエスト(要求)の数は、CARD16 で指定する。実際の X リクエストの型がクライアントに渡る。
このメッセージは、まだ定義してない。
callback type STRING
widget WIDGET
parent WIDGET
name STRING
class name STRING
window CARD32
toolkit STRING
resources: LIST OF resources
each resource:
name STRING
className STRING
type STRING
kind CARD32
native type STRING
return type STRING
value data LIST OF CARD8
これは一方的に(asynchronous)エージェントへ送信されるメッセージであり、 同者に createHook・コールバックが呼び出されたことを通知する。メッセージの中身は全て、生成時の呼出し(the create call)が行われたウィジェットに関する情報である(FullQueryTreeReply を見よ)。
callback type STRING
widget WIDGET
geometryMask CARD32
x pos CARD32
y pos CARD32
width CARD32
height CARD32
borderWidth CARD32
sibling CARD32
stackMode CARD32
これは一方的に(asynchronous)エージェントへ送信されるメッセージであり、 同者に configHook・コールバックが呼び出されたことを通知する。メッセージの中身は全て、位置形状の変更を実際の配置に反映する手続き(the configuration call)が行われたウィジェットに関する情報である。
callback type STRING widget WIDGET
これは一方的に(asynchronous)エージェントへ送信されるメッセージであり、 同者に destroyHook・コールバックが呼び出されたことを通知する。メッセージの中身には、同コールバックの型と破壊されたウィジェットが入る。
callback type STRING
widget STRING
for type == XtHpreGeometry:
request mode CARD32
x pos CARD32
y pos CARD32
width CARD32
height CARD32
borderWidth CARD32
sibling CARD32
stackMode CARD32
for all other types:
result CARD32
request mode CARD32
request x pos CARD32
request y pos CARD32
request width CARD32
request height CARD32
request borderWidth CARD32
request sibling CARD32
request stackMode CARD32
final request mode CARD32
final x pos CARD32
final y pos CARD32
final width CARD32
final height CARD32
final borderWidth CARD32
final sibling CARD32
final stackMode CARD32
これは一方的に(asynchronous)エージェントへ送信されるメッセージであり、 同者に geometryHook・コールバックが呼び出されたことを通知する。メッセージの中身は全て、位置形状の情報を変更する手続き(the geometry call)が行われたウィジェットに関する情報である。
callback type STRING
widget STRING
*** for type == XtHsetValues:
resources: LIST OF resources
each resource:
name STRING
type STRING
value STRING
*** for type == XtHmanageChildren, XtHunmanageChildren,
XtHunmanageSet, XtHmanageSet, XtHsetWMColormapWindows:
widgets: LIST OF widgets
each widget:
widget WIDGET
*** for type == XtHrealizeWidget:
window CARD32
*** for type == XtHaddCallback, XtHaddCallbacks,
XtHremoveCallback, XtHremoveCallbacks:
callback name STRING
*** for type == XtHsetKeyboardFocus:
descendant CARD32
*** for type == XtHsetMappedWhenManaged:
boolean CARD32
*** for type == XtHpopup:
grabKind CARD32
これは一方的に(asynchronous)エージェントへ送信されるメッセージであり、 同者に changeHook・コールバックが呼び出されたことを通知する。メッセージの中身は全て、変更の呼出し(the change call)が行われたウィジェットに関する情報である。
request XREQ
これは一方的に(asynchronous)エージェントへ送信されるメッセージであり、 同エージェント側が関心を持っている旨を登録していたリクエスト(要求)について通知を行う。メッセージの中身には、wire format(通信形式)の xReq 要求構造体が丸ごと入る。
event XEVENT
これは一方的に(asynchronous)エージェントへ送信されるメッセージであり、 同エージェント側が関心を持っている旨を登録していたイベントについて通知を行う。メッセージの中身には、wire format(通信形式)の xEvent イベント構造体が丸ごと入る。
たくさん、しかしまだ執筆されてない。