共通デスクトップ環境 ToolTalk メッセージの概要

付録 A メッセージ・ツールキット

ToolTalk メッセージ・ツールキットは、ToolTalk アプリケーション・プログラミング・インタフェース (API) のハイレベルなインタフェースです。同じメッセージ・プロトコルに準拠する他のアプリケーションとの最適な相互運用のための基本的な ToolTalk のメッセージと機能をアプリケーションへ簡単に統合できるよう共通の定義と規約を提供します。

ToolTalk メッセージ・ツールキットのメッセージの大部分は、標準 ToolTalk メッセージ・セットに含まれています。メッセージ・ツールキットの関数は別々にコーディングする必要があるいくつかのタスクを透過的に処理します。たとえば、ttdt_file_join() 関数はパターンを登録し、指定された配信範囲にある指定のファイルへの Deleted、Reverted、Moved、および Saved 通知を監視します。コールバック・メッセージも呼び出します。

ToolTalk メッセージ・ツールキットの一般的な説明

相互運用は、別々に開発されたアプリケーションを同時に実行する場合には重要なテーマです。相互運用アプリケーションの開発者は、ツールキットのメッセージを一致させています。つまり、プロトコルは小型の十分に定義されたインタフェースを形成します。このインタフェースは、アプリケーションの自律性を最大限にします。

ToolTalk メッセージ・ツールキットは、アプリケーションの相互運用において重要であり、メッセージに対する完全なサポートを提供します。メッセージ・プロトコル仕様は、メッセージの設定とアプリケーションがメッセージを受信したときの動作を含んでいます。これらのメッセージは、アプリケーションの機能を利用するために既存のアプリケーションに対して更新できます。共有している情報を送信、受信、および使用するために既存のアプリケーションにこれらのメッセージを簡単に追加できます。

ToolTalk メッセージ規約に準拠しているツールは、意味が異なる場合同じ ToolTalk 構文を使用しません。同じ意味の場合は異なる ToolTalk 構文を使用するのでツール間の通信に失敗することもありません。プロトコルが監視されている場合、互いに影響を及ぼすことなく連携するアプリケーションを変更したり置き換えたりすることもできます。

メッセージ・ツールキットのメッセージの大部分は、標準 ToolTalk メッセージ・セットに含まれています。標準 ToolTalk メッセージ・セットの詳細は、『ToolTalk リファレンスマニュアル』を参照してください。表 A-1 に、この章で説明する関数の一覧を示します。これらの関数は、ToolTalk メッセージ・ツールキットの一部を構成します。

表 A-1 ToolTalk メッセージ・ツールキット関数


関数	説明
`ttdt_close()`	ToolTalk 通信終端を破棄します。
`ttdt_file_event()`	ファイルに関するイベントを通知します。
`ttdt_file_join()`	ファイルに関する ToolTalk イベントを監視できるように登録します。
`ttdt_file_notice()`	ファイルに関する標準 ToolTalk 通知を作成して送信します。
`ttdt_file_quit()`	ファイルに関する ToolTalk イベントにおける配信対象を登録解除します。
`ttdt_file_request()`	ファイルに関する標準 ToolTalk 要求を作成して送信します。
`ttdt_Get_Modified()`	ファイルに変更内容を保留している ToolTalk クライアントがないかどうかを問い合わせます。
`ttdt_message_accept()`	ToolTalk 要求の処理を引き受けます。
`ttdt_open()`	ToolTalk 通信終端を作成します。
`ttdt_Revert()`	ファイルの内容を最後に保存した内容に戻すよう ToolTalk クライアントに要求します。
`ttdt_Save()`	ToolTalk クライアントがファイルを保存するよう要求します。
`ttdt_sender_imprint_on()`	ツールに指定の ToolTalk ツールの動作や特性をエミュレートさせます。
`ttdt_session_join()`	ToolTalk セッションに参加し、多くの標準デスクトップ・メッセージのパターンとデフォルトのコールバックを登録します。
`ttdt_session_quit()`	セッションに参加した時に登録したパターンとデフォルトのコールバックをすべて登録解除し、ToolTalk セッションを終了します。
`ttdt_subcontract_manage()`	未処理の要求を管理します。
`ttmedia_Deposit()`	ドキュメントにチェックポイントを設定するための Deposit 要求を送信します。
`ttmedia_load()`	ドキュメントの表示、編集、作成のための Media Exchange 要求を作成して送信します。
`ttmedia_load_reply()`	Display 要求、Edit 要求、または Compose 要求に返信します。
`ttmedia_ptype_declare()`	Media Exchange メディア・エディタの ptype を宣言します。
`tttk_block_while()`	返信などの待機中にプログラムをブロックします。
`tttk_message_abandon()`	メッセージを無視または拒否してから破棄します。
`tttk_message_create()`	メッセージ規約に準拠しているメッセージを作成します。
`tttk_message_fail()`	メッセージを無視します。
`tttk_message_receive()`	次の ToolTalk メッセージを取り出します。
`tttk_message_reject()`	メッセージを拒否します。
`tttk_op_string()`	オペレーションに対する文字列を返します。
`tttk_string_op()`	文字列に対するオペレーションを返します。
`tttk_Xt_input_handler()`	Xt クライアントのための ToolTalk イベントを処理します。

ToolTalk の規約

ツールキットのメッセージ規約の大部分は、標準 ToolTalk メッセージ・セットの記述で構成されます。この節では、特定の標準メッセージ・セットには関係ない規約について説明します。

表 A-2 メッセージ・ツールキット規約


フィールド	説明
fileAttrib	メッセージのファイル属性を設定できるかどうか、または設定する必要があるかどうかを示します。ToolTalk サービスには、各メッセージがファイルを参照し、名前が付いているファイルでは「配信対象である」クライアントにメッセージを配信できる機能 (「ファイル配信範囲指定機能」と呼ぶ) があります。
opName	オペレーション名またはイベント名 (「op」ともいう)。重要なのは、ツールが異なっても意味が同じものに対しては同じ opName を使用することです。メッセージが標準のものではない場合、その opName は一意でなければなりません。たとえば、opName に `Company_Product` (`Acme_HoarkTool_Hoark_My_Frammistat` など) という接頭辞を付けます。
requiredArgs	メッセージに必ず含まれていなければならない引き数
optionalArgs	メッセージに含まれることもある特別引き数。メッセージ内のオプション引き数は、指定の順序で必須の引き数の後ろに指定しなければなりません。
vtype argumentName	特定の引き数についての記述。vtype は、メッセージ引き数に含まれるデータの種類を表す文字列で、プログラマが定義します。ToolTalk サービスは、送信メッセージ・インスタンスと登録されているメッセージ・パターンとを照合する場合にだけ vtype を使用します。各 vtype は、規約により一般的な単一の既知のデータ型に対応づけなければなりません。

アプリケーション記述時のメッセージ・ツールキットの使用

ツールキットを使用するには、ToolTalk メッセージ・ツールキットのヘッダ・ファイルを組み込みます。

   #include <Tt/tttk.h>

ToolTalk メッセージ・ツールキット

この節では、ToolTalk メッセージ・ツールキットの一部である関数について説明します。

`ttdt_close`

Tt_status   ttdt_close( const char *    procid,
                        const char *    new_procid,
                        int             sendStopped );

ttdt_close() 関数は、ToolTalk 通信終端を破棄します。この関数は、ToolTalk 関数 tt_close() を呼び出します。

procid の値が != 0 の場合、この関数は次を呼び出します。
```
    tt_default_procid_set(    procid    )
```
new_procid の値が != 0 の場合、この関数は次を呼び出します。
```
    tt_default_procid_set(    new_procid )
```
sendStopped パラメータが設定されている場合、この関数は Stopped 通知を送信します。

ttdt_close() 関数は、ToolTalk 関数 tt_default_procid_set() および tt_close() が返すどのようなエラーも返す可能性があります。Sending 通知が失敗した場合、エラーは伝達されません。

`ttdt_file_event`

Tt_status   ttdt_file_event(    Tt_message      context,
                                Tttk_op         event,
                                Tt_pattern *    patterns,
                                int             send );

ttdt_file_event() 関数は、ToolTalk サービスを介してファイルに関するイベントを通知します。この関数は、指定されたファイルに関係のあるイベントを知らせる ToolTalk メッセージを作成し、必要に応じて送信します。このファイルは、patterns の作成時に ttdt_file_join() 関数に渡されたパス名で示されます。

表 A-3 では、event パラメータの値に対応する通知内容を示します。

表 A-3 event パラメータの通知内容


通知される `event`	通知内容
`TTDT_MODIFIED`	`ttdt_file_join()` 関数に渡された配信範囲を登録し、Get_Modified 要求、Save 要求、Revert 要求を処理する配信対象ツールへイベントを通知します。
`TTDT_SAVED, TTDT_REVERTED`	Get_Modified 要求、Save 要求、Revert 要求のハンドラ・パターンを登録解除します。 `send` パラメータが設定された場合、配信範囲に応じて Saved 通知か Reverted 通知を送信します。

send パラメータを設定すると、配信範囲に Modified 通知を送信します。
context パラメータがゼロ以外の値のとき、このルーチンによって作成されるメッセージはスロット名が ENV_ で始まるすべてのコンテキストを継承します。

表 A-4 では、この関数が返す可能性のあるエラーの一覧を示します。

表 A-4 ttdt_file_event が返す可能性のあるエラー


エラーの値	説明
`TT_DESKTOP_EINVAL`	イベント通知が無効です。有効なイベント通知は、`TTDT_MODIFIED`、`TTD_TSAVED`、`TTDT_REVERTED` です。
`TT_ERR_POINTER`	`patterns` パラメータが NULL です。
`TT_ERR_OVERFLOW`	ToolTalk サービスが受信したメッセージの数が、正しく処理可能なアクティブ・メッセージの最大数 (2000) に達しました。
`TT_ERR_NOMP`	ttsession プロセスを使用できません。ToolTalk サービスは、ttsession が実行されていない場合はその再起動を試みます。このエラーは、ToolTalk サービスがインストールされていないか正しくインストールされていないかのどちらかを示します。

`ttdt_file_join`

Tt_message  ( *Ttdt_file_cb)(   Tt_message      msg,
                                Tttk_op         op,
                                char *          pathname,
                                void *          clientdata,
                                int             same_euid_egid,
                                int             same_procid );    
Tt_pattern * ttdt_file_join(    const char *    pathname,
                                Tt_scope        the_scope,
                                int             join,
                                Ttdt_file_cb    cb,
                                void *          clientdata );

ttdt_file_join() 関数は、指定のファイルに関する ToolTalk イベントを監視できるように登録します。Deleted、Modified、Reverted、Moved、Saved の 5 種類の通知を監視するように配信範囲に登録します。

コールバック・メッセージ引き数 Ttdt_file_cb は、表 A-5 に示すパラメータを取ります。

表 A-5 Ttdt_file_cb が取るパラメータ


パラメータ	説明
`message`	送信中のメッセージ
`op`	要求されているオペレーション
`pathname`	メッセージに関連付けられたファイルのパス名。このコピーは、ToolTalk 関数 `tt_free()` で解放できます。
`clientdata`	メッセージに含まれているクライアント・データ
`same_euid_egid`	送信側を識別するフラグ。この値が true の場合は、送信側の信頼性は高いです。
`same_procid`	送信側を識別するフラグ。この値が true の場合は、送信側の procid は受信側と同じです。

the_scope パラメータの値がゼロ (つまり TT_SCOPE_NONE) の場合、ファイルの配信範囲はデフォルト (TT_BOTH) に設定されます。しかし、たとえば ToolTalk データベース・サーバ rpc.ttdbserver が pathname を所有するファイル・サーバにインストールされていない場合、ファイル配信範囲は TT_FILE_IN_SESSION に設定されます。

ttdt_file_join() 関数は the_scope の値および pathname のコピーとを Tt_patterns 型の戻り値に関連付けることで、ttdt_file_quit() 関数がパターンにアクセスすることを可能にします。呼び出し側は、ttdt_file_join() 呼び出しが返ると、pathname を変更または解放できます。

join パラメータの値が true の場合、この関数は次を呼び出します。
```
        tt_file_join(    pathname  )
```

この関数は、NULL で終了する Tt_pattern 型の配列を返します。この配列を破棄するには、ttdt_file_quit() 関数を使用します。エラーが返される場合、返された配列は tt_ptr_error で解読できるエラー・ポインタです。表 A-6 は、ttdt_file_join() 関数が返す可能性のあるエラーの一覧です。

表 A-6 ttdt_file_join が返す可能性のあるエラー


エラーの値	説明
`TT_ERR_NOMP`	ttsession プロセスが存在しません。ToolTalk サービスは、ttsession が実行されていない場合はその再起動を試みます。このエラーは、ToolTalk サービスがインストールされていないか正しくインストールされていないかのどちらかを示します。
`TT_ERR_DBAVAIL`	ToolTalk サービスが、このオペレーションに必要な ToolTalk データベースにアクセスできませんでした。
`TT_ERR_DBEXIST`	ToolTalk サービスが、指定された ToolTalk データベースを予期した場所で見つけることができませんでした。
`TT_ERR_PATH`	ToolTalk サービスが、指定されたファイル・パス名でディレクトリを読み取ることができませんでした。
`TT_ERR_NOMEM`	オペレーションを実行するのに十分なメモリがありません。

`ttdt_file_notice`

Tt_message  ttdt_file_notice(   Tt_message      context,
                                Tttk_op         op,
                                T_scope         scope,
                                const char *    pathname,
                                int             send_and_destroy );

ttdt_file_notice() 関数は、ファイルに関する標準 ToolTalk 通知を作成し、必要に応じて送信します。Created、Deleted、Moved、Reverted、Saved、Modified の 6 種類の標準ファイル通知を作成するには、この関数を使用します。

注 -

ttdt_file_event() 関数は、ttdt_file_notice() 関数よりもハイレベルなインタフェースです。Moved 通知以外のすべての通知を送信する場合は、この関数を使用するようにしてください。

context パラメータがゼロ以外の値のとき、このルーチンによって作成されるメッセージは、スロット名が ENV_ で始まるすべてのコンテキストを継承します。
この関数は指定の op パラメータと scope パラメータで通知を作成し、そのファイル属性を pathname パラメータに設定します。
send_and_destroy パラメータを設定すると、この関数はメッセージを送信してから破棄します。

send_and_destroy パラメータの値が false の場合、作成されたメッセージが返されます。send_and_destroy パラメータの値が true の場合、ゼロが返されます。

エラーが発生すると、エラー・ポインタが返されます。Tt_status を調べるには、tt_ptr_error を使用します。表 A-7 では、この関数が返す可能性のあるエラーについて説明します。

表 A-7 ttdt_file_notice が返す可能性のあるエラー


エラーの値	説明
`TT_ERR_NOMP`	ttsession プロセスが存在しません。ToolTalk サービスは、ttsession が実行されていない場合はその再起動を試みます。このエラーは、ToolTalk サービスがインストールされていないか正しくインストールされていないかのどちらかを示します。
`TT_ERR_PROCID`	指定されたプロセス識別子が旧式か、無効です。
`TT_ERR_NOMEM`	オペレーションを実行するのに十分なメモリがありません。
`TT_ERR_OVERFLOW`	ToolTalk サービスが受信したメッセージの数が、正しく処理可能なアクティブ・メッセージの最大数 (2000) に達しました。
`TT_ERR_DBAVAIL`	ToolTalk サービスが、このオペレーションに必要な ToolTalk データベースにアクセスできませんでした。
`TT_ERR_DBEXIST`	ToolTalk サービスが、指定された ToolTalk データベースを予期した場所で見つけることができませんでした。
`TT_DESKTOP_EINVAL`	オペレーションが移動され、`send_and_destroy` パラメータの値が true です。
`TT_ERR_POINTER`	パス名が NULL か、ToolTalk エラー・ポインタでした。

`ttdt_file_quit`

Tt_status   ttdt_file_quit( Tt_pattern *    patterns,
                            int             quit );

ttdt_file_quit() 関数は、ファイルの ToolTalk イベントにおける配信対象を登録解除します。この関数はパターンを破棄します。quit パラメータが設定されると、この関数は次を呼び出します。

    tt_file_quit( pathname )

patterns の作成時に ttdt_file_join() 関数に渡したパス名における配信対象を登録解除する場合にこの関数を使用します。表 A-8 に、この関数が返す可能性のあるエラーの一覧を示します。

表 A-8 ttdt_file_quit が返す可能性のあるエラー


エラーの値	説明
`TT_ERR_NOMP`	ttsession プロセスを使用できません。ToolTalk サービスは、ttsession が実行されていない場合はその再起動を試みます。このエラーは、ToolTalk サービスがインストールされていないか正しくインストールされていないかのどちらかを示します。
`TT_ERR_PROCID`	指定されたプロセス識別子が旧式か、無効です。
`TT_ERR_DBAVAIL`	ToolTalk サービスが、このオペレーションに必要な ToolTalk データベースにアクセスできませんでした。
`TT_ERR_DBEXIST`	ToolTalk サービスが、指定された ToolTalk データベースを予期した場所で見つけることができませんでした。
`TT_ERR_POINTER`	パターンが NULL か、無効です。

`ttdt_file_request`

Tt_message      ttdt_file_request(  Tt_message        context,
                                    Tttk_op           op,
                                    Tt_scope          scope,
                                    const char        pathname,
                                    Ttdt_file_cb      cb,
                                    void              client_data,
                                    int               send_and_destroy  );

ttdt_file_request() 関数は、標準デスクトップのファイルに対する配信範囲指定要求 (Get_Modified、Save、Revert など) を作成し、必要に応じて送信します。

注 -

この関数は、ttdt_Get_Modified() 関数、ttdt_Save() 関数、ttdt_Revert() 関数よりもローレベルのインタフェースです。要求を作成してから送信し、その応答に応じてブロックします。

ttdt_file_request() 関数は、指定の op と scope で要求を作成し、そのファイル属性を pathname に設定します。デスクトップ・メッセージ規約に従い、TT_IN と vtype File のまだ設定されていない Tt_mode 型引き数が要求に追加されます。指定のオペレーションが TTDT_GET_MODIFIED() の場合は、TT_OUT と vtype Boolean のまだ設定されていない Tt_mode 型引き数も要求に追加されます。

context パラメータがゼロ以外の値のとき、このルーチンによって作成される要求は、スロット名が ENV_ で始まるすべてのコンテキストを context から継承します。

この関数は、作成された要求のメッセージ・コールバックとして cb をインストールし、クライアント・データが確実にコールバックに渡されるようにします。send が true の場合、この関数はハンドルを返す前に要求を送信します。

この関数は正常終了時に、作成された Tt_message を返します。エラーが発生すると、エラー・ポインタが返されます。Tt_status を調べるには、tt_ptr_error を使用します。表 A-9 には、この関数が返す可能性のあるエラーの一覧を示します。

表 A-9 ttdt_file_request が返す可能性のあるエラー


エラーの値	説明
`TT_ERR_NOMP`	ttsession プロセスを使用できません。ToolTalk サービスは、ttsession が実行されていない場合はその再起動を試みます。このエラーは、ToolTalk サービスがインストールされていないか正しくインストールされていないかのどちらかを示します。
`TT_ERR_PROCID`	指定されたプロセス識別子が旧式か、無効です。
`TT_ERR_NOMEM`	オペレーションを実行するのに十分なメモリがありません。
`TT_ERR_OVERFLOW`	ToolTalk サービスが受信したメッセージの数が、正しく処理可能なアクティブ・メッセージの最大数 (2000) に達しました。
`TT_ERR_DBAVAIL`	ToolTalk サービスが、このオペレーションに必要な ToolTalk データベースにアクセスできませんでした。
`TT_ERR_DBEXIST`	ToolTalk サービスが、指定された ToolTalk データベースを予期した場所で見つけることができませんでした。
`TT_ERR_POINTER`	パス名が NULL か、無効です。

`ttdt_Get_Modified`

int     ttdt_Get_Modified(  Tt_message          context,
                            const char *        pathname,
                            Tt_scope            the_scope,
                            XtAppContext        app2run,
                            int                 ms_timeout );

ttdt_Get_Modified() 関数は、ファイルに変更内容を保留している ToolTalk クライアントがないかどうか問い合わせます。この関数は、Get_Modified 要求を送信して応答を待ちます。

context パラメータがゼロ以外の値のとき、このルーチンによって作成されるメッセージは、スロット名が ENV_ で始まるすべてのコンテキストを継承します。
Get_Modified 要求は、固定表示を行うつもりの pathname に変更内容を保留している ToolTalk クライアントがないかどうか問い合わせます。
the_scope パラメータは、Get_Modified 要求が送信される配信範囲を示します。このパラメータの値がゼロ (つまり TT_SCOPE_NONE) の場合、ファイルの配信範囲はデフォルト (TT_BOTH) に設定されます。しかし、たとえば ToolTalk データベース・サーバ rpc.ttdbserver が pathname を所有するファイル・サーバにインストールされていない場合、ファイル配信範囲は TT_FILE_IN_SESSION に設定されます。
app2run パラメータと ms_timeout パラメータは、この関数が送信する Get_Modified 要求への応答をブロックするために、tttk_block_while() 関数に渡されます。

Get_Modified 要求が指定のタイムアウト時間内に肯定応答を受信すると、ttdt_Get_Modified() 関数はゼロ以外を返します。そうでない場合は、ゼロを返します。この呼び出しはエラーを返しません。

`ttdt_message_accept`

Tt_pattern *    ttdt_message_accept(    Tt_message          contract,
                                        Ttdt_contract_cb    cb, 
                                        void *              clientdata,
                                        Widget              shell, 
                                        int                 accept, 
                                        int                 sendStatus );

ttdt_message_accept() 関数は、ToolTalk 要求を処理することを受け入れます。ツールは、要求の処理 (つまり、無視したり拒否すること) を受け入れる場合にこの関数を呼び出します。

Ttdt_contract_cb 引き数は、表 A-10 に示すパラメータを取ります。

表 A-10 Ttdt_contract_cb 引き数が取るパラメータ


パラメータ	説明
`Tt_message msg`	送信状態にある要求。クライアント・プログラムは、この要求を無視または拒否する、あるいはメッセージに応答します。
`Tttk_op op`	着信中の要求のオペレーション
`Widget shell`	`ttdt_message_accept()` 関数に渡すシェル
`void *clientdata`	`ttdt_message_accept()` 関数に渡すクライアント・データ
`Tt_message contract`	`ttdt_message_accept()` 関数に渡すコントラクト

メッセージ msg を正常に処理すると、コールバックはゼロを返します。そうでない場合は、Tt_message に送られた tt_error_pointer を返します。

メッセージ msg を処理しない場合、コールバックはメッセージを返し、TT_CALLBACK_CONTINUE ルーチンを呼び出しスタックに渡してメッセージを他のコールバックに提供するか、メッセージを tt_message_receive() 呼び出しに返します。

ttdt_message_accept() 関数は、ハンドラを宛先とする要求 (表 A-11 を参照してください) をデフォルト・セッションで登録します。

表 A-11 ttdt_message_accept が登録する要求


要求	処理方法
`Get_Geometry, Set_Geometry`	`shell` パラメータが NULL でない場合、これらの要求は透過的に処理されます。`shell` パラメータが NULL で、`cb` パラメータが NULL でない場合は、これらの要求はコールバック・ルーチンに渡されます。それ以外の場合は、これらの要求はエラー `TT_DESKTOP_ENOTSUP` とともに異常終了します。
`Get_Iconified, Set_Iconified`	`shell` パラメータが NULL でない場合、これらの要求は透過的に処理されます。`shell` パラメータが NULL で、`cb` パラメータが NULL でない場合は、これらの要求はコールバック・ルーチンに渡されます。それ以外の場合は、これらの要求はエラー `TT_DESKTOP_ENOTSUP` とともに異常終了します。
`Get_Mapped, Set_Mapped`	`shell` パラメータが NULL でない場合、これらの要求は透過的に処理されます。`shell` パラメータが NULL で、`cb` パラメータが NULL でない場合は、これらの要求はコールバック・ルーチンに渡されます。それ以外の場合は、これらの要求はエラー `TT_DESKTOP_ENOTSUP` とともに異常終了します。
`Raise`	`shell` パラメータが NULL でない場合、この要求は透過的に処理されます。`shell` パラメータが NULL で、`cb` パラメータが NULL でない場合は、この要求はコールバック・ルーチンに渡されます。それ以外の場合は、この要求はエラー `TT_DESKTOP_ENOTSUP` とともに異常終了します。
`Lower`	`shell` パラメータが NULL でない場合、この要求は透過的に処理されます。`shell` パラメータが NULL で、`cb` パラメータが NULL でない場合は、この要求はコールバック・ルーチンに渡されます。それ以外の場合は、この要求はエラー `TT_DESKTOP_ENOTSUP` とともに異常終了します。
`Get_XInfo, Set_XInfo`	`shell` パラメータが NULL でない場合、これらの要求は透過的に処理されます。`shell` パラメータが NULL で、`cb` パラメータが NULL でない場合は、これらの要求はコールバック・ルーチンに渡されます。それ以外の場合は、これらの要求はエラー `TT_DESKTOP_ENOTSUP` とともに異常終了します。
`Pause`	`cb` パラメータが NULL でない場合、この要求はコールバック・ルーチンに渡されます。cp パラメータが NULL の場合は、エラー `TT_DESKTOP_ENOTSUP` とともに異常終了します。
`Resume`	`cb` パラメータが NULL でない場合、この要求はコールバック・ルーチンに渡されます。cp パラメータが NULL の場合は、エラー `TT_DESKTOP_ENOTSUP` とともに異常終了します。
`Quit`	`cb` パラメータが NULL でない場合、この要求はコールバック・ルーチンに渡されます。cp パラメータが NULL の場合は、エラー `TT_DESKTOP_ENOTSUP` とともに異常終了します。
`Get_Status`	`cb` パラメータが NULL でない場合、この要求はコールバック・ルーチンに渡されます。cp パラメータが NULL の場合は、エラー `TT_DESKTOP_ENOTSUP` とともに異常終了します。

contract 引き数が TT_WRN_START_MESSAGE メッセージ・ステータスの時、メッセージはツールを起動します。

注 -

起動したツールは、その ptype にすでにディスパッチされている他のメッセージを受信するため、コントラクトを受け入れる前に使用したい配信範囲に参加する必要があります。そうしないと、ツールは動作中にその ptype の宣言を解除しなければなりません。ツールがどの配信範囲にも参加していないと、ディスパッチされたメッセージによって ptype の他のインスタンスが起動されます。

  tt_message_accept(  contract    )

sendStatus 引き数が true の場合、ttdt_open() 関数に渡されたパラメータ (存在する場合) を使用して、ttdt_message_accept() 関数は要求側に Status 通知を送信します。

この関数は、NULL で終了する Tt_pattern 型の配列を返します。この配列を破棄する場合は、tttk_patterns_destroy() 関数を使用します。エラーが返される場合、返された配列は tt_ptr_error で解読されるエラー・ポインタになります。表 A-12 は、ttdt_message_accept() 関数が返す可能性のあるエラーの一覧です。

表 A-12 ttdt_message_accept が返す可能性のあるエラー


エラーの値	説明
`TT_ERR_NOMP`	ttsession プロセスを使用できません。ToolTalk サービスは、ttsession が実行されていない場合はその再起動を試みます。このエラーは、ToolTalk サービスがインストールされていないか正しくインストールされていないかのどちらかを示します。
`TT_ERR_POINTER`	渡されたポインタが、このオペレーションに適した型のオブジェクトを指していません。たとえば、文字列が必要なときにポインタは整数を指している場合などです。
`TT_ERR_UNIMP`	デフォルト・セッションの ttsession は、`tt_message_accept()` 関数をサポートしていないバージョン (1.0 または 1.0.1) です。注 - 注: `contract` 引き数のメッセージ・ステータスが `TT_WRN_START_MESSAGE` の場合、ツールの ptype に対して送信されるメッセージは、`contract` が拒否、応答、または無視されるまでブロックされます。

`ttdt_open`

char *  ttdt_open(  int *           ttfd,
                    const char *    toolname,
                    const char *    vendor,
                    const char *    version,
                    int             sendStarted );

ttdt_open() 関数は、ToolTalk 通信終端を作成します。この関数は、tt_open()関数と tt_fd() 関数を呼び出します。ttdt_open() 関数は、toolname、vendor、version と作成された procid とを関連付けます。新しい procid のデフォルト・コンテキストを environ(5) から初期化します。sendStarted 引き数が設定された場合は、Started 通知を送信します。

ttdt_open() 関数は、tt_free() 関数で解放できる文字列に、作成された procid を返します。

この関数は、tt_open() 関数および tt_fd() 関数で発生したどのようなエラーも返すことができます。Started 通知が失敗した場合、エラーは伝達されません。

`ttdt_Revert`

Tt_status       ttdt_Revert(    Tt_message      context,
                                const char *    pathname,
                                Tt_scope        the_scope, 
                                XtAppContext    app2run,
                                int             ms_timeout );

ttdt_Revert() 関数は、ファイル内容を元に戻すように ToolTalk クライアントに要求します。この関数は、Revert 要求を the_scope に送信し、応答を待ちます。Revert 要求は、pathname に保留中の変更を破棄するように、処理中である ToolTalk クライアントに求めます。

context パラメータがゼロ以外の値のとき、このルーチンによって作成されるメッセージは、スロット名が ENV_ で始まるすべてのコンテキストを継承します。
the_scope パラメータの値がゼロ (つまり TT_SCOPE_NONE) の場合、ファイルの配信範囲はデフォルト (TT_BOTH) に設定されます。しかし、たとえば ToolTalk データベース・サーバ rpc.ttdbserver が pathname を所有するファイル・サーバにインストールされていない場合、ファイル配信範囲は TT_FILE_IN_SESSION に設定されます。
app2run パラメータと ms_timeout パラメータは、この関数が送信する Revert 要求への応答をブロックするために、tttk_block_while() 関数に渡されます。

要求が指定のタイムアウト時間内に肯定応答を受信すると、ttdt_Revert() 関数は TT_OK を返します。そうでない場合は、失敗した応答に対する tt_message_status の戻り値、または表 A-13 に示すエラーのいずれかを返します。

表 A-13 ttdt_Revert が返す可能性のあるエラー


エラーの値	説明
`TT_ERR_NOMP`	ttsession プロセスを使用できません。ToolTalk サービスは、ttsession が実行されていない場合はその再起動を試みます。このエラーは、ToolTalk サービスがインストールされていないか正しくインストールされていないかのどちらかを示します。
`TT_ERR_PROCID`	指定されたプロセス識別子が旧式か、無効です。
`TT_ERR_NOMEM`	オペレーションを実行するのに十分なメモリがありません。
`TT_ERR_OVERFLOW`	ToolTalk サービスが受信したメッセージの数が、正しく処理可能なアクティブ・メッセージの最大数 (2000) に達しました。
`TT_ERR_DBAVAIL`	ToolTalk サービスが、このオペレーションに必要な ToolTalk データベースにアクセスできませんでした。
`TT_ERR_DBEXIST`	ToolTalk サービスが、指定された ToolTalk データベースを予期した場所で見つけることができませんでした。
`TT_DESKTOP_ETIMEOUT`	指定されたタイムアウト時間内に応答を受信しませんでした。
`TT_DESKTOP_EPROTO`	要求が無視されました。しかしハンドラは、特定のエラー・ステータスの代わりに失敗した応答に対する `tt_message_status` の戻り値を `TT_OK` に設定します。
`TT_ERR_POINTER`	パス名が NULL か、ToolTalk エラー・ポインタです。

`ttdt_Save`

Tt_status   ttdt_Save(  Tt_message      context,
                        const char *    pathname,
                        Tt_scope        the_scope,
                        XtAppContext    app2run,
                        int             ms_timeout );

ttdt_Save() 関数はファイルを保存するように ToolTalk クライアントに要求します。この関数は、Save 要求を the_scope に送信し、応答を待ちます。Save 要求は、pathname に保留中の変更を破棄するように、処理中である ToolTalk クライアントに求めます。

context パラメータがゼロ以外の値のとき、このルーチンによって作成されるメッセージは、スロット名が ENV_ で始まるすべてのコンテキストを継承します。
the_scope パラメータの値がゼロ (つまり TT_SCOPE_NONE) の場合、ファイルの配信範囲はデフォルト (TT_BOTH) に設定されます。しかし、たとえば ToolTalk データベース・サーバ rpc.ttdbserver が pathname を所有するファイル・サーバにインストールされていない場合、ファイル配信範囲は TT_FILE_IN_SESSION に設定されます。
app2run パラメータと ms_timeout パラメータは、この関数が送信する Save 要求への応答をブロックするために、tttk_block_while() 関数に渡されます。

要求が指定のタイムアウト時間内に肯定応答を受信すると、ttdt_Save() 関数は TT_OK を返します。そうでない場合は、失敗した応答に対する tt_message_status の戻り値、または表 A-14 に示すエラーのいずれかを返します。

表 A-14 ttdt_Save が返す可能性のあるエラー


エラーの値	説明
`TT_ERR_NOMP`	ttsession プロセスを使用できません。ToolTalk サービスは、ttsession が実行されていない場合はその再起動を試みます。このエラーは、ToolTalk サービスがインストールされていないか、正しくインストールされていないかのどちらかを示します。
`TT_ERR_PROCID`	指定されたプロセス識別子が旧式か、無効です。
`TT_ERR_NOMEM`	オペレーションを実行するのに十分なメモリがありません。
`TT_ERR_OVERFLOW`	ToolTalk サービスが受信したメッセージの数が、正しく処理可能なアクティブ・メッセージの最大数 (2000) に達しました。
`TT_ERR_DBAVAIL`	ToolTalk サービスが、このオペレーションに必要な ToolTalk データベースにアクセスできませんでした。
`TT_ERR_DBEXIST`	ToolTalk サービスが、指定された ToolTalk データベースを予期した場所で見つけることができませんでした。
`TT_DESKTOP_ETIMEOUT`	指定されたタイムアウト時間内に応答を受信しませんでした。
`TT_DESKTOP_EPROTO`	要求が無視されました。しかし、ハンドラは、特定のエラー・ステータスの代わりに失敗した応答に対する `tt_message_status` の戻り値を `TT_OK` に設定します。
`TT_ERR_POINTER`	パス名が NULL か、ToolTalk エラー・ポインタです。

`ttdt_sender_imprint_on`

Tt_status   ttdt_sender_imprint_on(     const char *    handler,
                                        Tt_message      contract,
                                        char **         display,
                                        int *           width,
                                        int *           height,
                                        int *           xoffset,
                                        int *           yoffset,
                                        XtAppContext    app2run,
                                        int             ms_timeout);

ttdt_sender_imprint_on() 関数を呼び出すと、呼び出し側ツール (以下、ツール B とします) で別のツール (以下ツール A とします) の動作と特定の特性が採用されます。ツール B は、ツール A の X11 ディスプレイ、ロケール、現在の作業ディレクトリを採用します。さらに、自身を正しい位置に置くためにツール A の X11 ジオメトリを取得します。

display パラメータが NULL の場合、環境変数 $DISPLAY はツール A のディスプレイに設定されます。display パラメータが NULL でない場合、ツール A のディスプレイがこのパラメータに返されます。戻り値は、ToolTalk の tt_free() 関数で解放できる文字列です。

この関数は、Get_Geometry 要求をツール A に送信します。ツール A がジオメトリ・パラメータに対して値を返さない場合は、次のようになります。

width パラメータに対して値が返されない場合、-1 を設定します。
height パラメータに対して値が返されない場合、-1 を設定します。
xoffset パラメータに対して値が返されない場合、INT_MAX を設定します。
yoffset パラメータに対して値が返されない場合、INT_MAX を設定します。

ttdt_sender_imprint_on() 関数の width パラメータ、height パラメータ、xoffset パラメータ、および yoffset パラメータすべてに NULL を設定すると、Get_Geometry 要求はツール A に送信されません。

app2run パラメータと ms_timeout パラメータは、この関数が送信する Get_Geometry 要求への応答をブロックするために、tttk_block_while() 関数に渡されます。

表 A-15 は、この関数が返す可能性のあるエラーの一覧です。

表 A-15 ttdt_sender_imprint_on が返す可能性のあるエラー


エラーの値	説明
`TT_DESKTOP_ETIMEDOUT`	指定されたタイムアウト時間内に送信された要求の一部が完了しませんでした。
`TT_ERR_NOMP`	ttsession プロセスを使用できません。ToolTalk サービスは、ttsession が実行されていない場合はその再起動を試みます。このエラーは、ToolTalk サービスがインストールされていないか、正しくインストールされていないかのどちらかを示します。
`TT_ERR_PROCID`	指定されたプロセス識別子が旧式か、無効です。
`TT_ERR_NOMEM`	オペレーションを実行するのに十分なメモリがありません。
`TT_ERR_OVERFLOW`	ToolTalk サービスが受信したメッセージの数が、正しく処理可能なアクティブ・メッセージの最大数 (2000) に達しました。

`ttdt_session_join`

Tt_message  ( *Ttdt_contract_cb) (  Tt_message          msg,
                                    void *              clientdata
                                    Tt_message          contract );     
Tt_pattern  * ttdt_session_join (   const char *        sessid,
                                    Ttdt_session_cb     cb,
                                    Widget              shell,
                                    void *              clientdata,
                                    int                 join);

ttdt_session_join() 関数は、「デスクトップの良き市民」として ToolTalk セッションに参加します。つまり、セッション sessid への参加時に多くの標準デスクトップ・メッセージ・インタフェースのパターンとデフォルト・コールバックを登録します。表 A-16 は、この関数が現在登録しているメッセージ・インタフェースの一覧です。

表 A-16 ttdt_session_join が登録している標準メッセージ


要求	処理方法
`Get_Environment, Set_Environment`	これらのメッセージは透過的に処理されます。
`Get_Locale, Set_Locale`	これらのメッセージは透過的に処理されます。
`Get_Situation, Set_Situation`	これらのメッセージは透過的に処理されます。
`Signal`	このメッセージは透過的に処理されます。
`Get_Sysinfo`	このメッセージは透過的に処理されます。
`Get_Geometry, Set_Geometry`	`shell` パラメータの値が NULL でなく、シェルが実体化された mappedWhenManaged applicationShellWidget の場合は、これらのメッセージは透過的に処理されます。シェルが mappedWhenManaged applicationShellWidget でない場合は、エラー `TT_DESKTOP_ENOTSUP` とともに異常終了します。
`Get_Iconified, Get_Iconified`	`shell` パラメータの値が NULL でなく、シェルが実体化された mappedWhenManaged applicationShellWidget の場合は、これらのメッセージは透過的に処理されます。シェルが mappedWhenManaged applicationShellWidget でない場合は、エラー `TT_DESKTOP_ENOTSUP` とともに異常終了します。
`Get_Mapped, Set_Mapped`	`shell` パラメータの値が NULL でなく、シェルが実体化された mappedWhenManaged applicationShellWidget の場合は、これらのメッセージは透過的に処理されます。シェルが mappedWhenManaged applicationShellWidget でない場合は、エラー `TT_DESKTOP_ENOTSUP` とともに異常終了します。
`Raise`	`shell` パラメータの値が NULL でなく、シェルが実体化された mappedWhenManaged applicationShellWidget の場合は、これらのメッセージは透過的に処理されます。シェルが mappedWhenManaged applicationShellWidget でない場合は、エラー `TT_DESKTOP_ENOTSUP` とともに異常終了します。
`Lower`	`shell` パラメータの値が NULL でなく、シェルが実体化された mappedWhenManaged applicationShellWidget の場合は、これらのメッセージは透過的に処理されます。シェルが mappedWhenManaged applicationShellWidget でない場合は、エラー `TT_DESKTOP_ENOTSUP` とともに異常終了します。
`Get_XInfo`	`shell` パラメータの値が NULL でない場合、これらのメッセージは透過的に処理されます。shell パラメータの値が NULL の場合は、エラー `TT_DESKTOP_ENOTSUP` とともに異常終了します。
`Set_XInfo`	`shell` パラメータの値が NULL でなく、シェルが実体化された mappedWhenManaged applicationShellWidget の場合は、これらのメッセージは透過的に処理されます。シェルが mappedWhenManaged applicationShellWidget でない場合は、エラー `TT_DESKTOP_ENOTSUP` とともに異常終了します。
`Pause`	`cb` パラメータが NULL でない場合は、このメッセージはコールバックに渡されます。`cb` パラメータが NULL の場合は、エラー `TT_DESKTOP_ENOTSUP` とともに異常終了します。
`Resume`	`cb` パラメータが NULL でない場合は、このメッセージはコールバックに渡されます。`cb` パラメータが NULL の場合は、エラー TT_DESKTOP_ENOTSUP とともに異常終了します。
`Quit`	`cb` パラメータが NULL でない場合は、このメッセージはコールバックに渡されます。`cb` パラメータが NULL の場合は、エラー `TT_DESKTOP_ENOTSUP` とともに異常終了します。
`Get_Status`	`cb` パラメータが NULL でない場合は、このメッセージはコールバックに渡されます。`cb` パラメータが NULL の場合は、エラー `TT_DESKTOP_ENOTSUP` とともに異常終了します。
`Do_Command`	`cb` パラメータが NULL でない場合は、このメッセージはコールバックに渡されます。`cb` パラメータが NULL の場合は、エラー TT_DESKTOP_ENOTSUP とともに異常終了します。

sessid パラメータが NULL の場合は、デフォルト・セッションに参加します。

join パラメータが設定されている場合は、指定のセッションに参加します。

Ttdt_contract_cb メッセージは、表 A-17 に示すパラメータを取ります。コールバックはメッセージを処理しない場合は、メッセージを返します。メッセージを処理する場合は、ゼロあるいは Tt_message に送られたエラー・ポインタを返します。

表 A-17 Ttdt_session_cb が取るパラメータ


パラメータ	説明
`Tt_message msg`	送信状態にある要求。クライアント・プログラムは、この要求を無視または拒否するか、メッセージに応答します。注 - 注: 処理後にメッセージ `msg` を破棄してください。
`void *clientdata`	`ttdt_session_join()` または `ttdt_message_accept()` 関数のどちらかに渡されるクライアント・データ
`Tt_messagecontract`	`ttdt_message_accept()` 関数に渡されるコントラクト。コールバックが `ttdt_session_join()` 関数によってインストールされると、`contract` パラメータの値は必ずゼロになります。

ttdt_session_join() 関数は、NULL で終了する Tt_pattern 型の配列を返します。この配列は、ttdt_session_quit() 関数に渡され破棄できます。エラーが発生すると、返された配列はエラー・ポインタになります。Tt_status を調べるには、tt_ptr_error を使用します。表 A-18 は、返される可能性のあるエラーの一覧です。

表 A-18 ttdt_session_join が返す可能性のあるエラー


エラーの値	説明
`TT_ERR_NOMP`	ttsession プロセスを使用できません。ToolTalk サービスは、ttsession が実行されていない場合はその再起動を試みます。このエラーは、ToolTalk サービスがインストールされていないか、正しくインストールされていないかのどちらかを示します。
`TT_ERR_PROCID`	指定されたプロセス識別子が旧式か、無効です。
`TT_ERR_SESSION`	旧式、または無効な ToolTalk セッションが指定されました。
`TT_ERR_POINTER`	渡されたポインタが、このオペレーションに適した型のオブジェクトを指していません。たとえば、文字列が必要なときにポインタは整数を指している場合などです。
`TT_ERR_NOMEM`	オペレーションを実行するのに十分なメモリがありません。

`ttdt_session_quit`

Tt_status   ttdt_session_quit(    const char *      sessid,
                                  Tt_pattern *      sess_pats,
                                  int               quit );

ttdt_session_quit() 関数は、「デスクトップの良き市民」として ToolTalk セッションを終了します。つまり、セッションへの参加時に登録したすべてのパターンとデフォルト・コールバックを登録解除します。

この関数は、sess_pats で指定されたすべてのパターンを破棄します。quit パラメータが設定されると、セッション sessid を終了します。sessid パラメータが NULL の場合は、デフォルト・セッションを終了します。

表 A-19 は、この関数が返す可能性のあるエラーの一覧です。

表 A-19 ttdt_session_quit が返す可能性のあるエラー


エラーの値	説明
`TT_ERR_NOMP`	ttsession プロセスを使用できません。ToolTalk サービスは、ttsession が実行されていない場合はその再起動を試みます。このエラーは、ToolTalk サービスがインストールされていないか、正しくインストールされていないかのどちらかを示します。
`TT_ERR_PROCID`	指定されたプロセス識別子が旧式か、無効です。
`TT_ERR_SESSION`	旧式、または無効な ToolTalk セッションが指定されました。
`TT_ERR_POINTER`	渡されたポインタが、このオペレーションに適した型のオブジェクトを指していません。たとえば、文字列が必要なときにポインタは整数を指している場合などです。

`ttdt_subcontract_manage`

Tt_pattern *ttdt_subcontract_manage(    Tt_message              contract,
                                        Ttdt_contract_cb        cb,
                                        Widget                  shell,
                                        void *                  clientdata);

ttdt_subcontract_manage() 関数は、未処理の要求を管理します。この関数が呼び出されると、要求側ツールは要求を処理しているツールとの間で行われるデスクトップ上の標準的な対話を管理できます。この関数は、TT_HANDLER を宛先とする Get_Geometry 要求と Get_XInfo 要求、および Status 通知のための登録をデフォルト・セッションで行います。

shell パラメータが NULL の場合は、要求または通知が cb パラメータに渡されます。shell パラメータが NULL でない場合は、要求は透過的に処理されます。

ttdt_subcontract_manage() 関数は、NULL で終了する Tt_pattern 型の配列を返します。この配列は、ttdt_session_quit() 関数に渡して破棄できます。エラーが発生すると、返された配列はエラー・ポインタになります。Tt_status を調べるには、tt_ptr_error を使用します。表 A-20 は、返される可能性のあるエラーの一覧です。

表 A-20 ttdt_subcontract_manage が返す可能性のあるエラー


エラーの値	説明
`TT_ERR_NOMEM`	オペレーションを実行するのに十分なメモリがありません。
`TT_ERR_NOMP`	ttsession プロセスを使用できません。ToolTalk サービスは、ttsession が実行されていない場合はその再起動を試みます。このエラーは、ToolTalk サービスがインストールされていないか、正しくインストールされていないかのどちらかを示します。
`TT_ERR_PROCID`	指定されたプロセス識別子が旧式か、無効です。
`TT_ERR_POINTER`	`subcontract` パラメータが有効な `Tt_message` ではありません。
`TT_ERR_EINVAL`	`shell` パラメータと `cb` パラメータの両方が NULL です。

`ttmedia_Deposit`

Tt_status   ttmedia_Deposit(    Tt_message              load_contract,
                                const char *            buffer_id,
                                const char *            media_type,
                                const unsigned char *   new_contents,
                                int                     new_len,
                                const char *            pathname,
                                XtAppContext            app2run,
                                int                     ms_timeout );

ttmedia_Deposit 関数は Deposit 要求を送信して、Edit、Compose、Open などの Media Exchange load_contract 要求の変換対象であったドキュメントにチェックポイントを設定します。

この関数は Deposit 要求を作成して送信し、その要求が成功したか失敗したかを返します。

load_contract は、このエディタがドキュメントを読み込むことを要求します。
buffer_id は、ドキュメントが Open 要求により読み込まれた場合に、このエディタが作成したバッファの ID です。
media_type は、送信された要求の contents 引き数の vtype です。
new_contents と new_len は、contents 引き数の値です。

要求が送信されると、app2run と ms_timeout は、応答を待つために、tttk_block_while() 関数に渡されます。

表 A-21 ttmedia_Deposit が返す可能性のあるエラー


エラーの値	説明
`TT_ERR_NOMP`	ttsession プロセスを使用できません。ToolTalk サービスは、ttsession が実行されていない場合はその再起動を試みます。このエラーは、ToolTalk サービスがインストールされていないか、正しくインストールされていないかのどちらかを示します。
`TT_ERR_PROCID`	指定されたプロセス識別子が旧式か、無効です。
`TT_ERR_NOMEM`	オペレーションを実行するのに十分なメモリがありません。
`TT_ERR_OVERFLOW`	ToolTalk サービスが受信したメッセージの数が、正しく処理可能なアクティブ・メッセージの最大数 (2000) に達しました。
`TT_ERR_DBAVAIL`	ToolTalk サービスが、このオペレーションに必要な ToolTalk データベースにアクセスできませんでした。
`TT_ERR_DBEXIST`	ToolTalk サービスが、指定された ToolTalk データベースを予期した場所で見つけることができませんでした。
`TT_DESKTOP_ETIMEOUT`	指定されたタイムアウト時間内に応答を受信しませんでした。
`TT_ERR_POINTER`	パス名が NULL、または ToolTalk エラー・ポインタです。

`ttmedia_load`

Tt_message  (*Ttmedia_load_msg_cb)( Tt_message              msg,
                                    void *                  clientdata,
                                    Tttk_op                 op,
                                    unsigned char *         contents,
                                    int                     len,
                                    char *                  file  );    
Tt_message  ttmedia_load(   Tt_message              context,
                            Ttmedia_load_msg_cb     cb,
                            void *                  clientdata,
                            Tttk_op                 op,
                            const char *            media_type,
                            const unsigned char*    contents,
                            int                     len,
                            const char *            file,
                            const char *            docname,
                            int                     send );

ttmedia_load() 関数は、ドキュメントの表示、編集、作成を行う Media Exchange 要求を作成し、必要に応じて送信します。この関数は、Display、Edit、Compose のいずれかの要求を作成して送信します。

注 -

要求のハンドラとの標準的な対話を管理するには、このメッセージで作成した要求の送信後すぐに ttdt_subcontract_manage() 関数を使用してください。

context 引き数の値がゼロ以外のとき、このルーチンによって作成されるメッセージは、スロット名が ENV_ で始まるすべてのコンテキストを継承します。

clientdata 引き数は、応答を受信する場合、またはドキュメントの中間のバージョンが Deposit 要求によってチェックポイントを設定される場合に cb 引き数に渡されます。

op 引き数は、TTME_DISPLAY、TTME_EDIT、TTME_COMPOSE のいずれかでなければなりません。

media_type 引き数は、ドキュメントのデータ形式に名前を付けます。通常、この引き数により、要求を処理するためにどのアプリケーションを選択するか決定します。

contents 引き数と len 引き数はドキュメントを指定します。これら両方の引き数の値がゼロで、file 引き数の値がゼロでない場合、ドキュメントは指定のファイルに格納されていると想定されます。

docname 引き数が NULL でないとき、その値はドキュメントのタイトルとして使用されます。

send 引き数が true のとき、メッセージは返される前に送信されます。

表 A-22 は、Ttmedia_load_msg_cb メッセージが取るパラメータの一覧です。

表 A-22 Ttmedia_load_msg_cb が取るパラメータ


パラメータ	説明
`Tt_message msg`	要求に対する応答。または読み込み要求の `tt_message_id` を指定する `messageID` 引き数が指定された Deposit 要求。このパラメータの値が Deposit 要求である場合、クライアント・プログラムは要求に応答するか、無視しなければなりません。注 - メッセージ `msg` は処理後に破棄してください。
`Tttk_op op`	メッセージのオペレーション (`TTME_DEPOSIT` あるいは `ttmedia_load()` メッセージに渡されたオペレーション)
`unsigned char * contents` `int len` `char *file`	到着中のドキュメントの内容。`len` 引き数がゼロのとき、ドキュメントは指定のファイルに格納されています。`contents` 引き数または `file` 引き数が NULL でない場合は、ToolTalk 関数 `tt_free()` を使用してそれらの引き数を解放してください。
`void *clientdata`	`ttmedia_load()` メッセージに渡されたクライアント・データ

メッセージが正常に処理されると、コールバックはゼロを返します。処理中にエラーが発生した場合は、コールバックは Tt_message に伝えられたエラー・ポインタを返します。

コールバックがメッセージ msg を処理しない場合、コールバックはメッセージを返し、TT_CALLBACK_CONTINUE ルーチンを呼び出しスタックに渡してメッセージを他のコールバックに提供するか、メッセージを tt_message_receive() 関数に返します。

終了時に、ttmedia_load() 関数は、構築するように要求された要求を返します。エラーが発生した場合、この関数はエラー・ポインタを返します。Tt_status を調べるには、tt_ptr_error を使用します。表 A-23 は、返される可能性のあるエラーの一覧です。

表 A-23 ttmedia_load が返す可能性のあるエラー


エラーの値	説明
`TT_ERR_NOMP`	ttsession プロセスを使用できません。ToolTalk サービスは、ttsession が実行されていない場合はその再起動を試みます。このエラーは、ToolTalk サービスがインストールされていないか、正しくインストールされていないかのどちらかを示します。
`TT_ERR_PROCID`	指定されたプロセス識別子が旧式か、無効です。
`TT_ERR_NOMEM`	オペレーションを実行するのに十分なメモリがありません。
`TT_ERR_OVERFLOW`	ToolTalk サービスが受信したメッセージの数が、正しく処理可能なアクティブ・メッセージの最大数 (2000) に達しました。

`ttmedia_load_reply`

Tt_message      ttmedia_load_reply (Tt_message              contract,
                                    const unsigned char *   new_contents, 
                                    int                     new_len,
                                    int                     reply_and_destroy);

ドキュメントの表示、編集、作成を行う Media Exchange 要求に対して応答するには、ttmedia_load_reply() 関数を使用します。

new_contents 引き数と new_len 引き数の両方がゼロでない場合、それらの値は contract 引き数の適切な出力引き数にドキュメントの新しい内容を設定するのに使用されます。reply_and_destroy 引き数が true の場合、contract 引き数に対して応答が行われ、その後メッセージは破棄されます。

表 A-24 は、返される可能性のあるエラーの一覧です。

表 A-24 ttmedia_load_reply が返す可能性のあるエラー


エラーの値	説明
`TT_ERR_NOMP`	ttsession プロセスを使用できません。ToolTalk サービスは、ttsession が実行されていない場合はその再起動を試みます。このエラーは、ToolTalk サービスがインストールされていないか、正しくインストールされていないかのどちらかを示します。
`TT_ERR_PROCID`	指定されたプロセス識別子が旧式か、無効です。
`TT_ERR_NUM`
`TT_ERR_NOTHANDLER`

`ttmedia_ptype_declare`

Tt_message      (*Ttmedia_load_pat_cb)( Tt_message          msg,
                                        void *              clientdata,
                                        Tttk_op             op,
                                        Tt_status           diagnosis,
                                        unsigned char *     contents,
                                        int                 len,
                                        char *              file,
                                        char *              docname ); 
Tt_status       ttmedia_ptype_declare(  const char *        ptype,
                                        int                 base_opnum,
                                        Ttmedia_load_pat_cb cb,
                                        void *              clientdata,
                                        int                 declare );

ttmedia_ptype_declare() 関数は、Media Exchange メディア・エディタの ptype を宣言します。この関数は、特定のメディア型用の Media Exchange メッセージ・インタフェースを実装するエディタを初期化します。

エディタが ptype でサポートされる種類のドキュメントを編集するように要求される場合、この関数は cb 引き数を呼び出します。
この関数は、ptype が含まれていると想定される一連のシグニチャーに、ツールキット内部のオペレーション番号 (opnum) コールバックをインストールします。ツールキット内部の opnum コールバックは、これらのシグニチャーのいずれかに一致する要求を受信すると、clientdata を cb 引き数に渡します。opnum は、base_opnum から始まり、ゼロか 1000 の倍数でなければなりません。
declare 引き数が true のとき、この関数は次を呼び出します。
```
    tt_ptype_declare(    ptype )
```

ptype が複数の異なるメディア型を実現する場合、ttmedia_ptype_declare() 関数を 2 回以上呼び出すことができます。base_opnum には、各呼び出しで異なる値を指定しなければなりません。

注 -

ttmedia_ptype_declare() 関数は何回も呼び出すことができますが、declare 引き数を「true」に設定できるのは 1 回だけです。

表 A-25 は、Ttmedia_load_pat_cb メッセージが取るパラメータの一覧です。

表 A-25 Ttmedia_load_pat_cb メッセージが取るパラメータ


パラメータ	説明
`Tt_message msg`	送信された要求。クライアント・プログラムは、この要求を無視または拒否する、あるいは要求に応答しなければなりません。
`Tt_message msg`	送信された要求。クライアント・プログラムは、この要求を無視または拒否する、あるいは要求に応答しなければなりません。
`Tttk_op op`	着信中の要求のオペレーション (`TTME_COMPOSE`、`TTME_EDIT`、`TTME_DISPLAY` のいずれか)
`Tt_status diagnosis`	ツールキットが要求を無視するように勧告するときに使用するエラー・コード (たとえば、`TT_DESKTOP_ENODATA`)。`diagnosis` が `TT_OK` ではなく、コールバック・ルーチンがメッセージ `msg` を返す場合、ツールキットはメッセージ `msg` を無視し破棄します。
`unsigned char * contents` `int len` `char *file`	到着中のドキュメントの内容。`len` 引き数がゼロのとき、ドキュメントは指定のファイルに格納されています。`contents` 引き数または `file` 引き数が NULL でない場合は、ToolTalk 関数 `tt_free` を使用して、それらの引き数を解放します。
`char * docname`	ドキュメントに名前が付けられている場合はその名前
`void * clientdata`	`ttmedia_ptype_declare()` メッセージに渡すクライアント・データ

コールバックがメッセージ msg を処理せず、diagnosis 引き数の値が TT_OK でない場合、コールバックはメッセージを返し、ツールキットは TT_CALLBACK_CONTINUE ルーチンを呼び出しスタックに渡してメッセージを他のコールバックに提供するか、メッセージを tt_message_receive() 呼び出しに返します。

エラーが発生すると、この関数は表 A-26 にあるエラーのうちのいずれかを返します。

表 A-26 ttmedia_ptype_declare が返す可能性のあるエラー


エラーの値	説明
`TT_ERR_NOMP`	ttsession プロセスを使用できません。ToolTalk サービスは、ttsession が実行されていない場合はその再起動を試みます。このエラーは、ToolTalk サービスがインストールされていないか、正しくインストールされていないかのどちらかを示します。
`TT_ERR_PROCID`	指定されたプロセス識別子が旧式か、無効です。
`TT_ERR_PTYPE`	ToolTalk サービスが、指定された ptype を検出することができません。
`TT_ERR_POINTER`	渡されたポインタが、このオペレーションに適した型のオブジェクトを指していません。たとえば、文字列が必要なときにポインタは整数を指している場合などです。

`tttk_block_while`

Tt_status       tttk_block_while(   const int       *blocked,
                                    int             ms_timeout);

tttk_block_while 関数は、ms_timout で指定されたタイムアウト時間中にプログラムが応答を待っている間プログラムをブロックします。

`tttk_message_abandon`

Tt_status       tttk_message_abandon (  Tt_message      msg );

tttk_message_abandon() 関数は、要求を放棄した後に破棄します。

注 -

プログラムは、メッセージを理解できずに処分したいときはメッセージを放棄しなければなりません。

エラーが発生すると、この関数は表 A-27 にあるエラーのうちのいずれかを返します。

表 A-27 tttk_message_abandon が返す可能性のあるエラー


エラーの値	説明
`TT_ERR_NOMP`	ttsession プロセスを使用できません。ToolTalk サービスは、ttsession が実行されていない場合はその再起動を試みます。このエラーは、ToolTalk サービスがインストールされていないか、正しくインストールされていないかのどちらかを示します。
`TT_ERR_POINTER`	渡されたポインタが、このオペレーションに適した型のオブジェクトを指していません。たとえば、文字列が必要なときにポインタは整数を指している場合などです。
`TT_ERR_NOTHANDLER`

`tttk_message_create`

Tt_message  tttk_message_create(    Tt_message                  context,
                                    Tt_class                    the_class,
                                    Tt_scope                    the_scope,
                                    const char *                handler,
                                    const char *                op,
                                    Tt_message_callback         callback);

tttk_message_create() 関数は、規約に従ったメッセージを作成します。この関数を使用すれば、継承されたコンテキストをあるメッセージから別のメッセージに伝達するメッセージを簡単に作成できます。

tttk_message_create() 関数はメッセージを作成し、スロット名が ENV_ で始まる context からすべてのコンテキスト・スロットを新しいメッセージ上にコピーします。作成されたメッセージには、the_class パラメータに指定された Tt_class 値と the_scopee パラメータに指定された Tt_scope 値が設定されます。

handler パラメータが NULL の場合、メッセージには TT_PROCEDURE の Tt_address が設定されます。handler パラメータが NULL でない場合は、メッセージは TT_HANDLER を経由して procid に送信されます。

op 引き数が NULL でない場合、その値にはメッセージの op 引き数が設定されます。

コールバック引き数が NULL でない場合、その値がメッセージ・コールバックとしてメッセージに追加されます。

正常終了時には、tttk_message_create() 関数は作成した Tt_message を返します。これは、他の Tt_message と同じ方法で変更、送信、および破棄できます。

エラーが発生すると、エラー・ポインタが返されます。Tt_status を調べるには、tt_ptr_error を使用します。表 A-28 は、返される可能性のあるエラーの一覧です。

表 A-28 tttk_message_create が返す可能性のあるエラー


エラーの値	説明
`TT_ERR_NOMP`	ttsession プロセスを使用できません。ToolTalk サービスは、ttsession が実行されていない場合はその再起動を試みます。このエラーは、ToolTalk サービスがインストールされていないか、正しくインストールされていないかのどちらかを示します。
`TT_ERR_PROCID`	指定されたプロセス識別子が旧式か、無効です。
`TT_ERR_NOMEM`	オペレーションを実行するのに十分なメモリがありません。

`tttk_message_destroy`

Tt_status  tttk_message_destroy    (    Tt_message      msg );

tttk_message_destroy() 関数は、規約に従うすべてのメッセージを破棄します。

注 -

このメッセージは、tt_message_destroy() メッセージの代わりに使用できます。

tttk_message_destroy() 関数は、ttdt_message_accept() 関数あるいは ttdt_subcontract_manage() 関数によってメッセージに格納されたパターンを破棄し、その後メッセージ msg を tt_message_destroy() 関数に渡します。

この関数は、tt_message_destroy() 関数によって返された値を返します。

`tttk_message_fail`

Tt_status   tttk_message_fail(      Tt_message              msg,
                                    Tt_status               status,
                                    const char              *status_string,
                                    int                     destroy );

tttk_mesage_fail() 関数は、メッセージ msg を無視した後で破棄します。

注 -

プログラムは、メッセージを理解できずに処分したいときは、メッセージを放棄しなければなりません。

状態が TT_SENT であるメッセージは無視できます。メッセージが、ハンドラが宛先指定されているメッセージ、あるいは TT_WRN_START_MESSAGE の tt_message_status を持つ場合、そのメッセージを無視できます。

この関数は、TT_DESKTOP_ENOTSUP を返します。

`tttk_message_receive`

Tt_status   tttk_message_receive(   const char*     procid );

tttk_message_receive() 関数は、tt_message_receive() 関数を呼び出し、次の ToolTalk メッセージを取り出します。

procid がゼロでない場合、この関数は次を呼び出します。

    tt_default_procid_set( procid )

`tttk_message_reject`

Tt_status   tttk_message_reject(    Tt_message              msg,
                                    Tt_status               status,
                                    const char*             status_string,
                                    int                     destroy );

tttk_message_reject() 関数は、メッセージ msg を拒否した後で破棄します。

注 -

プログラムは、メッセージを理解できずに処分したいときは、メッセージを放棄しなければなりません。

状態が TT_SENT であるメッセージは拒否できます。メッセージが、ハンドラが宛先指定されているメッセージでない、あるいは TT_WRN_START_MESSAGE 以外の tt_message_status を持つ場合、そのメッセージを拒否できます。

この関数は、TT_DESKTOP_ENOTSUP を返します。

`tttk_op_string`

char            *tttk_op_string(    Tttk_op                     op);

tttk_op_string() 関数は、正常終了する場合はオペレーション op に対する文字列を返します。そうでない場合、この関数はゼロを返します。

注 -

返された文字列を解除するには、tt_free() 関数を使用してください。

Tttk_op         tttk_string_op( const char *        opstring );

tttk_string_op() 関数は、指定の文字列に対するオペレーションを保持している文字列を返します。エラーが発生すると、この関数は TTDT_OP_NONE を返します。

`tttk_Xt_input_handler`

void        tttk_Xt_input_handler(  XtPointer       procid,
                                    int *           source,
                                    XtInputId *     id );

tttk_Xt_input_handler() 関数は、Xt クライアントのための ToolTalk イベントを処理します。一部のメッセージがコールバックで処理されないと予期される場合を除き、この関数を Xt 入力ハンドラとして使用します。

この関数は、procid 引き数を tttk_message_receive() 関数に渡し、すべての返されたメッセージ (つまり、コールバックで処理されないメッセージ) を tttk_message_abandon() 関数に渡します。

この関数がエラー TT_ERR_NOMP を返すと、tttk_Xt_input_handler() 関数は id パラメータを XtRemoveInput() 関数に渡します。