Net秘書君仕様書 ver 0.40

最初に

文書中「クライアント」は秘書君2またはその互換ソフトである。

文書中「サーバ」は秘書君サーバまたはその互換ソフトである。

概要

通信プロトコルはXMLを使用する。
エンコード方法は全てShift-JISとする。
アトリビュート名、エレメント名は全てアルファベット小文字とハイフン、アンダースコアのみで構成される
サーバーの状態は「未認証」->「認証済み」->「ファイル選択済み」と遷移する。
クライアントの状態は「未認証」->「認証済み」->「ファイル選択済み」と遷移する。セッション初期化が行われた場合には未認証状態に戻る。
すべての通信はクライアントからのプロシージャコールの形で行われる
通信セッションは「セッション作成」で作成され、「セッション終了」で削除される。セッションの区別はセッションIDによって行われ、通信形態にはよらない。

プロシージャ一覧

プロシージャ一覧
名称	プロシージャ名	概要	引数	返り値
セッション作成	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"が指定されます。

例

呼び出し例

応答例

<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>

概要

サーバはユーザー管理、データファイル管理、データ管理を行う。
データ管理については、単位データ(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エレメントに作成して返す。