FileDescriptor - TakayukiHoshi1984/DeviceConnect-Spec GitHub Wiki

スマートフォンまたは周辺機器から他方のスマートデバイスに対しての ファイルディスクリプタ操作機能を提供するAPI。

API	概要
PUT /gotapi/fileDescriptor/close	スマートデバイスのファイルのクローズを要求する。
GET /gotapi/fileDescriptor/onWatchFile	スマートデバイスのファイルの更新時間が変化したことを取得する。
PUT /gotapi/fileDescriptor/onWatchFile	スマートデバイスのファイルの更新時間が変化したことを通知するイベントを開始する。
DELETE /gotapi/fileDescriptor/onWatchFile	スマートデバイスのファイルの更新時間が変化したことを通知するイベントを登録解除する。
GET /gotapi/fileDescriptor/open	スマートデバイスのファイルオープンを要求する。
GET /gotapi/fileDescriptor/read	スマートデバイスのファイルを指定したサイズ分取得する。
PUT /gotapi/fileDescriptor/write	スマートデバイスのファイルへの書き込みを要求する。

one-shot

スマートデバイスのファイルのクローズを要求する。

ファイルがクローズされるまで、 オープンされたファイルはFileプロファイルなどで参照できない。

物理名	データ型	必須	説明
serviceId	string	Yes	サービスID。取得対象スマートデバイス
path	string	Yes	ファイルパス。ファイルが存在するパス。 ルートはデバイスプラグインごとに異なる。 ディレクトリを指定した場合はエラーを返す。

論理名	物理名	データ型	必須	説明
処理結果	result	integer	Yes	0: 正常応答 0以外: 異常応答
システム名	product	string	Yes	DeviceConnectシステムの名前。
システムバージョン	version	string	Yes	DeviceConnectシステムのバージョン名。
署名	hmac	string	No	レスポンスに対する署名。 アプリケーション側から事前にHMACキーを共有されていた場合は必須。

{
  "result" : 0,
  "product" : "Example System",
  "version" : "1.0.0"
}

one-shot

スマートデバイスのファイルの更新時間が変化したことを取得する。

プラグイン側でキャッシュしている最新のイベントメッセージを1つ取得する。

物理名	データ型	必須	説明
serviceId	string	Yes	サービスID。取得対象スマートデバイス

論理名	物理名	データ型	必須	説明
処理結果	result	integer	Yes	0: 正常応答 0以外: 異常応答
システム名	product	string	Yes	DeviceConnectシステムの名前。
システムバージョン	version	string	Yes	DeviceConnectシステムのバージョン名。
署名	hmac	string	No	レスポンスに対する署名。 アプリケーション側から事前にHMACキーを共有されていた場合は必須。

{
  "result" : 0,
  "product" : "Example System",
  "version" : "1.0.0",
  "file" : {
    "path" : "Test1.png",
    "curr" : "2017-01-01T12:34:56+0900",
    "prev" : "2017-01-01T01:23:45+0900"
  }
}

event

スマートデバイスのファイルの更新時間が変化したことを通知するイベントを開始する。

スマートデバイスのファイルへの書き込みが発生した時にイベントが発行される。

物理名	データ型	必須	説明
serviceId	string	Yes	サービスID。取得対象スマートデバイス
interval	long	No	デバイスプラグインがイベントを送信する間隔。

論理名	物理名	データ型	必須	説明
処理結果	result	integer	Yes	0: 正常応答 0以外: 異常応答
システム名	product	string	Yes	DeviceConnectシステムの名前。
システムバージョン	version	string	Yes	DeviceConnectシステムのバージョン名。
署名	hmac	string	No	レスポンスに対する署名。 アプリケーション側から事前にHMACキーを共有されていた場合は必須。

{
  "result" : 0,
  "product" : "Example System",
  "version" : "1.0.0"
}

論理名	物理名	データ型	必須	説明
サービスID	serviceId	string	Yes	イベントを送信したサービスのID
プロファイル名	profile	string	Yes	プロファイル名。
インターフェース名	interface	string	Yes	インターフェース名。
アトリビュート名	attribute	string	Yes	アトリビュート名。

{
  "serviceId" : "Host.exampleId.localhost.deviceconnect.org",
  "profile" : "filedescriptor",
  "attribute" : "onwatchfile",
  "file" : {
    "path" : "/dir/file1.txt",
    "curr" : "2014-05-02 T10:32:10+0900",
    "prev" : "2014-05-01 T10:32:10+0900"
  }
}

event

スマートデバイスのファイルの更新時間が変化したことを通知するイベントを登録解除する。

スマートデバイスのファイルへの書き込みが発生した時にイベントが発行される。

物理名	データ型	必須	説明
serviceId	string	Yes	サービスID。取得対象スマートデバイス

論理名	物理名	データ型	必須	説明
処理結果	result	integer	Yes	0: 正常応答 0以外: 異常応答
システム名	product	string	Yes	DeviceConnectシステムの名前。
システムバージョン	version	string	Yes	DeviceConnectシステムのバージョン名。
署名	hmac	string	No	レスポンスに対する署名。 アプリケーション側から事前にHMACキーを共有されていた場合は必須。

{
  "result" : 0,
  "product" : "Example System",
  "version" : "1.0.0"
}

one-shot

スマートデバイスのファイルオープンを要求する。

ここで使用するpathは、Fileプロファイルで取得できる。

物理名	データ型	必須	説明
serviceId	string	Yes	サービスID。取得対象スマートデバイス
path	string	Yes	ファイルパス。ファイルが存在するパス。 ルートはデバイスプラグインごとに異なる。 ディレクトリを指定した場合はエラーを返す。
flag	string	Yes	フラグ。 r : 読み込みのみ rw : 読み込み＆書き込み

論理名	物理名	データ型	必須	説明
処理結果	result	integer	Yes	0: 正常応答 0以外: 異常応答
システム名	product	string	Yes	DeviceConnectシステムの名前。
システムバージョン	version	string	Yes	DeviceConnectシステムのバージョン名。
署名	hmac	string	No	レスポンスに対する署名。 アプリケーション側から事前にHMACキーを共有されていた場合は必須。

{
  "result" : 0,
  "product" : "Example System",
  "version" : "1.0.0"
}

one-shot

スマートデバイスのファイルを指定したサイズ分取得する。

スマートデバイスのファイルが読み込み完了していない場合には、 再度このAPIを利用して取得を行う。

物理名	データ型	必須	説明
serviceId	string	Yes	サービスID。取得対象スマートデバイス
path	string	Yes	ファイルパス。ファイルが存在するパス。 ルートはデバイスプラグインごとに異なる。 ディレクトリを指定した場合はエラーを返す。
length	long	Yes	読み込みサイズ。一度の読み込みで取得する最大サイズ。 length > 0
position	long	No	読み込み開始位置。読み込みファイルの開始位置を指定する。 省略された場合には、現在ファイルが読み込んでいる位置から読み込む。 position >= 0

論理名	物理名	データ型	必須	説明
処理結果	result	integer	Yes	0: 正常応答 0以外: 異常応答
システム名	product	string	Yes	DeviceConnectシステムの名前。
システムバージョン	version	string	Yes	DeviceConnectシステムのバージョン名。
署名	hmac	string	No	レスポンスに対する署名。 アプリケーション側から事前にHMACキーを共有されていた場合は必須。
データサイズ	size	integer	Yes	読み込んだデータのサイズ
データ	fileData	string	Yes	読み込んだデータをdata URI schemeの形式で設定する

{
  "result" : 0,
  "product" : "Example System",
  "version" : "1.0.0",
  "size" : 100,
  "fileData" : "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg=="
}

one-shot

スマートデバイスのファイルへの書き込みを要求する。

スマートデバイスのファイルが書き込み完了していない場合には、 デバイスプラグイン側で書き込みが終わるまで待つこと。 書き込み中の場合はエラーを返し、再度リクエストを出すこと。

物理名	データ型	必須	説明
serviceId	string	Yes	サービスID。取得対象スマートデバイス
path	string	Yes	ファイルパス。ファイルが存在するパス。 ルートはデバイスプラグインごとに異なる。 ディレクトリを指定した場合はエラーを返す。
uri	string	No	URI。dataと同時に省略することはできない。 両方指定した場合はdataが優先され、uriは無視される。
data	file	No	ファイルのbinary。送信するファイルのbinary。 uriと同時に省略することはできない。 両方指定した場合はdataが優先され、uriは無視される。
position	long	No	ファイルオフセット。 ファイルの書き込み開始位置を指定する。 省略された場合には、現在ファイルが書き込んでいる位置から書き込む。

論理名	物理名	データ型	必須	説明
処理結果	result	integer	Yes	0: 正常応答 0以外: 異常応答
システム名	product	string	Yes	DeviceConnectシステムの名前。
システムバージョン	version	string	Yes	DeviceConnectシステムのバージョン名。
署名	hmac	string	No	レスポンスに対する署名。 アプリケーション側から事前にHMACキーを共有されていた場合は必須。

{
  "result" : 0,
  "product" : "Example System",
  "version" : "1.0.0"
}