三分九理
UltraSonix.source/RAP/docs/rap-spec.txt の日本語訳
許諾:本文書を含む Ultrasonix 7.0 の配布物では、非営利かつ教育目的の使用が認められているということで。
本文書を含むソースコードの取得元URL:
ftp://ftp.cc.gatech.edu/pub/multimedia/pub/UltraSonix.source-7.0.tar.Z
---------------------------------------------------------------------------
---------------------------------------------------------------------------

「REMOTE ACCESS PROTOCOL SPECIFICATION(日本語訳)」

原典記載の最終更新日:1995年4月21日

------------------------------------------------------------------------------
1.0 接続の待合せ(Connection Rendezvous)

 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] は、同プロパティが属するウィンドウである。

2.0 通則

 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 バイトは、現在使用していない。現実装では、大抵の返答メッセージは、往信メッセージの続き番号を記憶する追加領域を持たない。

3.0 RAP メッセージ

 以下に記すのは、各メッセージの形式の定義である。

3.1 RapError
	CARD16	replySequence
	CARD16	error code
	STRING	error string

 RapError は、異状を引き起こすリクエスト(要求)があった時に生成する。「error code」は、エラーの型を一意に特定する。「error string」で詳しい情報を提供する。未完成ではあるが、RAP エラーの一覧を挙げれば、以下の通り。

	RapNoError                        
    	RapNoSuchObject                  
    	RapNoSuchResource                  
    	RapNoSuchGraphicsContext          
    	RapCannotConvertType             
    	RapErrorAddNotify
3.2 RapAcknowledge
	CARD16	replySequence

 RapAcknowledge はリクエスト(要求)に対する肯定応答である。受領された(ACK'ed)メッセージの続き番号以外、何らデータを含まない。

3.3 RapHelloRequest

 RapHelloRequest は、クライアントの接続が始まった直後に、エージェントによって生成される。このメッセージは、エージェントとクライアントの間で応答確認情報(handshaking information)を遣り取りできるようにと考えて導入した。

 今のところ何もデータを運ばない。

3.4 RapHelloReply
	CARD32	window	 クライアントの最上位ウィンドウの ID

 RapHelloReply は、RapHelloRequest を受けて、クライアントが生成する。ゆくゆくは、このメッセージを使って、互礼情報(handshaking information)(リソースの型、使えるコールバック、未実装のメッセージ、等)をエージェントに返すつもりである。現在はクライアントのウィンドウ ID をエージェントに送り返すだけである。

3.5 RapQueryTreeRequest

 RapQueryTreeRequest はエージェントが生成する。同メッセージを用いて、クライアントに、同者の各シェル(shells)が持つウィジェット木全体の情報を送るように要求する。本メッセージは如何なる情報も運ばない。

3.6 RapQueryTreeReply
	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 で追加?)。

3.7 RapFullQueryTreeRequest

 RapFullQueryTreeRequest を用いて、全てのウィジェットと、各ウィジェットの全てのリソースと、各リソースの全ての値とを取得するべく、リクエスト(要求)を送出する。

3.8 RapFullQueryTreeReply
	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」は常にバイトの配列で返る。

3.9 RapGetResourcesRequest
	widgets				LIST OF WIDGETS

 RapGetResourcesRequest を用いて、ウィジェット識別子の配列をクライアントに渡す。それを受けて、クライアントは、配列中の各ウィジェットの名前、クラス、型、種別(kind)(normal または constraint)を返す。

3.10 RapGetResourcesReply
  	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 が使われている。)
3.11 RapGetGCValuesRequest
        GCc                         LIST OF GContextIDS

 RapGetGCValuesRequest を用いて、GContextId の配列をクライアントに渡す。それを受けて、クライアントは、配列で指定された各 GC の全 GCValues を返す。GContextID の配列が空のままエージェントから送信された場合、クライアントは自身の全ての GC の全ての値を返す。

3.12 RapGetGCValuesReply
        entries                         LIST OF entries
        each entry:
                gc                      GContext
                error code              CARD16
                [ error string          STRING ]
                [ values:               XGCValues ]

 RapGetGCValuesReply を用いて、GContextID の配列の全要素に応じた GCValues の配列を返す。GContextID の配列が空のままエージェントから送信された場合、クライアントは自身の全ての GC の全ての値を返す。

3.13 RapGetValuesRequest
  	widget				WIDGET
	resource names			LIST OF STRINGS

 RapGetValuesRequest を用いて、エージェントは指定したウィジェットからリソース値の配列を取得する。同情報は RapGetValuesReply を通じて戻って来る。

3.14 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」、実際に転送されて来る型、次いで実際のデータが詰まった可変長のバイト配列が格納される。

3.15 RapSetValuesRequest
  	name				STRING
	type				STRING
	value				STRING
	widgets				LIST OF WIDGETS

 RapSetValuesRequest を用いて、エージェントは一群のウィジェット中の特定リソースの値を変更できる。本メッセージが運ぶのは、リソースの名前と値(文字列で指定)と、リソースの設定が行われるウィジェットの配列とである。このメッセージの結果、RapSetValuesReply が生成される。「type」は、転送中の「value」が纏う型であり、現時点では XtRString である。

 このメッセージは、まだ実装してない。

3.16 RapSetValuesReply
  	name				STRING
	type				STRING
	value				STRING
	entries				LIST OF entries
	each entry:
		widget			WIDGET
		error code		CARD16
		error string		STRING

 RapSetValuesReply を通じて、RapSetValuesRequest メッセージを発したエージェントに、その成否を知らせる。本メッセージは、リソース名、型、値の情報と、ウィジェット、エラー・コード(おそらく RapErrorNone)、エラー文から成る項目(entry)の配列とを返す。

 このメッセージは、まだ実装してない。

3.17 RapAddNotifyRequest
	callback ids			CARD16 LIST OF CARD16

 このリクエスト(要求)によって、非同期的通知(asynchronous notifications:返答を要しない一方向の通知)のためのコールバック群がクライアントにインストールされる。個々のコールバックを表すトークン(符号)は実装次第となろう(HelloReply で使用可能なコールバックの一覧を届けさせる?)。配列中のコールバックの数は CARD16 で記す。現在、五つのコールバックは全て、RAP プロトコルの初期化の過程で自動的にインストールされる。

 クライアントは RapError または RapAck で応じる。

3.18 RapRemoveNotifyRequest
	callback ids			CARD16 LIST OF CARD16

 このリクエストによって、非同期的通知のためのコールバック群をクライアントから取り外す。個々のコールバックを表すトークン(符号)は実装次第となろう。クライアントは RapError または RapAck で応じる。

 このメッセージは、まだ実装してない。

3.19 RapObjectToWindowRequest
	widgets				LIST OF WIDGETS

 このメッセージは、まだ実装してない。

3.20 RapObjectToWindowReply
	entries				LIST OF entries
	each entry:
		widget			WIDGET
		error code		CARD16
		[ error string		STRING ]
		[ window		WINDOW ]

 このメッセージは、まだ実装してない。

3.21 RapWindowToObjectRequest
	windows				LIST OF WINDOW

 このメッセージは、まだ実装してない。

3.22 RapWindowToObjectReply
	entries				LIST OF entry
	each entry:
		window			WINDOW
		error code		CARD16
		error string		STRING
		widget			WIDGET

 このメッセージは、まだ実装してない。

3.23 RapLocateObjectRequest
	widgets				LIST OF WIDGET

 このメッセージは、まだ実装してない。

3.24 RapLocateObjectReply
	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 ]

 このメッセージは、まだ実装してない。

3.25 RapGetActionsRequest

 このメッセージは、まだ定義してない。

3.26 RapGetActionsReply

 このメッセージは、まだ定義してない。

3.27 RapDoActionRequest

 このメッセージは、まだ定義してない。

3.28 RapDoActionReply

 このメッセージは、まだ定義してない。

3.29 RapSelectEventRequest
	event ids			CARD16 LIST OF CARD16

 このリクエストによって、エージェントに通知して欲しいイベント群を登録する。エージェント側が関心を持つイベントの数は、CARD16 で指定する。実際の X イベントの型がクライアントに渡る。

3.30 RapSelectRequestRequest
	request ids			CARD16 LIST OF CARD16

 この要求によって、エージェントに通知して欲しいリクエスト(要求)の一群を登録する。エージェント側が関心を持つリクエスト(要求)の数は、CARD16 で指定する。実際の X リクエストの型がクライアントに渡る。

3.31 RapCloseConnectionRequest

 このメッセージは、まだ定義してない。

3.32 RapCreateNotify
	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 を見よ)。

3.33 RapConfigNotify
        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)が行われたウィジェットに関する情報である。

3.34 RapDestroyNotify
	callback type			STRING
	widget				WIDGET

 これは一方的に(asynchronous)エージェントへ送信されるメッセージであり、 同者に destroyHook・コールバックが呼び出されたことを通知する。メッセージの中身には、同コールバックの型と破壊されたウィジェットが入る。

3.35 RapGeometryNotify
	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)が行われたウィジェットに関する情報である。

3.36 Rap ChangeNotify
	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)が行われたウィジェットに関する情報である。

3.37 RapRequestNotify
	request				XREQ

 これは一方的に(asynchronous)エージェントへ送信されるメッセージであり、 同エージェント側が関心を持っている旨を登録していたリクエスト(要求)について通知を行う。メッセージの中身には、wire format(通信形式)の xReq 要求構造体が丸ごと入る。

3.38 RapEventNotify
	event				XEVENT

 これは一方的に(asynchronous)エージェントへ送信されるメッセージであり、 同エージェント側が関心を持っている旨を登録していたイベントについて通知を行う。メッセージの中身には、wire format(通信形式)の xEvent イベント構造体が丸ごと入る。

4.0 未解決の課題

 たくさん、しかしまだ執筆されてない。

-----------------------------------------
-----------------------------------------
三分九理