ToolTalk メッセージを送信するためのアプリケーションの変更

アプリケーションは、ToolTalk メッセージを送信するために、いくつかの操作を実行しなければなりません。つまり、ToolTalk メッセージの作成と完了、メッセージコールバックルーチンの追加、および完了したメッセージの送信などの操作が必要です。

メッセージの作成

ToolTalk サービスは、メッセージを作成し完了するために次の 3 通りの方法を用意しています。

1. 汎用関数

   • tt_message_create ( )

2. プロセス指向の通知関数と要求関数

   • tt_pnotice_create ( )

   • tt_prequest_create ( )

3. オブジェクト指向の通知関数と要求関数

   • tt_onotice_create ( )

   • tt_orequest_create ( )

プロセス指向およびオブジェクト指向の通知関数と要求関数を使用すると、一般的なメッセージが簡単に作成できます。これらの関数は、機能的には他の tt_message_create ( ) および tt_message_attribute_set ( ) 呼び出しの文字列と同じですが、より簡単に書き込みと読み取りができます。表 8-4 と表 8-5 は、メッセージの作成および完成用に使用する ToolTalk 関数を示しています。

すべての作成用関数が返す型は Tt_message です。

メッセージの完成用に使用するすべての関数が返す型は Tt_status です。

汎用関数を使った ToolTalk メッセージの作成

汎用関数 tt_message_create ( ) を使用して、ToolTalk メッセージを作成し完成できます。tt_message_create ( ) を使用してプロセス指向またはオブジェクト指向のメッセージを作成する場合は、tt_message_attribute_set ( ) 呼び出しを使用して属性を設定します。

クラス

• 値または状態を返すメッセージ用には、TT_REQUEST を使用します。メッセージが処理された場合、メッセージが待ち行列に入れられた場合、または要求を処理するプロセスを起動した場合には通知されます。

• イベントの他のプロセスに通知するだけのメッセージ用には、TT_NOTICE を使用します。

• メッセージの受信者としていくつかのタイプを予想して、それらの中の受信者、拒絶者、忌避者の割合を知りたい場合は、TT_OFFER を使用します。

アドレス

• TT_PROCEDURE を使用して、これらの引数を使用してこの操作を実行できるすべてのプロセスにメッセージを送信します。このメッセージの操作属性と引数属性を書き込みます。

• TT_OTYPE を使用して、これらの引数を使用してこの操作を実行できるオブジェクト型にメッセージを送信します。このメッセージの otype 属性、操作属性、および引数属性を書き込みます。

• TT_HANDLER を使用して、特定のプロセスにメッセージを送信します。ハンドラ属性の値を指定します。

  通常、1 つのプロセスは一般的な要求を作成し、応答からハンドラ属性を選択し、そのハンドラに追加のメッセージを送信します。ハンドラの正確な procid を指定した場合、ToolTalk サービスはメッセージを直接配信します。この場合、パターン照合は行われず、他のアプリケーションがメッセージを監視できません。このポイントツーポイント (PTP) のメッセージ渡し機能によって、2 つのプロセスがブロードキャストメッセージを渡すことによって認識し合い、明示的な通信を実行できます。

オファは、TT_PROCEDURE アドレスでのみ送信可能です。それ以外のアドレスで送信しようとすると、TT_ERR_ADDRESS エラーとなります。

• TT_OBJECT を使用して、これらの引数を使用して操作を実行する特定のオブジェクトにメッセージを送信します。このメッセージのオブジェクト属性、操作属性、および引数属性を書き込みます。

配信範囲

メッセージ配信の配信範囲を書き込みます。受信可能側は、次の値に結合できます。

• TT_SESSION

• TT_FILE

• TT_BOTH

• TT_FILE_IN_SESSION

ToolTalk サービスは、配信範囲に応じてデフォルトのセッションまたはファイル、あるいはその両方をメッセージに追加します。

オファは、TT_SESSION の配信範囲でのみ送信可能です。

操作

作成中の通知または要求について記述した操作を書き込みます。操作名を判定するには、ターゲットとなる受信側の ptype 定義またはメッセージプロトコル定義を参照します。

引数

操作に固有の引数を書き込みます。引数のデータ型に最も適した関数を使用します。

• tt_message_arg_add ( )

  値がゼロ終了文字列の引数を追加します。

• tt_message_barg_add ( )

  値がバイト文字列の引数を追加します。

• tt_message_iarg_add ( )

  値が整数の引数を追加します。

追加する引数ごとに、次の値を指定します (値の型には関係ありません)。

• Tt_mode

  TT_IN または TT_INOUT を指定します。TT_IN は、送信側が引数を書き込み、ハンドラおよびオブザーバがこの引数を読み取れることを示します。TT_INOUT は、送信側とハンドラが引数を書き込み、誰でも引数を読み取れることを示します。応答としてハンドラからの引数を必要とする要求を送信する場合は、TT_INOUT を使用します。

• 値の型

  値の型 (vtype) は、追加する引数のデータ型について説明します。ToolTalk サービスは、登録済みのパターンとメッセージを比較してメッセージの受信側を判定する際に vtype 名を使用します。しかし、メッセージまたはパターンの引数の値を処理する際には vtype を使用しません。

  vtype 名は、メッセージの受信側がデータを解釈するのに役立ちます。たとえば、ワードプロセッサがメモリ内のパラグラフを PostScript 表現に変換した場合は、tt_message_arg_add に次の引数を付けて呼び出すことができます。

     tt_message_arg_add (m, "PostScript", buf); 

  この場合 ToolTalk サービスは、ゼロ終了文字列を指す buf を想定し送信します。

  同様に、アプリケーションは、ToolTalk メッセージで enum 値 (たとえば、次のような Tt_status の要素) を送信します。

     tt_message_iarg_add(m, "Tt_status", (int) TT_OK); 

  ToolTalk サービスは、値を整数として送信します。ただし、Tt_status という vtype は、値が何を意味するかを受信側に示します。

特に送信側と受信側で特定の vtype 名を定義し、受信側が他の形式で格納された値を検索できないようにしなければなりません。たとえば、整数として格納した値が、文字列として検索されないようにしなければなりません。

プロセス指向メッセージの作成

プロセス指向の通知と要求は、簡単に作成できます。手続き型の通知または要求について、新しいメッセージオブジェクトのハンドルまたは隠されたポインタを取得するには、tt_pnotice_create 関数または tt_prequest_create 関数を使用します。このハンドルは、以降の呼び出しでメッセージを参照するために使用できます。

tt_pnotice_create または tt_prequest_create を使用してメッセージを作成する場合は、引数として次の 2 つの属性を指定しなければなりません。

• 配信範囲

  メッセージ配信の配信範囲を書き込みます。受信可能側は、次の値に結合できます。

  • TT_SESSION

  • TT_FILE

  • TT_BOTH

  • TT_FILE_IN_SESSION

  ToolTalk サービスは配信範囲に応じて、デフォルトのセッションまたはファイル (あるいはその両方) を書き込みます。

• 操作

  作成中の通知または要求について記述した操作を書き込みます。操作名を判定するには、ターゲットプロセスの ptype 定義またはその他のプロトコル定義を参照します。

操作引数などの他のメッセージ属性を完成するには、tt_message_attribute_set ( ) 呼び出しを使用します。

オブジェクト指向メッセージの作成および完成

オブジェクト指向の通知と要求は、簡単に作成できます。オブジェクト指向の通知または要求について、新しいメッセージオブジェクトのハンドルまたは隠されたポインタを取得するには、tt_onotice_create 関数または tt_orequest_create 関数を使用します。このハンドルは、以降の呼び出しでメッセージを参照するために使用できます。

tt_onotice_create または tt_orequest_create を使用してメッセージを作成する場合は、引数として次の 2 つの属性を指定しなければなりません。

• Objid

  一意のオブジェクト識別子を書き込みます。

• 操作

  作成中の通知または要求について記述した操作を書き込みます。操作名を判定するには、ターゲットプロセスの ptype 定義またはその他のプロトコル定義を参照します。

操作引数などの他のメッセージ属性を完成するには、tt_message_attribute_set ( ) 呼び出しを使用します。

メッセージコールバックの追加

ある要求がメッセージコールバックルーチンを含んでいる場合、コールバックルーチンは、応答が受信されると自動的に呼び出され、応答結果を調査して適切な処置を行います。

コールバックは、登録した順序と逆の順序で呼び出されます (つまり、最後に追加したコールバックが最初に呼び出されます)。

コールバックルーチンを要求に追加するには、tt_message_callback_add を使用します。応答が返され、コールバックルーチンが応答メッセージを処理し終わった場合、コールバックルーチンが TT_CALLBACK_PROCESSED を返す前に、その応答メッセージを破棄しなければなりません。応答メッセージを破棄するには、例 8-4 で示すように tt_message_destroy を使用します。

例 8-4 メッセージの破棄

Tt_callback_action
sample_msg_callback(Tt_message m, Tt_pattern p)
{
	... process the reply msg ...

	tt_message_destroy(m);
	return TT_CALLBACK_PROCESSED;
}

次のコード例は、cntl_msg_callback というコールバックルーチンです。このルーチンは、応答の状態フィールドを調査し、状態が起動済み、処理済み、または失敗である場合に処理を実行します。

/*
 * Default callback for all the ToolTalk messages we send.
 */

Tt_callback_action
cntl_msg_callback(m, p)
     Tt_message m;
     Tt_pattern p;
{
	int		mark;
	char		msg[255];
	char		*errstr;


	mark = tt_mark();
	switch (tt_message_state(m)) {
	      case TT_STARTED:
		    xv_set(cntl_ui_base_window, FRAME_LEFT_FOOTER,
		       "Starting editor...", NULL);
		    break;
	      case TT_HANDLED:
		    xv_set(cntl_ui_base_window, FRAME_LEFT_FOOTER, "", NULL);
		    break;
	      case TT_FAILED:
		    errstr = tt_message_status_string(m);
		    if (tt_pointer_error(errstr) == TT_OK && errstr) {
			sprintf(msg,"%s failed: %s", tt_message_op(m), errstr);
		    } else if (tt_message_status(m) == TT_ERR_NO_MATCH) {
			sprintf(msg,"%s failed: Couldn't contact editor",
				tt_message_op(m),
				tt_status_message(tt_message_status(m)));
		    } else {
			sprintf(msg,"%s failed: %s",
				tt_message_op(m),
				tt_status_message(tt_message_status(m)));
		    }
		    xv_set(cntl_ui_base_window, FRAME_LEFT_FOOTER, msg, NULL);
		    break;
	      default:
		    break;
	}
	/*
	 * no further action required for this message. Destroy it
	 * and return TT_CALLBACK_PROCESSED so no other callbacks will
	 * be run for the message.
	 */
	tt_message_destroy(m);
	tt_release(mark);
	return TT_CALLBACK_PROCESSED;
}

ptype のシグニチャの opnum に接続すると、静的パターンにコールバックを追加することもできます。opnum を持つ静的パターンと一致したためにメッセージが配信されると、ToolTalk サービスはその opnum に付加されているコールバックをすべて調べて起動します。

• osignature の opnum にコールバックルーチンを付加するには、tt_otype_opnum_callback_add を使用してください。

• psignature の opnum にコールバックルーチンを付加するには、tt_ptype_opnum_callback_add を使用してください。

メッセージの送信

メッセージが完成したら、tt_message_send を使用して送信します。

ToolTalk サービスが TT_WRN_STALE_OBJID を返した場合は、ToolTalk データベースで転送ポインタを検索したことを意味します。そのポインタは、メッセージに指定されたオブジェクトが移動したことを示します。ただし、ToolTalk サービスは、新しい objid を使用してメッセージを送信します。その後、tt_message_object を使用してメッセージから新しい objid を検索し、内部のデータ構造体に入れることができます。

将来必要としないメッセージ (たとえば通知など) がある場合は、tt_message_destroy を使用して、メッセージを削除して記憶領域を解放できます。

メッセージに対する応答がありそうな場合は、応答を処理する前にメッセージを破棄しないでください。