組み込みデスクトップ・サービス・メッセージ・セット・コマンド

次に示すコマンドは、シェル・スクリプトがデスクトップ・サービス・プロトコルの参入に必要なデスクトップ・サービス・メッセージ・セットの最小サブセットを実行します。ほとんどの ToolTalk コマンドは対応する C プログラミング・コールとわずかに異なっています。通常はポインタを返す ToolTalk コマンドでは、C アプリケーションが tt_ptr_error() 関数を呼び出すことによってそのポインタを有効にします。この関数呼び出しはポインタが有効であるかどうかを示す Tt_status 値を返します。有効でない場合は、その理由を示します。kshell コードの設計上の理由から、シェル・スクリプトが見る文字列ポインタは、通常は、基本の C コードが返す文字列ポインタと同じではありません。シェルのプログラミング中は、重要な情報が文字列ポインタではなく文字列値で示されるため、これは問題にはなりません。

シェル・スクリプトがポインタのステータスを獲得できるようにするため、通常はポインタを返すコマンドは、自動的にそのポインタに関連する Tt_status 値も返します。これによってシェル・スクリプトは、元のポインタの有効性を検査するために呼び出しを追加する必要がなくなります。ポインタ・エラーが生じた場合は、dtksh はポインタ値として空の文字列を返し、Tt_status コードを設定します。

Tt_status 値は status 引き数に返されます。Tt_status 値はエラーを示す文字列で、次のいずれかの値になります。

• TT_OK
• TT_WRN_NOTFOUND
• TT_WRN_STALE_OBJID
• TT_WRN_STOPPED
• TT_WRN_SAME_OBJID
• TT_WRN_START_MESSAGE
• TT_ERR_CLASS
• TT_ERR_DBAVAIL
• TT_ERR_DBEXIST
• TT_ERR_FILE
• TT_ERR_INVALID
• TT_ERR_MODE
• TT_ERR_ACCESS
• TT_ERR_NOMP
• TT_ERR_NOTHANDLER
• TT_ERR_NUM
• TT_ERR_OBJID
• TT_ERR_OP
• TT_ERR_OTYPE
• TT_ERR_ADDRESS
• TT_ERR_PATH
• TT_ERR_POINTER
• TT_ERR_PROCID
• TT_ERR_PROPLEN
• TT_ERR_PROPNAME
• TT_ERR_PTYPE
• TT_ERR_DISPOSITION
• TT_ERR_SCOPE
• TT_ERR_SESSION
• TT_ERR_VTYPE
• TT_ERR_NO_VALUE
• TT_ERR_INTERNAL
• TT_ERR_READONLY
• TT_ERR_NO_MATCH
• TT_ERR_UNIMP
• TT_ERR_OVERFLOW
• TT_ERR_PTPE_START
• TT_ERR_CATEGORY
• TT_ERR_DBUPDATE
• TT_ERR_DBFULL
• TT_ERR_DBCONSIST
• TT_ERR_STATE
• TT_ERR_NOMEM
• TT_ERR_SLOTNAME
• TT_ERR_XDR
• TT_DESKTOP_EPERM
• TT_DESKTOP_ENOENT
• TT_DESKTOP_EINTR
• TT_DESKTOP_EIO
• TT_DESKTOP_EAGAIN
• TT_DESKTOP_ENOMEM
• TT_DESKTOP_EACCES
• TT_DESKTOP_EFAULT
• TT_DESKTOP_EEXIST
• TT_DESKTOP_ENODEV
• TT_DESKTOP_ENOTDIR
• TT_DESKTOP_EISDIR
• TT_DESKTOP_EINVAL
• TT_DESKTOP_ENFILE
• TT_DESKTOP_EMFILE
• TT_DESKTOP_ETXBSY
• TT_DESKTOP_EFBIG
• TT_DESKTOP_ENOSPC
• TT_DESKTOP_EROFS
• TT_DESKTOP_EMLINK
• TT_DESKTOP_EPIPE
• TT_DESKTOP_ENOMSG
• TT_DESKTOP_EDEADLK
• TT_DESKTOP_ECANCELED
• TT_DESKTOP_ENOTSUP
• TT_DESKTOP_ENODATA
• TT_DESKTOP_EPROTO
• TT_DESKTOP_ENOTEMPTY
• TT_DESKTOP_ETIMEDOUT
• TT_DESKTOP_EALREADY
• TT_DESKTOP_UNMODIFIED
• TT_MEDIA_ERR_SIZE
• TT_MEDIA_ERR_FORMAT

一部のコマンドはパラメータとしてメッセージ・スコープを取ります。スコープは発信メッセージを受信する可能性のあるクライアントを示します。これらのコマンドでは、scope パラメータが次のいずれかの値に設定されます。

• TT_SCOPE_NONE
• TT_SESSION
• TT_FILE
• TT_BOTH
• TT_FILE_IN_SESSION

• TT_file_netfile variable status filename

  指定した filename (ローカル・ホストで有効と見なされるファイル名) を、対応する netfilename 書式に変換します。netfilename はネットワーク上の他のホストに渡され、他のホストに関連したパスになるように tt_netfile_file コマンドによって変換されます。

• tt_netfile_file variable status netfilename

  指定した netfilename をローカル・ホストで有効なパス名に変換します。

• tt_host_file_netfile variable status host filename

  指定したファイル (指定したホストに存在すると見なされる) を、対応する netfilename 書式に変換します。

• tt_host_netfile_file variable status host netfilename

  指定した netfilename を指定したホストで有効なパスに変換します。

• ttdt_open variable status var2 toolname vendor version sendStarted

  ToolTalk 通信エンドポイントを開きます。この接続に関連した procID を variable 引き数に返します。この接続に関連したファイル記述子は var2 に返します。ファイル記述子は代替 Xt 入力ハンドラを登録するのに使用します。sendStarted 引き数は、true が設定されると Started メッセージが自動的に送信されます。

  ttdt_open によって返される任意の procID は埋め込みスペースを含みます。kshell が procID を複数のパラメータである (埋め込みスペースを伴う 1 つのパラメータではなく) と解釈しないように、procID を含む環境変数は次に示すように常に二重引用符で囲んでください。

     ttdt_close STATUS "$PROC_ID" "" True

• tttk_Xt_input_handler procID source id

  ToolTalk メッセージを受信および処理するために、シェル・スクリプトは ttdt_open の呼び出しによって返されるファイル記述子に対して Xt 入力ハンドラを登録しなければなりません。Xt 入力ハンドラは XtAddInput コマンドを使用して登録しますが、raw 入力ハンドラとして登録してください。シェル・スクリプトが登録した入力ハンドラは tttk_Xt_input_handler を呼び出してメッセージを受信および処理します。次のコード・ブロックで実行方法を示します。

     ttdt_open PROC_ID STATUS FID "Tool" "HP" "1.0" True XtAddInput 
  INPUT_ID -r $FID "ProcessTTInput ¥"$PROC_ID¥""  
  
  ProcessTTInput()  
  {   
     tttk_Xt_input_handler $1 $INPUT_SOURCE $INPUT_ID 
  }

  代替 Xt 入力ハンドラの詳細は、XtAddInput コマンドの説明を参照してください。

  procID 環境変数を示すには、必ず前後に " (バックスラッシュと二重引用符) を付けてください。procID 環境変数の値は埋め込みスペースを含んでいて、誤って解釈される可能性があるためです。

• ttdt_close status procID newProcId sendStopped

  指定した通信接続を閉じ、sendStopped 引き数に true が設定されているとオプションで Stopped 通知を送信します。

  ttdt_open の呼び出しによって返される procID には埋め込みスペースが入っているので、procID 環境変数を示すものは次のように二重引用符で囲んでください。

     ttdt_close STATUS "$PROC_ID" "$NEW_PROC_ID" False

• ttdt_session_join variable status sessId shellWidgetHandle join

  多くの標準デスクトップ・メッセージ・インタフェースのパターン・コールバックとデフォルト・コールバックを登録することによって、適切なデスクトップとして sessID 引き数で指定したセッションを結合します。sessID 引き数が値を指定しない (つまり空の文字列である) 場合は、デフォルト・セッションが結合されます。shellWidgetHandle 引き数がウィジェット・ハンドルを指定した (つまり空の文字列ではない) 場合は、mappedWhenManaged applicationShellWidget になります。join 引き数はブール値で、true または false が設定されます。このコマンドは variable 引き数に隠された pattern ハンドルを返します。このハンドルが必要なくなったときは、ttdt_session_quit コマンドで破棄できます。

• ttdt_session_quit status sessId sessPatterns quit

  sessPatterns 引き数で指定されるメッセージ・パターンを破棄します。quit 引き数に true が設定されている場合は、sessId 引き数は表示セッションを終了します。sessId が空の場合はデフォルト・セッションを終了します。

• ttdt_file_join variable status pathName scope join ksh-command

  削除、変更、復帰、移動、保存されたメッセージの配信対象を、指定したスコープの指定したファイルに登録します。隠されたパターン・ハンドルが variable 引き数に返されます。指定したファイルのメッセージを監視する必要がなくなったときは、ttdt_file_quit コマンドで破棄できます。

  要求した ksh-command は、指定したファイルがメッセージを受信すると常に評価されます。この kshell コマンドを評価すると、次に示す環境変数が定義され、受信したメッセージに関する追加情報が提供されます。

  • DT_TT_MSG

    着信メッセージに隠されたハンドルが入っています。

  • DT_TT_OP

    実行しなければならないオペレーションを示す文字列が入っています。文字列は、 TTDT_DELETED、TTDT_MODIFIED、TTDT_REVERTED、TTDT_MOVED、 TTDT_SAVED のいずれかです。

  • DT_TT_PATHNAME

    メッセージが属するファイルのパス名が入っています。

  • DT_TT_SAME_EUID_EGID

    このプロセスと同じ有効ユーザ ID (euid) および有効グループ ID (egid) で動作するアプリケーションによってメッセージが送信された場合は true に設定されます。

  • DT_TT_SAME_PROCID

    (ttdt_open が返すのと) 同じ procID を持つアプリケーションによってメッセージが送信された場合は、true に設定されます。

  コールバックが完了すると、渡される先のメッセージが「消費」(応答、破棄、拒否のいずれか) されたかどうかが必ず示されます。コールバックがメッセージを返す場合 (DT_TT_MSG 環境変数に渡されます)、メッセージは消費されていないものと見なされます。メッセージが消費された場合は、コールバックは 0、あるいは tt_error_pointer コマンドが返す値の 1 つを返します。コールバックは値を次のように返します。

      return $DT_TT_MSG (or) return 0

• ttdt_file_quit status patterns quit

  patterns 引き数で指定するメッセージ・パターンを破棄し、quit 引き数に true が設定されている場合は、ttdt_file_joinコマンドに渡されたパス名の配信先を登録解除します。patterns 引き数は、ttdt_file_join コマンドの呼び出しによって返される値です。

• ttdt_file_event status op patterns send

  ファイルに関するイベントを通知する ToolTalk 通知を作成し、オプションで送信します。ファイルは、patterns の作成時に ttdt_file_join コマンドに渡されたパス名によって示されます。op 引き数は、指定したファイルに通知する内容を示すもので、TTDT_MODIFIED、TTDT_SAVED、TTDT_REVERTED のいずれかです。op 引き数に TTDT_MODIFIED が設定されている場合、このコマンドはGet_Modified、Save、Revertの各メッセージの処理を patterns の作成時に指定されたスコープに登録します。op 引き数に TTDT_SAVED または TTDT_REVERTED が設定されている場合は、このファイルの Get_Modified、Save、Revert の各メッセージの処理を登録解除します。send 引き数に true が設定されている場合は、表示されているメッセージが送信されます。

• ttdt_Get_Modified pathName scope timeout

  Get_Modified 要求を指定したスコープに送信し、応答があるか、指定したタイムアウト (ミリ秒単位) が経過するのを待ちます。Get_Modified 要求は、他の ToolTalk クライアントに、固定表示しようとして保留している pathname を変更したかどうかをたずねます。条件文で使用する値を返します。指定したタイムアウト内に肯定応答を受信した場合は値 true が返され、そうでない場合は false が返されます。

• ttdt_Save status pathName scope timeout

  Save 要求を指定したスコープに送信し、応答があるか、指定したタイムアウト (ミリ秒単位) が経過するのを待ちます。Save 要求は、処理中の ToolTalk クライアントに、pathName 引き数で指定したファイルで保留している変更を保存するかどうかをたずねます。指定したタイムアウト内に肯定応答を受信した場合はステータス TT_OK が返され、そうでない場合は標準の Tt_status エラー値のうちの 1 つが返されます。

• ttdt_Revert status pathName scope timeout

  Revert 要求を指定したスコープに送信し、応答があるか、指定したタイムアウト (ミリ秒単位) が経過するのを待ちます。Revert 要求は、処理中の ToolTalk クライアントに、pathName 引き数で指定したファイルで保留している変更を破棄するかどうかをたずねます。指定したタイムアウト内に肯定応答を受信した場合はステータス TT_OK が返され、そうでない場合は標準の Tt_status エラー値のうちの 1 つが返されます。

次のコマンドは通常、ttdt_file_join コマンドで登録されたコールバックが使用します。メッセージの消費および破棄を行う機能を提供します。メッセージは、拒否されるか、破棄されるか、応答されることによって消費されます。tt_error_pointer はコールバックが使用して、エラー条件を示す戻りポインタを獲得します。

• tt_error_pointer variable ttStatus

  無効なポインタを表すために ToolTalk が使用する「マジック値」を返します。マジック値は ttStatus 値が渡される先に依存して返されます。任意の有効な Tt_status 値を指定できます。

• tttk_message_destroy status msg

  msg 引き数が示すメッセージに格納されている任意のパターンを破棄し、メッセージを破棄します。

• tttk_message_reject status msg msgStatus msgStatusString destroy

  ステータスおよびステータス文字列を指定した要求メッセージに設定し、メッセージを拒否します。destroy 引き数に true が設定されている場合は、渡されるメッセージを破棄します。このコマンドは、ttdt_file_join コマンドで指定されたコールバックがメッセージを消費するための 1 つの方法です。通常、安全にメッセージを破棄するには、メッセージを拒否した後で tttk_message_destroy を使用してください。

• tttk_message_fail status msg msgStatus msgStatusString destroy

  ステータスおよびステータス文字列を指定した要求メッセージに設定し、メッセージを破棄します。destroy 引き数に true が設定されている場合は渡されるメッセージを破棄します。このコマンドは、ttdt_file_join コマンドで指定されたコールバックがメッセージを消費するための 1 つの方法です。通常、安全にメッセージを破棄するには、メッセージを拒否した後で tttk_message_destroy を使用してください。

• tt_message_reply status msg

  シェル・スクリプトがメッセージを処理し、すべて戻り値で満たされていることを ToolTalk サービスに通知します。ToolTalk サービスは、状態を TT_HANDLED に設定して送信プロセスに応答を送信します。通常、メッセージを応答した後で安全にメッセージを破棄するには、tttk_message_destroy コマンドを使用してください。