X Session Management Library(日本語訳)

  セッション・マネージャに対する接続を開設するには、SmcOpenConnection を用いる。

  引数 network_ids_list は、セッション・マネージャのネットワーク ID 群をコンマで区切って並べた、null 文字終端の文字列である。network_ids_list が NULL であれば、環境変数 SESSION_MANAGER の値を用いることになる。ネットワーク ID の一つ一つは、以下の書式で記す。

  まず最初のネットワーク ID を用いて接続を試みる。それが失敗したら、二番目のネットワーク ID を用いて接続を試みる。以下同様に試行。

  接続が確立すると、SmcOpenConnection は、続いてセッション・マネージャにクライアントを登録する。クライアントが前回セッションに属していて、今回再起動される場合、previous_id には前回セッションにおけるクライアント ID を表す null 文字終端の文字列を容れる。クライアントが初めてセッションに加わるのであれば、previous_id は NULL に設定するものとする。previous_id が指定されたものの、セッション・マネージャに無効であると判定された場合、SMlib は previous_id を NULL に設定して、再度クライアントの登録を試みる。

  SmcOpenConnection が成功すれば、戻り値として SmcConn 型の不透明な接続ポインタが返り、引数 client_id_ret にそのセッションで使用するクライアント ID が入る。client_id_ret は用が済んだ時 free で解放するものとする。SmcOpenConnection が蹉跌した場合、同関数は戻り値として NULL を返し、error_string_ret に失敗の理由を入れる。

  SMlib では、セッション・マネージャへの接続を確立するにあたって、ICE プロトコルを利用していることに注意する。クライアントとセッション・マネージャの間に既に ICE 接続が存在する場合、セッション・マネジメントでも同 ICE 接続を利用する可能性がある。

  引数 context によって、他のプロトコルと ICE 接続を共有することに対するクライアント側の態度を示す。context が NULL であれば、当関数の呼出者は常に接続の共有を試みる。context が NULL でなければ、呼出方は、自身が指定したものとは異なる、NULL でない context と結びついた既設の ICE 接続を用いない。

  先に述べたように(第三章、SMlib の ICE への依存を知る)、クライアントは何時 ICE 接続が生成・破棄されるのかを看視しておく必要がある(IceAddConnectionWatch と IceRemoveConnectionWatch を用いて)。そして同者は、select によって ICE 接続上の読み込むべきデータの存在を検知する度に、IceProcessMessages を呼び出さなければならない。詳しい情報は規格文書「Inter-Client Exchange Library」を参照。

  引数 callbacks には、セッション・マネージャからのイベントに応答する際に用いるコールバックの一群を渡す。引数 mask によって、設定するコールバックが何れと何れなのかを指定する。この版(SMlibの)で名前が出ているコールバックは全て必須である。引数 mask は、同ライブラリの将来の版において後方互換性を保つために必要なものである。

  mask の値を作るには、下記の値を組み合わせ、論理和をとる。

  クライアントは、各コールバックに対して一つづつ、クライアント・データへのポインタを付録することができる。SMlib がコールバックを呼び出す時、同ポインタは引数としてコールバックに渡ることになる。

typedef struct {

	struct {
		SmcSaveYourselfProc callback;
		SmPointer client_data;
	} save_yourself;

	struct {
		SmcDieProc callback;
		SmPointer client_data;
	} die;

	struct {
		SmcSaveCompleteProc callback;
		SmPointer client_data;
	} save_complete;

	struct {
		SmcShutdownCancelledProc callback;
		SmPointer client_data;
	} shutdown_cancelled;

} SmcCallbacks;

  セッション・マネージャとの接続を閉じるには、SmcCloseConnection を用いる。

  引数 reason_msgs は、セッションからの退座がクライアントにとって想定内のものであれば、大抵は NULL である。それ以外の場合、同引数には、終了の理由を表す、null 文字終端かつ Compound Text 形式の文字列の配列が入る。セッション・マネージャは、この理由を表すメッセージを利用者に表示するものとする。

  SMlib はセッション・マネージャに対する接続を確立するのに ICE プロトコルを使用しているので、セッション・マネジメント以外の様々なプロトコルが同一 ICE 接続上で運用されている可能性がある。SmcCloseConnection が呼び出された時、実際に ICE 接続が閉鎖されるのは、同 ICE 接続上の全てのプロトコルが終了済みの場合に限られる。ICE 接続が開閉される度に呼び出されるコールバックの設営方法を知るには、ICElib の規格文書を調べて IceAddConnectionWatch と IceRemoveConnectionWatch を見れば良い。大抵は、このコールバックを用いて、select の(あるいはXtAppAddInput 及び XtRemoveInputの)呼出し対象たる有効な ICE ファイル記述子群に対し、記述子の追加・削除を行う。

  SmcCloseConnection は次の値の何れか一つを返す。

  SmcOpenConnection で設定したコールバックを変更するには、SmcModifyCallbacks を用いる。

  引数 mask の値を作るには、下記の値を組み合わせ、論理和をとる。

  クライアントのセッション・マネジメント・プロパティを設定するには、SmcSetProperties を用いる。

  設定するプロパティ群は、プロパティのポインタの配列で指定する。関数 SmcSetProperties によって、プロパティの元の値は上書きされる。セッションが再開された時、セッション・マネージャは必ずしもプロパティの値を復元しないということに注意する。このため、クライアントはセッション・マネージャを、アプリケーション固有の状態情報を記録するデータベースとして使うべきではない。

  セッション・マネジメント・プロパティと構造体 SmProp に関する説明は、第七章、「セッション・マネジメント・プロパティ」にある。

  クライアントが前に設定したプロパティを削除するには、SmcDeleteProperties を用いる。

  クライアントが前に記録したプロパティを取得するには、SmcGetProperties を用いる。

  SmcGetProperties の戻り値は、失敗すれば 0、成功すれば正の値である。

  このライブラリは目的のプロパティが返ってくるまで入力待機する(block)するわけではない、という点に注意する。SmcPropReplyProc 型のコールバックは、そのようなやり方ではなく、データの準備が整い次第呼び出される。(訳註：セッション・マネージャが関数 SmsReturnProperties を呼び出し、その内部で SM_PropertiesReply メッセージが発行されたら、_SmcProcessMessage がそれを拾い、コールバックを実行する(libSM-1.2.1)。)

  一つ一つプロパティを解放するには、SmFreeProperty を用いる(第八章「データの解放」を参照)。ポインタの配列自体は free を用いて解放する。

  interact_style に SmInteractStyleErrors もしくは SmInteractStyleAny を付した「Save Yourself」メッセージが届いた時、クライアントは利用者とやり取りすることができる。一度に一つのクライアントしか利用者とやり取りできないため、クライアントは SmcInteractRequest を呼び出した上で、セッション・マネージャから「Interact」メッセージが返るのを待たなければならない。

  SmcInteractRequest の戻り値は、失敗すれば 0、成功すれば正の値である。

  引数 dialog_type には、SmDialogError もしくは SmDialogNormal を指定する。クライアント側がエラー・ダイアログによる表示を望めば前者を、通常のダイアログによる表示を望めば後者を用いる。

  もし終了処理(shutdown)が進行中であれば、利用者に、終了作業を中止するという選択肢が与えられる可能性もあるので注意する。終了作業が中止された場合、まだ利用者とやり取りしていないクライアントには、「Interact」メッセージの代わりに「Shutdown Cancelled」メッセージが届くことになる。

  セッション・マネージャから「Interact」メッセージが届くと、コールバック SmcInteractProc が呼び出される。

  利用者とのやり取り(「Interact」メッセージを受けた)の後には、SmcInteractDone を呼び出すものとする。

  引数 cancel_shutdown に True を入れて良いのは、元になった「Save Yourself」において shutdown が True に、interact_style が SmInteractStyleErrors もしくは SmInteractStyleAny に設定されていた場合に限られる。

  セッション・マネージャに拓本を採るよう(checkpoint)要請するには、SmcRequestSaveYourself を用いる。

  引数 save_type、shutdown、interact_style、及び fast に関しては、 The save_type, shutdown,第五章一の一、「Save Yourself に応じるコールバック」 でより詳しく述べてある。

  global が True に設定されている場合、結果として生じる「Save Yourself」はセッション中の全てのクライアントに送信される。例えば、無停電電源(Uninterruptible Power Supply、UPS)の開発者は、UPS の状態を監視するセッション・マネジメント・クライアントを提供し、電源が落ちそうな時に素早く終了処理を提起できるであろう。

  global が False であれば、「Save Yourself」は、これを要求したクライアントにしか送信しないものとする。

  「Save Yourself」を受け取ったクライアントは、自分以外の全クライアントの状態情報を保存するため、それらが静遊状態(quiescent)となった時に通知してもらえるよう要請することができる。そのためには、SmcRequestSaveYourselfPhase2 を用いる。

  SmcRequestSaveYourselfPhase2 の戻り値は、失敗すれば 0、成功すれば正の値である。

  この要求関数を使用するのは、他のクライアント群を管理するクライアントである(例えば、ウィンドウ・マネージャ、ワークスペース・マネージャなど)。マネージャ(管理者)は、管理対象クライアント全てが遊転状態(idle state)となり、それらの状態情報が保存可能になったことを確かめなければならない。

  「Save Yourself」メッセージを受けて状態情報を保存した後には、SmcSaveYourselfDone を呼び出すものとする。

  クライアントは、セッション・マネージャへの登録の後、SmcSaveYourselfDone を呼び出す前に、各必須プロパティ(required property)を少なくとも一回設定していなければならない。

  SmcProtocolVersion は、引数のセッションで運用されているセッション・マネジメント・プロトコルの主たる版番号(major version)を返す。

  SmcProtocolRevision は、引数のセッションで運用されているセッション・マネジメント・プロトコルの従たる版番号(minor version)を返す。

  SmcVendor は、セッション・マネージャの開発者(owner)を表す何らかの識別文字列を返す。この文字列は free を呼び出して解放するものとする。

  SmcRelease は、セッション・マネージャの版番号(release number)を表す文字列を返す。この文字列は free で解放するものとする。

   SmcClientID は、引数の接続オブジェクトのクライアント ID を表す、null 文字終端の文字列を返す。この情報は SmcOpenConnection でも取得できる(利便性を考えて ID 取得専用の関数も用意した)。取得したクライアント ID が不用になれば、そのポインタに対して free を適用する。

  SmcGetIceConnection は、引数のセッション・マネジメント接続オブジェクトが内部に保持する ICE 接続オブジェクトを返す。ICE 接続オブジェクトを用いて、接続に関する詳しい情報を得ることができる。IceConn を付して呼び出せる有用な関数を挙げれば、IceConnectionNumber、IceConnectionString、IceLastSentSequenceNumber、IceLastReceivedSequenceNumber 及び IcePing がある。詳細は規格文書「Inter-Client Exchange Library」を参照。

  セッション・マネージャからクライアントへ予期せぬプロトコル・エラーが届けられた場合、SMlib はエラー・ハンドラ(エラー処理器)を呼び出す。標準のエラー・ハンドラが始めから用意されている。このハンドラは、単にエラー・メッセージを stderr に表示し、エラーの重症度(severity)が致命的(fatal)であれば、終了処理に飛ぶ(exit)。クライアントは、関数 SmcSetErrorHandler を呼び出すことで、このエラー・ハンドラを変更することができる。

  SmcSetErrorHandler の戻り値は、これまで使用していたエラー・ハンドラである。

  SmcErrorHandler の関数型は次の通り。

  このエラー・ハンドラは、プロトコルに関係したエラーを処理するものであることに注意する。入出力エラーに対応するエラー・ハンドラを設定するには、IceSetIOErrorHandler を用いる。詳しくは規格文書「Inter-Client Exchange Library」を見よ。

  SmsInitialize は、セッション・マネージャが最初に呼び出す SMlib 関数である。この関数を通じて、セッション・マネージャの情報を設定し、さらに、新たなクライアントがセッション・マネージャへの接続を試みる度に呼び出されるコールバックを登録する。

  関数 SmsInitialize を呼び出した後、セッション・マネージャは、新たな接続を待ち受けるため、関数 IceListenForConnections を呼び出す。以降、クライアントが接続を試みる度に、セッション・マネージャは IceAcceptConnection を呼び出す。

  認証について詳しく知りたければ、第九章、「クライアントの認証」」を見よ(ホスト名に基づく認証(host based authentication)も含む)。また、ICE 接続の申請の待受けと受理については、規格文書「Inter-Client Exchange Library」を見る。

  新たなクライアントがセッション・マネージャへの接続を試みる度に、コールバック SmsNewClientProc が呼び出される。セッション・マネージャは新しい不透明な接続オブジェクトを得て、以後のクライアントとのやり取りで常にこれを使用する(訳註：libSM-1.2.1/src/sm_manager.c の中の関数 _SmsProtocolSetupProc において、SmsNewClientProc 型のコールバックを呼び出す直前に、構造体 SmsConn 型の接続オブジェクトの変数を宣言し、領域を確保し、同接続オブジェクトのメンバの設定をしている。)。この時に、セッション・マネージャは、クライアントから送られて来るであろう種々のメッセージに応じるためのコールバック群を登録しなければならない。

  SmsNewClientProc が失敗した時は、実値 0 の Status を返し、失敗の理由を表す文字列を failure_reason_ret に割り当てるものとする。この記憶領域を解放するのは SMlib の仕事である。

  セッション・マネージャは、クライアントが発するイベントに応答する際に用いるコールバックの一群を登録しなければならない。引数 mask_ret は、コールバックの中の何れと何れが設定されたのかを表す。この版(SMlibの)で名前が出ているコールバックは全て必須である。引数 mask_ret は、同ライブラリの将来の版において後方互換性を保つために必要なものである。

  mask の値を作るには、下記の値を組み合わせ、論理和をとる。

  セッション・マネージャは、各コールバックに対して、そのコールバック専用のマネージャ・データへのポインタを登録することができる。このポインタは、SMlib によってコールバックが呼び出される時、引数として渡される。

typedef struct {
	struct {
		SmsRegisterClientProc callback;
		SmPointer manager_data;
	} register_client;

	struct {
		SmsInteractRequestProc callback;
		SmPointer manager_data;
	} interact_request;

	struct {
		SmsInteractDoneProc callback;
		SmPointer manager_data;
	} interact_done;

	struct {
		SmsSaveYourselfRequestProc callback;
		SmPointer manager_data;
	} save_yourself_request;

	struct {
		SmsSaveYourselfPhase2RequestProc callback;
		SmPointer manager_data;
	} save_yourself_phase2_request;

	struct {
		SmsSaveYourselfDoneProc callback;
		SmPointer manager_data;
	} save_yourself_done;

	struct {
		SmsCloseConnectionProc callback;
		SmPointer manager_data;
	} close_connection;

	struct {
		SmsSetPropertiesProc callback;
		SmPointer manager_data;
	} set_properties;

	struct {
		SmsDeletePropertiesProc callback;
		SmPointer manager_data;
	} delete_properties;

	struct {
		SmsGetPropertiesProc callback;
		SmPointer manager_data;
	} get_properties;

} SmsCallbacks;

  コールバック SmsRegisterClientProc を受けて、クライアントを登録するには、SmsRegisterClientReply を用いる。

  SmsRegisterClientReply の戻り値は、失敗すれば 0、成功すれば正の値である。失敗となるのは、SMlib が、クライアント ID の複製を保持するための領域を確保できなかった時である。この複製は、SMlib の内部の用途に充てる。

  クライアントが自身の登録を試みた時に、NULL ではない previous_id を指定した場合、client_id をその previous_id と一致させるものとする。

  さもなければ、client_id には、セッション・マネージャが新たに生成した唯一無二のクライアント ID を容れる。加えて、セッション・マネージャは、クライアントの登録後直ちに type = Local、shutdown = False、interact-style = None、及び fast = False とした「Save Yourself」メッセージを送信する。

  一度クライアントにクライアント ID が割り当てられると、同クライアントはその ID を恒久的に使い続けるということに注意する。クライアントが一旦終了した後に再起動した場合、再び同じ ID が割り当てられる。クライアント ID が、計算機から計算機へ、利用者から利用者へ、セッション・マネージャからセッション・マネージャへ、クライアントの同一性を保ちながら流通していくのが望ましい。これと、クライアント ID の永続性とを合わせると、クライアント ID は地球上で(globally)唯一無二である必要がある、ということになる。(訳註：？？？)

  地球上で(globally)唯一無二のクライアント ID を生成するには、関数 SmsGenerateClientID を呼び出す。(訳註：???)

  ID を生成できなかった場合、戻り値は NULL である。さもなければ、クライアント ID が関数の戻り値となる。このクライアント ID は、用が済んだ時は free で解放するものとする。

  「Save Yourself」をクライアントに送信するには、SmsSaveYourself を用いる。

  セッション・マネージャは、クライアントの拓本を採るため(checkpoint it)、あるいは終了処理の直前に、クライアントに「Save Yourself」メッセージを送信する。これによって、クライアントは自身の状態情報を保存できるようになる。クライアントは、0 個以上の「Set Properties」メッセージで応じ、クライアントの再起動方法を記すプロパティ群を更新する。全てのプロパティを設定し終えたら、クライアントは「Save Yourself Done」メッセージを送信する。

  interact_style が SmInteractStyleNone であれば、クライアントは、状態保存の最中に利用者とやり取りしてはならない。interact_style が SmInteractStyleErrors であれば、クライアントは異状が発生した時に限って利用者とやり取りすることができる。interact_style が SmInteractStyleAny の場合、クライアントは、目的を問わず自由に利用者とやり取りして良い。クライアントは、利用者とのやり取りに先立って、「Interact Request」メッセージを送信し、且つセッション・マネージャから「Interact」メッセージが送られてくるのを待たなければならない。クライアントは、利用者とのやり取りを終えたところで、「Interact Done」メッセージを送信するものとする。「Interact Request」メッセージは、「Save Yourself」の後、且つ「Save Yourself Done」の前であれば、何時送信してもよい。

  引数 save_type が SmSaveLocal であれば、クライアントは、その時点での自身の状態を映すようにプロパティ群を更新しなければならない。踏み込んで云えば、クライアントは、同クライアントの利用者から見える状態を復元するのに十分な情報を保存するべきであり、他の利用者から見える状態に影響を与えるべきではない。save_type が SmSaveGlobal であれば、利用者は、クライアントがその全てのデータを恒久的、且つ広域に利用可能な記録装置に保存することを望んでいるということである。save_type が SmSaveBoth であれば、クライアントは上記の作業の両方を行うものとする(クライアントは先ず恒久的記録装置にデータを保存し、その後に自身のプロパティ群を更新する)。

  引数 shutdown は、システムが終了作業中であるか否かを表す。この引数の値の真偽によって、利用者とのやり取りの形に異同がある。終了作業中でなければ、クライアントは保存作業を行なって、通常の処理を再開することができる。終了作業中であれば、クライアントは自身の状態を保存した後、「Die」メッセージもしくは「Shutdown Cancelled」メッセージが同者に届くまで、利用者とのやり取りを差し控えなければならない。これは、保存作業後に利用者が行ったものは全て失われてしまうからである。

  引数 fast は、クライアントができる限り速く状態保存を行うべきか否かを表す。例えば、電源が落ちそうであるとセッション・マネージャに知れた時、同セッション・マネージャは fast を True に設定する。

  クライアントに「Save Yourself Phase 2」メッセージを送信するには、SmsSaveYourselfPhase2 を用いる。

  セッション・マネージャは、前もって「Save Yourself Phase 2 Request」メッセージを送ってきていたクライアントに対して、当メッセージを送信する。このメッセージを受け取ったクライアントは次の事実を知る。即ち、同者以外の全てのクライアントの状態が定まり、これらのクライアントと結び付いた自身の状態情報を保存できるようになったことを知る。

  クライアントに「Interact」メッセージを送信するには、SmsInteract を用いる。

  「Interact」メッセージを受信したクライアントは、利用者とのやり取りを独占することができる。クライアントは、利用者とのやり取りを終えた時、セッション・マネージャに対して「Interact Done」メッセージを送信しなければならない。

  クライアントに「Save Complete」メッセージを送信するには、SmsSaveComplete を用いる。

  セッション・マネージャは、チェックポイント処理(checkpoint、セッションの状態を保存する処理)を終えた時、このメッセージを送信する。これ以後、クライアントは自由に状態を変更することができるようになる。

  クライアントに「Die」メッセージを送信するには、SmsDie を用いる。

  セッション・マネージャは、終了する前に、自身が「Die」メッセージを送ったクライアントのそれぞれから、「Connection Closed」メッセージが戻って来るのを待ち受けるものとする。その際、所定の時間が過ぎれば自動的に終了する。

  終了処理(shutdown)を中止するには、SmsShutdownCancelled を用いる。

  当関数の呼出し以後、クライアントはまるで終了作業が存在しなかったかのように処理を続けることができる。クライアントは、まだ「Save Yourself Done」メッセージを送信していないのであれば、保存作業を中止した上で、引数 success に False を付して「Save Yourself Done」を送信してもよいし、あるいは、保存作業を続行し、その結果を引数 success に反映させて「Save Yourself Done」を送信してもよい。

  「Get Properties」メッセージを受けて、セッション・マネージャは SmsReturnProperties を呼び出す。

  プロパティ群の引き渡しには、プロパティを指すポインタの配列を用いる。セッション・マネジメント・プロパティと構造体 SmProp については、第七章、「セッション・マネジメント・プロパティ」で説明する。

  クライアントが依然として健在か否かを調べるには、ICE ライブラリに備わっている関数 IcePing を用いる。そのためには、SmsGetIceConnection を用いて、ICE 接続を取得しなければならない(第六章十二節、「Sms の情報取得関数を使う」を見よ)。

  PING に対する返信が用意できた時は(もし返信が存在すれば)、コールバック IcePingReplyProc が呼び出される。セッション・マネージャは、ある種の待受け期限を備えるものとし、その期限を過ぎれば、同者はクライアントが予期せず終了したものと見做す。

  セッション・マネージャに「Connection Closed」メッセージが届いた時、あるいは、他の方法を通じてクライアントの接続切断を検知した時、同セッション・マネージャは接続オブジェクトを解放するために関数 SmsCleanUp を呼び出すものとする。

  SmsProtocolVersion は、引数のセッションで運用されているセッション・マネジメント・プロトコルの主たる版番号(major version)を返す。

  SmsProtocolRevision は、引数のセッションで運用されているセッション・マネジメント・プロトコルの従たる版番号(minor version)を返す。

  SmsClientID は、引数の接続オブジェクトのクライアント ID を表す、null 文字終端の文字列を返す。クライアント ID が用済みになった時は、そのポインタに対して free を呼び出すものとする。

  クライアントのホスト名(host name)を取得するには、SmsClientHostName を用いる。このホスト名はクライアントの再起動に必要となる。

  取得した文字列は、「protocol/hostname」の書式から成る。この中の「protocol 」部分には、{tcp, decnet, local} の何れか一つが入る。取得した文字列が用済みになった時は、同文字列に対して free を呼び出すものとする。

  SmsGetIceConnection は、引数のセッション・マネジメント接続オブジェクトが内部に保持する ICE 接続オブジェクトを返す。ICE 接続オブジェクトを用いて、接続に関する詳しい情報を得ることができる。IceConn を引数にして呼び出せる有用な関数を挙げれば、IceConnectionNumber と IceLastSequenceNumber がある。詳細は規格文書「Inter-Client Exchange Library」を参照。

  クライアントからセッション・マネージャへ予期せぬプロトコル・エラーが届けられた場合、SMlib はエラー・ハンドラ(エラー処理器)を呼び出す。標準のエラー・ハンドラが始めから用意されている。このハンドラは、単にエラー・メッセージを表示するだけである(終了 exit しない)。セッション・マネージャは、関数 SmsSetErrorHandler を呼び出すことで、このエラー・ハンドラを変更することができる。

  SmsSetErrorHandler の戻り値は、これまで使用していたエラー・ハンドラである。SmsErrorHandler の関数型は次の通り。

  このエラー・ハンドラは、プロトコルに関係したエラーを処理するものであることに注意する。入出力エラーに対応するエラー・ハンドラを設定するには、IceSetIOErrorHandler を用いる。詳しくは規格文書「Inter-Client Exchange Library」を見よ。