ToolTalk ユーザーズガイド

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 関数を示しています。

表 8–4 メッセージ作成用の関数

ToolTalk 関数 

機能 

tt_onotice_create(const char *objid, const char *op)

オブジェクト指向の通知を作成する 

tt_orequest_create(const char *objid, const char *op)

オブジェクト指向の要求を作成する 

tt_pnotice_create(Tt_scope scope, const char *op)

プロセス指向の通知を作成する 

tt_prequest_create(Tt_scope scope, const char *op)

プロセス指向の要求を作成する 

tt_message_create(void)

メッセージを作成する。この関数は、メッセージ作成用の ToolTalk 汎用関数である 


注 –

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


表 8–5 メッセージ完成用の関数

ToolTalk 関数 

機能 

tt_message_address_set(Tt_message m, Tt_address p)

アドレス指定モードを設定する (たとえば、ポイントツーポイント) 

tt_message_arg_add(Tt_message m, Tt_mode n, const char *vtype, const char *value)

NULL 終了文字列の引数を追加する 

tt_message_arg_bval_set(Tt_message m, int n, const unsigned char *value, int len)

引数の値を、指定されたバイト配列に設定する 

tt_message_arg_ival_set(Tt_message m, int n, int value)

引数の値を、指定された整数に設定する 

tt_message_arg_val_set(Tt_message m, int n, const char *value)

引数の値を、指定された NULL 終了文字列に設定する 

tt_message_barg_add(Tt_message m, Tt_mode n, const char *vtype, const unsigned char *value, int len)

バイト配列の引数を追加する 

tt_message_iarg_add(Tt_message m, Tt_mode n, const char *vtype, int value)

整数の引数を追加する 

tt_message_context_bval(Tt_message m, const char *slotname, unsigned char **value, int *len);

コンテキストの値を、指定されたバイト配列に取得する 

tt_message_context_ival(Tt_message m, const char *slotname, int *value);

コンテキストの値を、指定された整数に取得する 

tt_message_context_val(Tt_message m, const char *slotname);

コンテキストの値を、指定された文字列に取得する 

tt_message_icontext_set(Tt_message m, const char *slotname, int value);

コンテキストを、指定された整数に設定する 

tt_message_bcontext_set(Tt_message m, const char *slotname, unsigned char *value, int length);

コンテキストを、指定されたバイト配列に設定する. 

tt_message_context_set(Tt_message m, const char *slotname, const char *value);

コンテキストを、指定された NULL 終了文字列に設定する 

tt_message_class_set(Tt_message m, Tt_class c)

メッセージの型 (通知または要求) を設定する 

tt_message_file_set(Tt_message m, const char *file)

メッセージの配信範囲として指定するファイルを設定する 

tt_message_handler_ptype_set(Tt_message m, const char *ptid)

メッセージを受信する ptype を設定する 

tt_message_handler_set(Tt_message m, const char *procid)

メッセージを受信する procid を設定する 

tt_message_object_set(Tt_message m, const char *objid)

メッセージを受信するオブジェクトを設定する 

tt_message_op_set(Tt_message m, const char *opname)

メッセージを受信する操作を設定する 

tt_message_otype_set(Tt_message m, const char *otype)

メッセージを受信するオブジェクト型を設定する 

tt_message_scope_set(Tt_message m, Tt_scope s)

メッセージを受信する受信側 (ファイルまたはセッション、あるいはその両方) を設定する 

tt_message_sender_ptype_set(Tt_message m, const char *ptid)

メッセージの送信元であるアプリケーションの ptype を設定する 

tt_message_session_set(Tt_message m, const char *sessid)

メッセージの配信範囲として指定するセッションを設定する 

tt_message_status_set(Tt_message m, int status)

メッセージの状態を設定する。この状態は、受信側アプリケーションが参照する 

tt_message_status_string_set(Tt_message m, const char *status_str)

メッセージの状態を記述するテキストを設定する。このテキストは、受信側アプリケーションが参照する 

tt_message_user_set(Tt_message m, int key, void *v)

送信側アプリケーションの内部メッセージを設定する。この内部メッセージは、受信側アプリケーションが参照できない隠されたデータである 

tt_message_abstainer(Tt_message m, int n)

指定したメッセージの n 番目の忌避者の procid を返す 

tt_message_abstainers_count(Tt_message m)

オファを忌避した、TT_OFFER m に記録されている procid の数を返す

tt_message_accepter(Tt_message m,int n)

特定のメッセージを受信した n 番目の procid を返す 

tt_message_accepters_count(Tt_message m)

オファを受信した、TT_OFFER m に記録されている procid の数を返す

tt_message_rejecter(Tt_message m,int n)

指定したメッセージの n 番目の拒絶者の procid を返す 

tt_message_rejecters_count(Tt_message m)

 

オファを拒絶した、TT_OFFER m に記録されている procid の数を返す


注 –

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


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

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

クラス

アドレス


注 –

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


配信範囲

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

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

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

操作

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

引数

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

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


注 –

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


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

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

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

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

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

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

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

操作引数などの他のメッセージ属性を完成するには、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 に付加されているコールバックをすべて調べて起動します。

メッセージの送信

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

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

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


注 –

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