ToolTalk ユーザーズガイド

動的メッセージの定義

動的メッセージパターンを作成し登録するためには、新しいパターンオブジェクトを割り当て、適切な情報を書き込んでから登録します。パターンが必要なくなった (つまり、そのパターンに一致するメッセージを対象としなくなった) 場合は、パターンを登録解除するか削除します。必要に応じて、動的メッセージパターンを登録および登録解除できます。

動的メッセージパターンの作成、登録、および登録解除に使用される ToolTalk 関数を表 9–1 に示します。

表 9–1 メッセージパターンの作成、更新、および削除用の関数


ToolTalk 関数	機能
`tt_pattern_create(void)`	パターンの作成
`tt_pattern_arg_add(Tt_pattern p, Tt_mode n, const char vtype, const char value)`	文字列引数の追加
`tt_pattern_barg_add(Tt_pattern m, Tt_mode n, const char vtype, const unsigned char value, int len)`	バイト配列引数の追加
`tt_pattern_iarg_add(Tt_pattern m, Tt_mode n, const char *vtype, int value)`	整数引数の追加
`tt_pattern_xarg_add(Tt_pattern m, Tt_mode n, const char vtype, xdrproc_t xdr_proc, void value)`	バイト配列に xdr 引数を追加
`tt_pattern_bcontext_add(Tt_pattern p, const char slotname, const unsigned char value, int length);`	バイト配列コンテキストの追加
`tt_pattern_context_add(Tt_pattern p, const char slotname, const char value);`	文字列コンテキストの追加
`tt_pattern_icontext_add(Tt_pattern p, const char *slotname, int value);`	整数コンテキストの追加
`tt_pattern_address_add(Tt_pattern p, Tt_address d)`	アドレスの追加
`tt_pattern_callback_add(Tt_pattern p, Tt_message_callback_action f)`	メッセージコールバックの追加
`tt_pattern_category_set(Tt_pattern p, Tt_category c)`	カテゴリの設定
`tt_pattern_class_add(Tt_pattern p, Tt_class c)`	クラスの追加
`tt_pattern_disposition_add(Tt_pattern p, Tt_disposition r)`	処置の追加
`tt_pattern_file_add(Tt_pattern p, const char *file)`	ファイルの追加
`tt_pattern_object_add(Tt_pattern p, const char *objid)`	オブジェクトの追加
`tt_pattern_op_add(Tt_pattern p, const char *opname)`	操作の追加
`tt_pattern_opnum_add(Tt_pattern p, int opnum)`	操作番号の追加
`tt_pattern_otype_add(Tt_pattern p, const char *otype)`	オブジェクト型の追加
`tt_pattern_scope_add(Tt_pattern p, Tt_scope s)`	配信範囲の追加
`tt_pattern_sender_add(Tt_pattern p, const char *procid)`	送信側プロセス識別子の追加
`tt_pattern_sender_ptype_add(Tt_pattern p, const char *ptid)`	送信側プロセス型の追加
`tt_pattern_session_add(Tt_pattern p, const char *sessid)`	セッション識別子の追加
`tt_pattern_state_add(Tt_pattern p, Tt_state s)`	状態の追加
`tt_pattern_user_set(Tt_pattern p, int key, void *v)`	ユーザーの設定
`tt_pattern_register(Tt_pattern p)`	パターンの登録
`tt_pattern_unregister(Tt_pattern p)`	パターンの登録解除
`tt_pattern_destroy(Tt_pattern p)`	メッセージパターンの削除

注 –

tt_pattern_create を除くすべての関数が返す型は、Tt_status です。tt_pattern_create は、Tt_pattern を返します。

メッセージパターンの作成

メッセージパターンを作成するには、tt_pattern_create 関数を使用します。この関数を使用して、新しいパターンオブジェクトのハンドルまたは隠されたポインタを入手できます。後続の呼び出しでは、このハンドルを使用してパターンを参照できます。

パターン情報を書き込むには、tt_pattern_attribute_add および tt_pattern_attribute_set 呼び出しを使用します。パターンに追加する各属性に複数の値を指定できます。パターンの値のどれか 1 つがメッセージの値に一致すれば、パターン属性はメッセージ属性に一致します。属性の値が指定されていない場合、ToolTalk サービスは任意の値を一致させるものと仮定します。すでに設定されているために値を 1 つだけ持つ属性もあります。

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

コールバックルーチンをユーザーのパターンに追加するには、tt_pattern_callback_add 関数を使用します。

注 –

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

ToolTalk サービスがメッセージを照合する場合、コールバックルーチンを自動的に呼び出してメッセージを検査し、適切な処置を行います。パターンに一致するメッセージは、コールバックとともに配信されると、コールバックルーチンを介して処理されます。ルーチンが終了すると、TT_CALLBACK_PROCESSED を返し、操作に使用された API オブジェクトは解放されます。その後、tt_message_destroy を使用してメッセージを削除します。それによって、メッセージが使用していた記憶領域が解放されます。次にコード例を示します。

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

tt_message_destroy(m);
return TT_CALLBACK_PROCESSED;
}

メッセージパターンの登録

完成したパターンを登録するには、tt_pattern_register() 関数を使用します。パターンを登録してから、処理の対象とするセッションまたはファイルを結合します。

次のコード例では、パターンを作成して登録しています。

	/*
	 * Create and register a pattern so ToolTalk 
 * knows we are interested
	 * in “ttsample1_value” messages within 
 * the session we join.
	 */

	pat = tt_pattern_create();
	tt_pattern_category_set(pat, TT_OBSERVE);
	tt_pattern_scope_add(pat, TT_SESSION);
	tt_pattern_op_add(pat, “ttsample1_value”);
	tt_pattern_register(pat);

メッセージパターンの削除と登録解除

注 –

アプリケーションプログラムが、削除したパターンに一致する配信済みメッセージを検索していない場合 (たとえば、メッセージが待ち行列に入れられた場合)、ToolTalk サービスは、それらのメッセージを削除しません。

メッセージパターンを削除するには、tt_pattern_destroy() 関数を使用します。この関数は最初にパターンを登録解除し、その後パターンオブジェクトを削除します。

パターンオブジェクトを削除せずに、メッセージパターンに一致するメッセージの受信を停止するには、tt_pattern_unregister() を使用してパターンを登録解除します。

tt_close を呼び出すと、ToolTalk サービスは、すべてのメッセージパターンオブジェクトを自動的に登録解除して削除します。