コマンド

---------------------------------------------------------------------
一般規則
コマンドはリクエスト・レスポンス形態をとるjson形式のメッセージ交換で処理されます。

リクエストメッセージの一般書式は以下の通りです。

パラメータを伴わないコマンド
"コマンド名"

パラメータを伴うコマンド
{
	"コマンド名":{
		"パラメータ名1":"パラメータ値1",
		"パラメータ名2":"パラメータ値2",
			:
		"パラメータ名n":"パラメータ値n"
	}
}

レスポンスメッセージの一般書式は以下の通りです。

正常終了
{
	"result":0,
	"取得データ名1":"取得データ1",
	"取得データ名2":"取得データ2",
		:
	"取得データ名n":"取得データn"
}

エラー終了
{
	"result":500,
	"msg":"permission error"
}

resultは終了コードを示し、0で正常、それ以外はエラーを示します。
取得データはコマンドの返値です。複数の項目が返される事があり、それぞれの項目の値はjson
規則に従った型（null値、文字列、数値、ブール値、オブジェクト値、配列）です。

---------------------------------------------------------------------
ユーザセッション

サーバに接続を行った後、sentinelサーバは、ユーザセッションの開始待ちとなり以下のメッセージ
を送ります。

{
	"version":[
		"1.0","1.2"
	],
	"auth":{
		"nonce":"PyFO4zZIes.Kc1DBKCDkD/",
		"algorithm":"MD5"
	},
	"server":[
		{"host":"server1","port":1119,"load":30},
		{"host":"server2","port":1119,"load":40}
	]
}

versionはサーバが対応するコマンドセットバージョンの一覧です。
serverは同じサービスを提供する接続可能なサーバのリストです。
loadの数値はその瞬間のサーバの負荷の状態を示します。複数台構成の場合、クライアントは最も
負荷の低いサーバを選択して接続するべきです。また、リストを保存して次回接続するサーバをリスト
からランダムに選択する事で、代表サーバへの集中、代表サーバがダウンしていた時の処理継続の両
面で有効です。ただし、リスト中のサーバは常に有効とは限らない（サーバの構成変更は常にあり得ます）
ため、接続の都度更新する必要があります。

ユーザセッションが開始されるまでの間、サーバへのリクエスト送信はloginコマンド以外は無効となります。
また、loginコマンド以外のリクエスト受信、または、無効なloginコマンドの受信でサーバはコネクションを
切断します。

ユーザセッションが開始されると、

---------------------------------------------------------------------
login コマンド

クライアントは接続を確立するために、ユーザ情報を送信します。
{
	"login":{
		"verion":"1.0",
		"uid":"tanaka",
		"device":{
			"did":"device id",
			"os":"os name",	... option
			"ver":"os version",	... option
			"ca":"carrier name",	... option
			"model":"device model name"	... option
		},
		"auth":{
			"response":"8stmOsHkz74vZKBpnHIjde",
			"nonce":"PyFO4zZIes.Kc1DBKCDkD/",
			"cnonce":"sspdpWSkwp29d130Akasjy",
			"algorithm":"MD5"
		}
	}
}

versionは利用するコマンドセットバージョン、uidはユーザ名、authは認証用のデータです。
nonceはサーバから受け取ったものをそのまま返します。
cnonceはクライアントが生成するランダムな文字列です
responseはnonce+パスワードから生成したハッシュ値+cnonceの文字列から生成したハッシュ値です。
使用するハッシュ関数はalgorithmで指定されます。
セキュリティ保護されていないアカウントはauth以下は不要です。

レスポンス
{
	"result":0,
	"aid":"00000001",
	"lastData":"2012/07/24-10:03:27"
}

正常終了の場合にはaidでアカウントID、lastDateで最後にログインした時刻が標準時刻で
返されます。

---------------------------------------------------------------------
register コマンド
新しくユーザアカウントを登録し接続を確立します。

{
	"register":{
		"verion":"1.0",
		"uid":"mailaddr",
		"name":"name",
		"lang":"user language", ... option
		"locale":"user locale", ... option
		"device":{
			"did":"device id",
			"os":"os name",	... option
			"ver":"os version",	... option
			"ca":"carrier name",	... option
			"model":"device model name"	... option
		},
		"auth":{
			"password":"password",
			"nonce":"PyFO4zZIes.Kc1DBKCDkD/",
		}
	}
}

versionは利用するコマンドセットバージョン、uidはユーザ名、authは認証用のデータです。
nonceはサーバから受け取ったものをそのまま返します。
cnonceはクライアントが生成するランダムな文字列です
responseはnonce+パスワードから生成したハッシュ値+cnonceの文字列から生成したハッシュ値です。
使用するハッシュ関数はalgorithmで指定されます。
セキュリティ保護されていないアカウントはauth以下は不要です。

レスポンス
{
	"result":0,
	"aid":"00000001",
	"lastData":"2012/07/24-10:03:27"
}

正常終了の場合にはaidでアカウントID、lastDateで最後にログインした時刻が標準時刻で
返されます。

---------------------------------------------------------------------
userコマンド
指定したアカウントのユーザ情報を返します。

{
	"user":{
		"aid":"00000001"
		または
		"aid":"self"
		または
		"uid":"tanaka"

		追加で取得する対象情報
		"field":["name","auth","mail","addr","phone","stat","all"]
	}
}

aidで指定したアカウントID、またはuidで指定したユーザIDのユーザ情報を返します。
uidに"self"を指定した場合、及びaid,uidを指定しない場合は接続ユーザの情報を返します。
fieldを指定した場合、対象フィールドのみ返されます。フィールドは配列形式で指定します。

レスポンス
{
	"result":0,
	"aid":"00000001",
	"uid":"tanaka",
	"auth":"yes",
	"email":"yasuoki@gmail.com",
	"lastDate":"2012/07/12-03:36:55"
	"name":"name",
	"level":10,
	"maxStorage":1000,
	"useStorage":500
}

---------------------------------------------------------------------
setuserコマンド
ユーザ情報を更新します。

{
	"setuser":{
		"aid":"00330287",
		"uid":"tanaka",
		"pass":"password",
		"email":"yasuoki@gmail.com",
		"name":"name",
		"level":10,
		"maxStorage":1000,
	}
}

aidで指定したユーザの登録情報を更新します。更新しない項目はメッセージ中に含める必要はありません
接続ユーザ自身の変更ではない場合は管理者権限が必要となります。
levelとmaxStorageの更新には管理者権限が必要となります。

レスポンス
リザルトコードが返されます。
{
	"result":0
}

---------------------------------------------------------------------
rmuserコマンド

既存のユーザを抹消します
{
	"rmuser":{
		"aid":"00008372"
		または
		"uid":"tanaka"
	}
}

aidで指定したアカウントID、またはuidで指定したユーザIDのユーザ情報を抹消します。

レスポンス
リザルトコードが返されます。
{
	"status":0,
}

---------------------------------------------------------------------
servicesコマンド
利用可能なサービスをリストします

{
	"services":{
		"from":0,
		"count":30
	}
}

fromでリストする最初の位置を指定します。countでリストする最大件数を指定します。
fromを省略すると先頭から、countを省略するとすべてとなります。

レスポンス
{
	"result": 0, 
	"services": [
		"S0000001",
		"S0000021",
		"S0000234"
		:
	]
}

サービスID"00000001"はユーザ領域同期サービスとして既定です。

---------------------------------------------------------------------
serviceコマンド
指定したサービスの詳細を返します

{
	"service":{
		"sid":"S0000001"
	}
}

sidで指定したサービスの詳細を返します。

レスポンス
{
	"result": 0, 
	"sid":"S0000001",
	"title":"service title",
	"description":"service description",
	"owner":"owner account",
	"status":"service status"
}

---------------------------------------------------------------------
servicegroupsコマンド
指定したサービスに参加するユーザグループ一覧を返します

{
	"servicegroups":{
		"sid":"S0000001"
	}
}

sidでサービスを指定します。

レスポンス
{
	"result": 0, 
	"groups": [
		"G0000001",
		"G0000021",
		"G0000234"
		:
	]
}
---------------------------------------------------------------------
regserviceコマンド
指定サービスにデバイスを関連付けます

{
	"regservice":{
		"service":"service name"
		or
		"sid":"serviceId"
	}
}

srviceまたはsidで指定したサービスに接続中のアカウント、デバイスを関連付けます。

レスポンス
{
	"result":0,
	"sid":"S0000001",
    "resources": [
        "R0000001", 
        "R0000002"
    ]
}

---------------------------------------------------------------------
resourcesコマンド
指定サービスに関連するリソースをリストします

{
	"resources":{
		"sid":"S0000001",
		"from":0,
		"count":30
	}
}

sidで指定したサービスに対応するリソース一覧を返します。
fromでリストする最初の位置を指定します。countでリストする最大件数を指定します。
fromを省略すると先頭から、countを省略するとすべてとなります。

レスポンス
{
	"result":0,
	"sid":"S0000001",
    "resources": [
        "R0000001", 
        "R0000002"
    ]
}

---------------------------------------------------------------------
resourceコマンド
指定リソースの情報を取得します
{
	"resource":{
		"rid":"S0000001"
	}
}
ridで指定したリソース情報を返します。

レスポンス
{
	"result":0,
	"sid":"S0000001",
	"rid":"R0000001",
	"URL":"https://server/target",
	"method":"GET",
	"params":"u=[account@uid]"
	"headers":"c=sentinel"
}

---------------------------------------------------------------------
syncstatコマンド
同期情報の状態を取得します

{
	"syncstat":{
		"rid":"R0000001"
		または
		"sid":"S0000001"
	}
}

ridを指定した場合、指定リソースの同期情報を取得します
sidを指定した場合、指定サービスに含まれるすべてのリソースの同期情報を取得します
rid,sidの両方とも指定しない場合、接続ユーザの参加する全てのサービスのすべてのリソースの同期情報を取得します

レスポンス
{
	"result":0,
	"status":[
		{
			"sid":"S0000001",
			"rid":"R0000001",
			"rev":29383726,
			"date":"2012/08/03-18:08:22"
		},
		{
			"sid":"S0000001",
			"rid":"R0000002",
			"rev":29383003,
			"date":"2012/08/03-18:09:33"
		},
		:
	]
}

---------------------------------------------------------------------
downsyncコマンド
下り同期処理を実行します

{
	"downsync":{
		"rid":"R0000001"
		"rev":29383003,
		"params":{
			"name1":"value1",
			"name2":"value2",
				:
			"nameN":"valueN",
		}
	}
}

ridで同期するリソースを指定します
revでデバイス側が認識しているリビジョン番号を指定します。サーバ側で認識しているリビション番号と
合致した場合、最新状態と言う事で転送は起こりません。

レスポンス
{
	"result":0,
	"rid":"R0000001",
	"rev":29383003,
}

リザルト0が返った場合には、更新するデータなしで終了です。

レスポンス
{
	"result":10,
	"rid":"R0000001",
	"rev":29383006,
	"date":"2012/08/03-18:19:33",
	"aid":"000000000002"
	"dev":"D23343004562"
	"stream":2
	"post":30
}

リザルト10が返った場合には、更新するデータのダウンロードシーケンスが開始されます。
revで新しいリビジョン、dateで更新日時、aidで更新ユーザ、devで更新したデバイスが示されます。
ダウンロードシーケンスはpostで指定した秒数以内に開始する必要があり、その時間を経過すると
解除されます。この時間内はリソースはロックされ他のコネクションからの更新要求は拒絶されます。
streamでダウンロードすべきデータの数が示されます。

ダウンロードは以下のメッセージの送付で開始されます。
{
	"download":{
		"rid":"R0000001",
		"rev":29383006,
		"stream":0
	}
}

レスポンス
stream=0
size=293827
crc=93ab3c70
（データ本体）
crlf

続くデータをダウンロードする場合

{
	"download":{
		"rid":"R0000001",
		"rev":29383006,
		"stream":1
	}
}

最後に完了メッセージを送ります。

{
	"complete":{
		"rid":"R0000001",
		"rev":29383006,
	}
}

ダウンロードシーケンスが解除されるのは次のケースです
1 completeコマンドの送付
2 cancelの１行を送付
3 コネクションの切断
4 post時間が経過するまでに受信を開始しない
5 サーバ側でエラーが発生した
6 APPサーバがエラーを返した


レスポンス
{
	"result":12,
	"rid":"R0000001",
	"rev":29383006,
	"date":"2012/08/03-18:19:33",
	"aid":"000000000002"
	"dev":"D23343004562"
	"data":{
		(アプリ固有データ）
	}
}

result=12の場合、レスポンス内のdata要素以下に同期データが含まれます。
どのようなデータが返されるかはアプリケーション定義です。

---------------------------------------------------------------------
upsyncコマンド
上り同期処理を実行します

{
	"upsync":{
		"rid":"R0000001"
		"rev":29383003,
		"date":"2012/08/03-18:09:33"
		"params":{
			"name1":"value1",
			"name2":"value2",
				:
			"nameN":"valueN",
		},
		"stream":1,
		"data":{
			(データ)
		}
	}
}

ridで同期するリソースを指定します
revでデバイス側が認識しているリビジョン番号を指定します。サーバ側で認識しているリビション番号と
合致しない場合、同期は失敗します。
dateで更新した日時を標準時間で指定します。
streamでアップロードする必要があるデータの数を指定します。
dataで更新したデータを指定します。streamとdataはどちらか一方のみ利用できます。

レスポンス
{
	"result":10,
	"rid":"R0000001",
	"rev":29383003,
	"stream":0
	"post":30
}

リザルト10が返った場合には、更新するデータのアップロードシーケンスが開始されます。
アップロードシーケンスはpostで指定した秒数以内に開始する必要があり、その時間を経過すると
解除されます。この時間内はリソースはロックされ他のコネクションからの更新要求は拒絶されます。
rid,rev,streamで対応するリソースを識別します。

リソースロックによりアップロードが拒絶された場合次のレスポンスが返ります

レスポンス
{
	"result":11,
	"rid":"R0000001",
	"rev":29383003,
	"aid":"000000000002"
	"dev":"D23343004562"
}
revでサーバが認識しているリビジョン、aidでロックしているユーザ、devでロックしているデバイスが通知されます。


競合によりアップロードが拒絶された場合次のレスポンスが返ります

レスポンス
{
	"result":12,
	"rid":"R0000001",
	"rev":29383005,
	"date":"2012/08/03-18:19:33",
	"aid":"000000000002"
}

revでサーバが認識しているリビジョン、dateでそのリビジョンに更新された日時、aidでそのリビジョンに
更新したユーザが通知されます。
競合状態となった場合、downsyncによってサーバの最新データとデバイスのデータをマージしてから
再度upsyncを行います。

アップロードシーケンスが開始されたら以下のメッセージでデータ本体を送ります。

stream=1
size=293827
crc=93ab3c70
（データ本体）
crlf

レスポンス
{
	"result":10,
	"rid":"R0000001",
	"rev":29383003,
	"stream":2
	"post":30
}

stream=2
size=29327
crc=3cabdd92
（データ本体）
crlf

レスポンス
{
	"result":10,
	"rid":"R0000001",
	"rev":29383003,
	"stream":2
	"post":30
}

  ：

全てのアップロードが終わると以下のレスポンスが返されます。

レスポンス
{
	"result":0,
	"rid":"R0000001",
	"rev":29383003,
	"newrev":29383004
	"date":"2012/08/03-18:19:33"
}
newrevはアップロードにより更新された新しいリビジョン番号です。
dateはアップロードが完了した日時です。

アップロードシーケンスが解除されるのは次のケースです
1 upsyncコマンドのstreamで指定した数のアップロードが終了（stream=nが一致したアップロード）
2 cancelの１行を送付
3 コネクションの切断
4 post時間が経過するまでに送信を開始しない
5 サーバ側でエラーが発生した
6 APPサーバがエラーを返した

---------------------------------------------------------------------
needsyncコマンド
同期が必要となった際にサーバよりクライアントへ送られます

{
	"needsync":{
		"rid":"R0000001"
		"rev":29383003,
		"date":"2012/08/03-18:09:33"
	}
}

ridで同期が必要となったリソースを示します
revでサーバ側が認識しているリビジョン番号を示します
dateで最終更新された日時を標準時間で示します。

クライアントはこのメッセージを受けたとき、downsync処理を行う必要があります。




