Net秘書君仕様書 ver 0.40

最初に

概要

プロシージャ一覧

プロシージャ一覧
名称プロシージャ名概要引数返り値
セッション作成Session_Createバージョンや使用できるプロシージャ等の確認セッションID、クライアントの情報サーバの情報
認証Session_Certificationサーバにアクセスする権限を認証するユーザー名、パスワードなど認証結果
ファイル選択Session_SelectFileアクセスするファイルを選択し、アクセス権を認証するファイル名、ユーザー名、パスワードな認証結果
データ確認Data_Verifyサーバにあるデータが更新されているかどうか確認クライアントの持つデータの世代、IDなど更新されていればその内容・ファイルが削除されていればその旨
データ更新Data_Modifyサーバにあるデータを更新する新しいデータ更新結果(個々のデータについて成功/失敗)
ファイル選択Session_Closeセッションを終了するなしなし
ファイル一覧取得File_GetFilenamesサーバに存在する利用できるファイルの一覧を返すなしファイル名一覧
ファイル追加File_Addサーバにデータファイルを追加する追加するデータファイルの名前、アクセス権データ追加できたかどうか
ファイル属性変更File_Configサーバのデータファイルの属性を変更する属性を変更するデータファイルの名前、アクセス権データ変更できたかどうか
ファイル削除File_Deleteサーバのデータファイルを一つ削除する削除するデータファイルの名前削除できたかどうか
終了Server_Quitサーバを終了させるなし終了できればOK
設定確認Server_GetSettingサーバの設定を取得するなし設定内容
コンフィグServer_Configサーバの設定を変更する変更する項目名とその内容設定された値と、変更できたかどうか

サーバの「未認証」、「認証済み」、「ファイル選択済み」状態を1,2,3とすると、 以下の状態のときにのみプロシージャを受け付ける。
受付不可能な通信が来た場合には状態エラーを返す。

受け入れ可能コマンド一覧
名称プロシージャ名状態
未認証認証済みファイル選択済み
セッション作成Session_Create ---
認証Session_Certification
ファイル選択Session_SelectFile ×
データ確認Data_Verify ××
データ更新Data_Modify ××
セッション終了Session_Close
ファイル一覧取得File_GetFilenames ×
ファイル追加File_Add ×
ファイル属性変更File_Config ×
ファイル削除File_Delete ×
サーバ終了Server_Quit ×
サーバ設定取得Server_GetSetting ×
コンフィグServer_Config ×

注意事項

各プロシージャコール/プロシージャ返答に先立ってXML宣言
<?xml version="1.0" encoding="Shift-JIS"?>
が送られる。
省略可?

フレームワーク

各プロシージャの呼び出しは以下のフレームワークにのっとって行われる。

プロシージャコール
<methodcall>
 <methodname>プロシージャ名</methodname>
 <sessionid>セッションID</sessionid>
 <data>引数群</data>
 </methodcall>

プロシージャ成功返答
<methodresponse>
 <sessionid>セッションID</sessionid>
 <result result =Success">帰り値群</result>
 </methodresponse>

プロシージャ失敗返答
<methodresponse>
 <sessionid>セッションID</sessionid>
 <result result =Failure">帰り値群</result>
 </methodresponse>

プロシージャ致命的失敗返答
<methodresponse>
 <sessionid>セッションID</sessionid>
 <fault>
  <num>エラー番号</num>
  <type>エラー種別</type>
  <description>エラー詳細<description>
  </fault>
 </methodresponse>

プロシージャ説明

セッション作成 Session_Create

概要

セッションを作成、開始します。
サーバはセッションIDを記録し、自らの情報を帰り値にして返します。
この関数は呼び出された時点で新たなセッションに属するため、常に未認証状態で実行されます。

引数

・クライアントの名称 ・クライアントのバージョン

帰り値

・サーバの名称 ・サーバのバージョン ・サーバの受け入れ可能な認証方式

詳細

呼び出し例

<methodcall>
 <methodname>Session_Create</methodname>
 <sessionid>SessionUID</sessionid>
 <data>
  <appname>秘書君2</appname>
  <version major="1" minor = "0" revision = "0" />
  </data>
 </methodcall>
応答例

<methodresult>
 <sessionid>SessionUID</sessionid>
 <result result =Success">
  <appname>hisyo-server</appname>
  <version major="1" minor = "0" revision = "0" />
  <enablecertification>
   <type name = "Plain" />
   <type name = "IP" />
   <type name = "MD5" >
   <challenge>CHALLENGE_STRING</challenge>
    </type>
   </enablecertification>
  </result>
 </methodresult>

認証 Session_Certification

概要

サーバに対して認証を行います。
サーバは状態にかかわらずこの関数が呼び出されるたびに認証をおこないます。
認証に成功した場合、前状態にかかわらず「認証済み」状態に遷移し、認証成功を返します。
認証に失敗した場合、前状態にかかわらず「未認証」状態に遷移し、認証失敗を返します。

引数

・認証情報

帰り値

・認証結果

詳細

呼び出し例

<methodcall>
 <methodname>Session_Certification</methodname>
 <sessionid>SessionUID</sessionid>
 <data>
  <type name = "Plain">
   <name>Annonymous</name>
   <password>Pass</password>
   </type>
  </data>
 </methodcall>

そのほか

 <data>
  <type name = "IP" />
  </data>



 <data>
  <type name = "MD5">
   <response>RESPONSE_STRING</response>
   </type>
  </data>

など
応答例

認証成功

<methodresult>
 <sessionid>SessionUID</sessionid>
 <result result =Success">
  <competence>User</competence>
  </result>
 </methodresult>

認証失敗

 <result result =Failure">
  <description>invalid user or password</description>
  </result>

ファイル選択 Session_SelectFile

概要

参照するデータファイルを指定し、認証を行います。
サーバは「認証済み」/「ファイル選択済み」状態であればこの関数が呼び出されるたびに認証とファイルの選択を行います。
認証で成功すればデータファイルを選択し、「ファイル選択済み」状態に遷移し、ファイル選択成功を返します。
認証が失敗した場合はファイル選択を解除し、「認証済み」状態に遷移し、ファイル選択失敗を返します。
サーバが「未認証」状態であった場合は状態エラーを返し、「未認証」状態を維持します。

引数

・ファイル名 ・認証情報

帰り値

・ファイル選択のの成功/失敗

詳細

呼び出し例

<methodcall>
 <methodname>Session_SelectFile</methodname>
 <sessionid>SessionUID</sessionid>
 <data>
  <type name = "Plain">
   <name>Annonymous</name>
   <pass>Pass</pass>
   </type>
  <file name = "FILENAME.EXTENTION" />
  </data>
 </methodcall>
応答例

認証成功

<methodresult>
 <sessionid>SessionUID</sessionid>
 <result result =Success">
  <competence>Write</competence>
  </result>
 </methodresult>

認証失敗

 <result result =Failure">
  <description>invalid user or password</description>
  </result>

状態異常

 <fault>
  <num>101</num>
  <type>invalid state</type>
  <description>Session_Selecfile was called in invalid state<description>
  </fault>

データ確認 Data_Verify

概要

クライアントから渡されたトランザクション番号に応じてサーバのデータから更新分を抽出し、返します。
「ファイル選択済み」状態以外ではこのプロシージャは必ず失敗します。

引数

・更新を確認するクライアントの知る最新のトランザクション番号 ・更新を確認するトランザクション番号に対応するトランザクションUID

帰り値

・更新されたデータ または データ矛盾が起きたこと

詳細

更新分抽出にあたり、クライアントから渡されたトランザクション番号とトランザクションUIDがサーバに保管されているものと整合性が取れているかを確認します。 整合性が取れていない場合はデータファイルが再作成されたものと判断してその旨をクライアントに通知します。

呼び出し例

<methodcall>
 <methodname>Data_Verify</methodname>
 <sessionid>SessionUID</sessionid>
 <data>
  <latesttransaction age = "ClientLatestTransactionAge" uid = "ClientLatestTransactionUID" />
  </data>
 </methodcall>
応答例

<methodresult>
 <sessionid>SessionUID</sessionid>
 <result result =Success">
  <transactions fromage = "ClientLatestTransactionAge" age = "ServerLatestTransactionAge" uid = "ServerLatestTransactionUID">
   <unit uid="UnitUID1"..>...</unit>
   ...
   </transactions>
  </result>
 </methodresult>

ClientLatestTransactionAge < ServerLatestTransactionAge または ServerSavedUID(ClientLatestTransactionAge) <> ClientLatestTransacionUIDであった場合

<methodresult>
 <sessionid>SessionUID</sessionid>
 <result result =Failure">
  <reason>Disagreement Occurred</reason>
  </result>
 </methodresult>

状態異常

 <fault>
  <num>101</num>
  <type>invalid state</type>
  <description>Data_Veirfy was called in invalid state<description>
  </fault>

権限不足

 <fault>
  <num>200</num>
  <type>invalid competence</type>
  <description>Data_Veirfy was called with invalid competence<description>
  </fault>

データ更新 Data_Modify

概要

クライアントからデータの更新分を送信します。
サーバはクライアントから与えられたデータを元にサーバのデータを更新し、更新結果を返します。 「ファイル選択済み」状態以外ではこのプロシージャは必ず失敗します。

引数

・クライアントの名称 ・クライアントのバージョン

帰り値

・サーバの名称 ・サーバのバージョン ・サーバの受け入れ可能な認証方式

詳細

サーバはトランザクション番号とトランザクションUIDからデータの整合性をチェックします。
整合性が取れていない場合はデータファイルが再作成されたものと判断してその旨をクライアントに通知し、送られてきたデータすべてについてAbortを返します。
整合性が取れていた場合はトランザクション番号が現在のサーバのトランザクション番号と一致しているかどうかを確認します。
一致していなかった場合はData_Verifyコマンドを受け取ったときと同様のtransacionsタグも返します。
最後に、与えられたデータとトランザクションUIDから新しいトランザクションを作成し、データを反映します。
データを反映するにあたり、クライアントから与えられたクライアントの持つ最新のトランザクション番号からサーバの持つトランザクション番号までの間に、クライアントより与えられたデータと同じUIDを持つデータが変更/削除されて居ないかを確認します。 変更/削除されていた場合はそのデータについてAbortを返します。
変更されていなければデータを更新し、そのデータについてCommitを返します。

呼び出し例

<methodcall>
 <methodname>Data_Modify</methodname>
 <sessionid>SessionUID</sessionid>
 <data>
  <latesttransaction age = "ClientLatestTransactionAge" uid = "ClientLatestTransactionUID"/>
  <newtransaction uid = "NewUID">
   <unit uid="UnitUID1"..>...</unit>
   <unit uid="UnitUID2"..>...</unit>
   ...
   </newtransaction>
  </data>
 </methodcall>
応答例


ClientLatestTransactionAge = ServerLatestTransactionAgeであった場合

<methodresult>
 <sessionid>SessionUID</sessionid>
 <result result =Success">
  <transaction age = "NewAge" uid = "NewUID">
   <unitaryresult uid="UnitUID1" action="Committed" />
   <unitaryresult uid="UnitUID2" action="Aborted" />
   ...
   </transaction>
  </result>
 </methodresult>

ClientLatestTransactionAge < ServerLatestTransactionAgeであった場合

<methodresult>
 <sessionid>SessionUID</sessionid>
 <result result =Success">
  <transactions fromage = "ClientLatestTransactionAge" age = "ServerLatestTransactionAge" uid = "ServerLatestTransactionUID">
   <unit uid="UnitUIDA"..>...</unit>
   ...
   </transactions>
  <transaction age = "NewAge" uid = "NewUID">
   <unitaryresult uid="UnitUID1" action="Committed" />
   <unitaryresult uid="UnitUID2" action="Aborted" />
   ...
   </transaction>
  </result>
 </methodresult>
注意) NewAge == ServerLatestTransactionAge + 1
プロシージャ返答後にサーバはServerLatestTransactionAge = NewAgeとする。

ClientLatestTransactionAge > ServerLatestTransactionAge または ServerSavedUID(ClientLatestTransactionAge) <> ClientLatestTransacionUIDであった場合

<methodresult>
 <sessionid>SessionUID</sessionid>
 <result result =Failure">
  <reason>Disagreement Occurred</reason>
  </result>
 </methodresult>

状態異常

 <fault>
  <num>101</num>
  <type>invalid state</type>
  <description>Data_Modify was called in invalid state<description>
  </fault>

権限不足

 <fault>
  <num>200</num>
  <type>invalid state</type>
  <description>Data_Modify was called with invalid competence<description>
  </fault>

セッション終了 Session_Close

概要

このプロシージャがコールされた場合、状態にかかわらずセッションを終了します。
サーバは応答後にセッションIDに関連付けられていたコンテキストやスレッド、ソケット等を開放します。

引数

・なし

帰り値

・なし

詳細

呼び出し例

<methodcall>
 <methodname>Session_Close</methodname>
 <sessionid>SessionUID</sessionid>
 </methodcall>
応答例

<methodresult>
 <sessionid>SessionUID</sessionid>
 <result result = "Success">
 </methodresult>

ファイル一覧取得 File_GetFilenames

概要

サーバに登録されているファイル名の一覧を作成し、返します。
「未認証」状態で呼び出された場合はこの関数は必ず失敗します。

引数

帰り値

・ファイル名一覧

詳細

呼び出し例

<methodcall>
 <methodname>File_GetFilenames</methodname>
 <sessionid>SessionUID</sessionid>
 </methodcall>
応答例

<methodresult>
 <sessionid>SessionUID</sessionid>
 <result = "Success">
  <file name = "FILENAME1.EXTENTION1" >
  <readwrite>Administrator</readwrite>
  <readwrite>Annonymous</readwrite>
   </file>
  <file name = "FILENAME2.EXTENTION2" >
  <readwrite>Administrator</readwrite>
  <readonly>Annonymous</readonly>
   </file>
  ...
  </result>
 </methodresult>

状態異常

 <fault>
  <num>101</num>
  <type>invalid state</type>
  <description>File_GetFilenames was called in invalid state<description>
  </fault>

ファイル追加 File_Add

概要

サーバにデータファイルを追加します。
「未認証」状態で呼び出された場合はこの関数は必ず失敗します。
この関数の実行にはAdministrator権限が必要です。

引数

・追加するファイルの情報

帰り値

・成功/失敗

詳細

サーバは追加されたファイルの情報を返します。 ファイル追加に失敗した場合は fileエレメントのstatus アトリビュートにNot existを指定して返します。

呼び出し例

<methodcall>
 <methodname>File_Add</methodname>
 <sessionid>SessionUID</sessionid>
 <data>
  <file name = "FILENAME1.EXTENTION1" >
  <readwrite>Administrator</readwrite>
  <readonly>Annonymous</readonly>
   </file>
  <file name = "FILENAME2.EXTENTION2" >
  <readwrite>Administrator</readwrite>
  <readonly>Annonymous</readonly>
   </file>
  </data>
 </methodcall>
応答例

<methodresult>
 <sessionid>SessionUID</sessionid>
 <result result =Success" />
  <file name = "FILENAME1.EXTENTION1" >
  <readwrite>Administrator</readwrite>
  <readonly>Annonymous</readonly>
   </file>
  <file name = "FILENAME2.EXTENTION2" status = "Not exist" />
 </methodresult>

状態異常

 <fault>
  <num>101</num>
  <type>invalid state</type>
  <description>File_Add was called in invalid state<description>
  </fault>

権限不足

 <fault>
  <num>200</num>
  <type>invalid state</type>
  <description>File_Add was called with invalid competence<description>
  </fault>

ファイル属性変更 File_Config

概要

サーバのデータファイルの属性を変更します。
「未認証」状態で呼び出された場合はこの関数は必ず失敗します。
この関数の実行にはAdministrator権限が必要です。

引数

・属性を変更するファイルの情報

帰り値

・成功/失敗

詳細

ファイルの属性情報を返します。
ファイルが存在しなかった場合はfileエレメントのstatusアトリビュートに"Not exist"を指定して返します。

呼び出し例

<methodcall>
 <methodname>File_Config</methodname>
 <sessionid>SessionUID</sessionid>
 <data>
  <file name = "FILENAME1.EXTENTION1" >
  <readwrite>Administrator</readwrite>
  <readonly>Annonymous</readonly>
   </file>
  <file name = "FILENAME2.EXTENTION2" >
  <readwrite>Administrator</readwrite>
  <readonly>Annonymous</readonly>
   </file>
  </data>
 </methodcall>
応答例

<methodresult>
 <sessionid>SessionUID</sessionid>
 <result result =Success" />
  <file name = "FILENAME1.EXTENTION1" >
  <readwrite>Administrator</readwrite>
  <readonly>Annonymous</readonly>
   </file>
  <file name = "FILENAME2.EXTENTION2" status = "Not exist" />
 </methodresult>

状態異常

 <fault>
  <num>101</num>
  <type>invalid state</type>
  <description>File_Config was called in invalid state<description>
  </fault>

権限不足

 <fault>
  <num>200</num>
  <type>invalid state</type>
  <description>File_Config was called with invalid competence<description>
  </fault>

ファイル削除 File_Delete

概要

サーバのデータファイルを削除します。
「未認証」状態で呼び出された場合はこの関数は必ず失敗します。
この関数の実行にはAdministrator権限が必要です。

引数

・削除するファイルの情報

帰り値

・成功/失敗

詳細

呼び出し例

<methodcall>
 <methodname>File_Delete</methodname>
 <sessionid>SessionUID</sessionid>
 <data>
  <file name = "FILENAME.EXTENTION" />
  </data>
 </methodcall>
応答例

<methodresult>
 <sessionid>SessionUID</sessionid>
 <result result =Success" />
 </methodresult>

状態異常

 <fault>
  <num>101</num>
  <type>invalid state</type>
  <description>File_Delete was called in invalid state<description>
  </fault>

権限不足

 <fault>
  <num>200</num>
  <type>invalid state</type>
  <description>File_Delete was called with invalid competence<description>
  </fault>

サーバ終了 Server_Quit

概要

サーバを終了させます。 「未認証」状態で呼び出された場合はこの関数は必ず失敗します。
この関数の実行にはAdministrator権限が必要です。

引数

・即時終了/適時終了

帰り値

・成功/失敗

詳細

即時終了(mode Now)は現在処理中の動作があっても中断し、終了します。
適時終了(mode Graceful)は現在処理中の動作がすべて終わってから終了します。

呼び出し例

<methodcall>
 <methodname>Server_Quit</methodname>
 <sessionid>SessionUID</sessionid>
 <data>
  <mode>Graceful</mode>
  </data>
 </methodcall>
応答例

<methodresult>
 <sessionid>SessionUID</sessionid>
 <result result =Success" />
 </methodresult>

状態異常

 <fault>
  <num>101</num>
  <type>invalid state</type>
  <description>Server_Quit was called in invalid state<description>
  </fault>

権限不足

 <fault>
  <num>200</num>
  <type>invalid state</type>
  <description>Server_Quit was called with invalid competence<description>
  </fault>

サーバ設定取得 Server_GetSetting

概要

サーバの設定を取得します。 「未認証」状態で呼び出された場合はこの関数は必ず失敗します。
この関数は将来の拡張用です。

引数

なし

帰り値

・成功/失敗

詳細

即時終了(mode Now)は現在処理中の動作があっても中断し、終了します。
適時終了(mode Graceful)は現在処理中の動作がすべて終わってから終了します。

呼び出し例

<methodcall>
 <methodname>Server_Quit</methodname>
 <sessionid>SessionUID</sessionid>
 <data>
  <params>
   <param name = "PARAM1" >
    <value>VALUE1</value>
    </param>
   <param name = "PARAM2" >
    <value>VALUE2</value>
    </param>
   </params>
  </data>
 </methodcall>
応答例

<methodresult>
 <sessionid>SessionUID</sessionid>
 <result result =Success">
  <params>
   <param>
   <param name = "PARAM1" >
    <value>VALUE1</value>
    <result>Success</result>
    </param>
   <param name = "PARAM2" >
    <value>OLDVALUE2</value>
    <result>Failure</result>
    </param>
   </params>
  </result>
 </methodresult>

状態異常

 <fault>
  <num>101</num>
  <type>invalid state</type>
  <description>Server_Config was called in invalid state<description>
  </fault>

権限不足

 <fault>
  <num>200</num>
  <type>invalid state</type>
  <description>Server_Config was called with invalid competence<description>
  </fault>

コンフィグ Server_Config

概要

サーバの設定を変更させます。 「未認証」状態で呼び出された場合はこの関数は必ず失敗します。
この関数の実行にはAdministrator権限が必要です。
この関数は将来の拡張用です。

引数

サーバへの設定値

帰り値

・設定の成功/失敗

詳細

引数としてサーバへの設定値を持ちます。
サーバは引数に応じて各設定項目の値を再設定します。設定に成功した場合も失敗した場合もパラメータ名と設定値(変更後)を返します。 paramエレメントのメンバ、resultエレメントの内容として設定に失敗した場合はFalseが、成功したときはSuccessが設定されます。
もし設定自体が存在しなかった場合は、paramパラメータのアトリビュートとしてstatus = "Not exist"が指定されます。

呼び出し例

<methodcall>
 <methodname>Server_Quit</methodname>
 <sessionid>SessionUID</sessionid>
 <data>
  <params>
   <param name = "PARAM1" >
    <value>VALUE1</value>
    </param>
   <param name = "PARAM2" >
    <value>VALUE2</value>
    </param>
   <param name = "PARAM3">
    <value>VALUE3</value>
    </param>
   </params>
  </data>
 </methodcall>
応答例

<methodresult>
 <sessionid>SessionUID</sessionid>
 <result result =Success">
  <params>
   <param name = "PARAM1" >
    <value>VALUE1</value>
    <result>Success</result>
    </param>
   <param name = "PARAM2" >
    <value>OLDVALUE2</value>
    <result>Failure</result>
    </param>
   <param name = "PARAM3" satus ="Not exist" />
   </params>
  </result>
 </methodresult>

状態異常

 <fault>
  <num>101</num>
  <type>invalid state</type>
  <description>Server_Config was called in invalid state<description>
  </fault>

権限不足

 <fault>
  <num>200</num>
  <type>invalid state</type>
  <description>Server_Config was called with invalid competence<description>
  </fault>

主要なエレメント

data エレメント

概要

dataエレメントは各プロシージャの引数を持つ。

エレメント

dataエレメントはコンテナであり、多くの種類のエレメントを持ちうる。

アトリビュート

なし

詳細

例:

result エレメント

概要

resultエレメントはプロシージャコールの帰り値を格納するエレメントである

エレメント

resultエレメントはコンテナであり、多くの種類のエレメントを持ちうる。

アトリビュート

  • result(必須)

詳細


resultエレメントはプロシージャが正しくその処理を終了したときに作成され、返される帰り値格納エレメントである。
関数の処理内容が成功/失敗であることにあわせ、resultエレメントにSuccessないしFailureが設定される。

例:

fault エレメント

概要

faultエレメントはプロシージャが想定外のエラーを返したときに帰り値として使用される。

エレメント

  • num(必須)
  • type(必須)
  • desc(必須)

アトリビュート

なし

詳細


faultエレメントは
・各命令が解釈が不可能であった場合
・致命的な不具合が発生した場合場合
・状態異常/権限不足でのプロシージャコール
に送られる。
各コマンドが本来の処理をした上でその処理結果が失敗であった場合は、各コマンドに対してresultをFailureで返すことに注意。

例:


以下に例をあげる。

XML書式エラー(タグが閉じてない、リテラル文字列が閉じてないなど)

 <fault>
  <num>1</num>
  <type>Format Error</type>
  <description>Invalid xml format</description>
  </fault>
トップレベルタグがない

 <fault>
  <num>2</num>
  <type>Format Error</type>
  <description>No toplevel tag</description>
  </fault>
エレメントに必須のアトリビュートがない

 <fault>
  <num>3</num>
  <type>Format Error</type>
  <description>No ***** attribute in ***** tag</description>
  </fault>
想定外のアトリビュート値が指定された

 <fault>
  <num>4</num>
  <type>Format Error</type>
  <description>Invalid value ***** attribute in ***** tag</description>
  </fault>
必須のエレメントが存在しない

 <fault>
  <num>5</num>
  <type>Format Error</type>
  <description>No ***** tag in ***** tag</description>
  </fault>
データ更新に失敗(ファイルIOエラー)

 <fault>
  <num>10</num>
  <type>Server Error</type>
  <description>FileI/O Error</description>
  </fault>
無効なセッションUID

 <fault>
  <num>100</num>
  <type>invalid state</type>
  <description>**** was called with invalid session uid<description>
  </fault>
状態異常

 <fault>
  <num>101</num>
  <type>invalid state</type>
  <description>**** was called in invalid state<description>
  </fault>
権限不足

 <fault>
  <num>200</num>
  <type>invalid state</type>
  <description>**** was called with invalid competence<description>
  </fault>
セッションIDが不正

 <fault>
  <num>1000</num>
  <type>invalid sessionID</type>
  <description>SessionID is invalid<description>
  </fault>

appname エレメント

概要

appnameエレメントはそれを発行したアプリケーションの名称を持つ

エレメント

なし

アトリビュート

なし

詳細

例:


  <appname>hisyo-server</appname>

version エレメント

概要

versionエレメントはこれを発行したアプリケーションのバージョンをもつ。

エレメント

なし

アトリビュート

詳細

例:


  <version major="1" minor = "0" revision = "0" />

enablecertification エレメント

概要

enablecertificationエレメントはサーバが認識できる認証方法の一覧を返す。

エレメント

アトリビュート

なし

詳細


enablecertificationエレメントはサーバがクライアントに対し受け入れ可能な認証方法を返すのに使用される。
このエレメントはSession_Createの帰り値として使われる。

例:


  <enablecertification>
   <type name = "Plain" />
   <type name = "IP" />
   <type name = "MD5" >
   <challenge>CHALLENGE_STRING</challenge>
    </type>
   </enablecertification>

type エレメント

概要

typeエレメントは認証方法を表すのに使用される。

エレメント

typeエレメントが持つエレメントはnameアトリビュートと作成する側(認証する側かされる側か)によって異なる。

アトリビュート

詳細


typeエレメントはサーバとクライアントの間で認証を行う際に、その種別情報およびその種別に特有な情報を入れるのに使用される。

例:

認証方法通知時の例

   <type name = "Plain" />
   <type name = "IP" />
   <type name = "MD5" >
認証時の例

  <type name = "Plain">
   <name>Annonymous</name>
   <password>Pass</password>
   </type>

  <type name = "IP" />

  <type name = "MD5">
   <response>RESPONSE_STRING</response>
   </type>
  </data>

unit エレメント

概要

unitエレメントはデータの一単位を表す

エレメント

アトリビュート

詳細


unitエレメントはこのサーバで扱われるデータの単位を表す。
すべてのunitエレメントはUIDを持ち、UIDはが同じunitは同じデータを指す。
サーバはunitエレメントのUIDエレメントのみを意識し、それ以外のアトリビュートおよびunit以下のエレメントはそのまま保存する。

例:


   <unit uid = "UnitUID" ...>
    ...
    </unit>

latesttransaction エレメント

概要

latesttransactionエレメントはサーバにデータを要求するときに使用される。

エレメント

なし

アトリビュート

詳細


latesttransactionエレメントはクライアントの現在のデータ認識状況をサーバに通知し、その差分を受け取るために発行される。
このエレメントはData_Verifyの引数/Data_Modifyの引数として使われる。

例:


  <latesttransaction age = "ClientLatestTransactionAge" uid = "ClientLatestTransactionUID"/>

transactions エレメント

概要

transactionsエレメントはクライアントに変更されたデータを返すときに使用される。

エレメント

アトリビュート

詳細


transactionsエレメントはクライアントの要求に大してサーバからデータの変更分を返すときに使用される。
transactionsエレメントはそれが含むunitデータが属するトランザクションの範囲を、開始をfromage、最終をageとuidであらわす。
クライアントに返すデータをunitエレメントとして内部に持つ。
このエレメントはData_Verifyの帰り値/Data_Modifyの帰り値として使われる。
latesttransacion引数と対応する帰り値である。

例:


  <transactions fromage = "ClientLatestTransactionAge" age = "ServerLatestTransactionAge" uid = "ServerLatestTransactionUID">
   <unit uid="UnitUID1"..>...</unit>
   ...
   </transactions>

newtransaction エレメント

概要

newtransactionエレメントはクライアントからサーバに更新要求を行うときに使用される。

エレメント

アトリビュート

詳細


newtransactionエレメントはクライアントからサーバにデータの更新を要求するときに使用されるエレメントである。
サーバにてデータの整合性を確認するためのクライアントが認識している最新のトランザクションについての情報と、新たに作成するトランザクションが持つべきUIDがアトリビュートとして指定される。
更新するデータをunitエレメントとして内部に持つ。
このエレメントはData_Modifyの引数として使用される

例:


  <newtransaction latestage = "ClientLatestTransactionAge" latestuid = "ClientLatestTransactionUID" newuid = "NewUID">
   <unit uid="UnitUID1"..>...</unit>
   <unit uid="UnitUID2"..>...</unit>
   ...
   </transaction>

transaction エレメント

概要

transactionエレメントはサーバがデータを更新したとき、クライアントに更新結果を返すのに使用される。

エレメント

アトリビュート

詳細


transactionエレメントはクライアントからの依頼により新たに作成され、コミットされたトランザクションの情報を格納するエレメントである。
transactionエレメントはクライアントからnewtransactionエレメントによって与えられたunitエレメントの一つ一つに対してサーバでそのデータがコミットできたかどうかその結果をunitaryresultエレメントにて返す。
このエレメントはData_Modifyの帰り値として使用される
newtransacion引数と対応する帰り値である。

例:


  <transaction age = "NewAge" uid = "NewUID">
   <unitaryresult uid="UnitUID1" action="Committed" />
   <unitaryresult uid="UnitUID2" action="Aborted" />
   ...
   </transaction>

file エレメント

概要

fileエレメントはファイルの情報を格納する。

エレメント

アトリビュート

詳細


fileエレメントはデータファイルについての情報をやり取りするのに使用されます。
必要な場合にはデータファイルが持つアクセス権限情報をエレメントとして持ちます。
アトリビュートstatusはサーバからの返答にのみ存在しえます。

例:


  <file name = "FILENAME1.EXTENTION1" >
  <readwrite>Administrator</readwrite>
  <readonly>Annonymous</readonly>
   </file>
  <file name = "FILENAME2.EXTENTION2" status = "Not exist" />
   </file>

params エレメント

概要

paramsエレメントはサーバの設定を変更するとき、その設定パラメータを入れるのに、または設定内容をサーバが返すときに使用される。

エレメント

アトリビュート

無し

詳細

例:


  <params>
   <param name = "PARAM1" >
    <value>VALUE1</value>
    </param>
   <param name = "PARAM2" >
    <value>VALUE2</value>
    </param>
   </params>

param エレメント

概要

paramエレメントはサーバの設定を変更するとき、または設定情報を返すとき、その情報を保持するのに使用される。

エレメント

アトリビュート

詳細


paramエレメントはサーバの設定値をもつ。 クライアントから設定を変更しようとするときはvalueエレメントを、サーバからその変更結果があたられるときはvalueのほかresult(設定成功したかどうか)を、サーバから設定内容が返されるときはvalueのみをもつ。
もし存在しないパラメータの設定が指定された場合は、帰り値のparamエレメントは"Not exist"が設定されたstatusアトリビュートを持ち、エレメントを持ちません。

例:


   <param name = "PARAM">
    <value>VALUE</value>
    </param>

   <param name = "PARAM1">
    <value>VALUE1</value>
    <result>Success</result>
    </param>

   <param name = "PARAM2">
    <value>OLDVALUE2</value>
    <result>Failure</result>
    </param>

   <param name = "PARAM3" status = "Not exist" />

サーバー

概要

サーバはユーザー管理、データファイル管理、データ管理を行う。
データ管理については、単位データ(unit)に関連付けられたUIDと、1データ更新ごとに付けられるトランザクション情報(番号とUID)を元にデータを管理する。
単位データの中身には頓着しない

各プロシージャの動作

セッション作成 (Session_Create)

サーバはセッションを管理するコンテキスト他リソースを用意し、与えられたSesionIDに関連づける。
また、自らの情報と利用可能な認証方法を返す。
処理途中で致命的なエラーが発生した場合はfaultエレメントを持つ帰り値を返す。
致命的エラーの処理については以下同じ。

認証 (Session_Certification)

サーバはサーバに登録されたユーザー情報と認証メカニズムを用いて、与えられた認証情報を認証する。
認証結果を返す。

ファイル選択 (Session_SelectFile)

サーバはサーバに登録されたファイルアクセス権情報と認証メカニズムを用いて、与えられた認証情報を認証する。
認証結果を返す。

データ確認 (Data_Verify)

サーバはData_Verifyプロシージャがコールされた場合、その引数に含まれるトランザクション番号から現在サーバで管理されているトランザクション番号までのデータをtransactionsエレメントを用いてクライアントに返す。
フローチャート
開始

クライアントより送られてきたトランザクション番号がサーバの保持するトランザクション番号と同じか小さいことを確認する。
確認した結果送られてきたトランザクション番号がサーバ保持するトランザクション番号より大きかった場合はエラー処理へ。
確認できた場合は次へ。

クライアントより送られてきたトランザクション情報が、サーバに保管されている対応した番号を持つトランザクション情報と一致することを確認する。
確認した結果送られてきたトランザクション情報がサーバに保管されているものと異なる場合はエラーへ。
確認できた場合は次へ。

サーバに保存されているデータを「クライアントから送られてきたトランザクション番号」から「現在サーバで保持してるトランザクション番号」まで取り出し、transactionsエレメントに追加する。 ↓
(あれば)taransacionsエレメントをdataエレメント内に設定し、クライアントに返す。

終了

エラー処理

サーバとクライアントの間でデータに矛盾が発生していることを返す。

終了

データ更新 (Data_Modify)

サーバはData_Modifyプロシージャがコールされた場合、その引数に含まれる「クライアントの保持する最新トランザクション」情報を用いてData_Verifyと同じ処理を行い、transactionsエレメントを作成する。
その後、送られてきたデータとサーバにあるデータとの衝突を調べながらサーバのデータと送られてきたデータをマージし、マージ結果をクライアントに返す。
下図では省略されているが、処理の途中で何らかの致命的エラーが発生した場合はfaultエレメントを含む帰り値を生成し、返す。
致命的エラーの処理については以下同じ。
フローチャート
開始

クライアントより送られてきた「クライアントの保持する最新トランザクション情報(latesttransacion)」よりData_Verifyと同様の処理を行い、transactionsタグを生成する。transactions作成中にエラー処理に移行した場合はそのまま終了する。

サーバの保持するトランザクション番号をインクリメントし、その新しいトランザクション番号とクライアントより与えられた新トランザクションIDを関連付ける。

クライアントより送られてきたnewtransacionに含まれるunitのUIDを取得し、先に作成したtransactionsに含まれるunitのUIDと比較する。
比較した結果transactionsに同一UIDをもつunitが含まれていた場合はそのunitに対するデータ更新は失敗したとして action を "Aborted"に設定したunitaryresultエレメントを生成し、帰り値のtransactionエレメントに追加する。
比較した結果transactionsに同一UIDを持つunitが含まれて居なかった場合、サーバはそのデータを先に作成した新しいトランザクション番号と関連付けてデータベースに保存する。その後action を "Committed"に設定したunitaryresultエレメントを生成し、帰り値のtransactionエレメントに追加する。

(あれば)taransacionsエレメントとtransactionエレメントをdataエレメント内に設定し、クライアントに返す。

終了

エラー処理

サーバとクライアントの間でデータに矛盾が発生していることを返す。

終了

セッション終了 (Session_Close)

サーバは呼び出しに含まれるSessionIDに関連付けられていたコンテキストなどあらゆるリソースを破棄する。

ファイル一覧取得 (File_GetFilenames)

サーバは保持するファイルすべてについての情報をfileエレメントに作成し、帰り値にとして返す。

ファイル追加 (File_Add)

サーバは与えられた情報から新しいファイルを作成する。

ファイル属性変更 (File_Config)

サーバは与えられた情報からファイルの属性を変更する。

ファイル削除 (File_Delete)

サーバは与えられた情報からファイルを削除する。

サーバ終了 (Server_Quit)

サーバは与えられた情報から即時終了ないし適時終了する。

サーバ設定取得 (Server_GetSetting)

サーバはその設定情報をparamエレメントに作成し、を返す。

コンフィグ (Server_Configv)

サーバはその設定情報を反映し、反映結果をparamエレメントに作成して返す。







文責:野中洋志