Overview

A schematic diagram is shown below.

How to Manage Parameters

Application parameter setting sequence

Application stopping state

Application running state

Data type of parameters

Boolean: logical data type
Description
Represented by either “TRUE” or “FALSE”
Example
TRUE, FALSE
Integer: integral data type
Description
Signed 64-bit integral data
The range of value is from -9223372036854775808 to 9223372036854775807
Example
0, 12345, -9876543
String: character data type
Description
Less than 1023 characters
UTF-8 characters
Escape character is available（however, you must insert ‘¥’ before escape characters）
Example
“ABC xyz 012”, “¥/123456¥”abcd”
Enumeration: enumerated data type
Description
Consists of a set of named values
Available named values are same as String data type
The value needs more than one character
The character must not be duplicated
Example
definition：[“Item0”, “Item1”, “Item2”, “Item3”], value：“Item0”, “Item1”
definition：[“¥/123456¥”abcd”, “ABC xyz 123”, “”], value：“¥/123456¥”abcd”
Binary: Binary data type
Description
String data of Base64 encoded binary data
Size limit is 32KB.(Exceeded data will be discarded)
Example
Bitmap Image, feature vector

Access Permission of Parameters

Restricting access for each parameter

appApiAccess：access permit setting from AdamApp API
ReadWrite
Able to Read/Write parameters from AdamApp API
Read
Only able to Read parameters from AdamApp API (unable to write parameters)
webApiAccess：access permit setting from WebAPI
ReadWrite
Able to Read/Write parameters from WEBAPI
Read
Only able to Read parameters from WEB API ( unable to write parameters )
None
Unable to either Read nor Write parameters from WEBAPI

Parameter File Format

Parameter definition file （PrefDefFile：appPrefs.json）

{
"preferenceVersion" :{"major":"1", "minor":"1"},
"preference": [ {"prefName" :"Pref0",
"prefType" :"Boolean",
"appApiAccess" :"ReadWrite",
"webApiAccess" :"ReadWrite",
"defaultValue" :"TRUE" },

{"prefName" :"Pref1",
"prefType" :"Integer",
"appApiAccess" :"Read",
"webApiAccess" :"None",
"defaultValue" :"0"} ,

{"prefName" :"Pref2",
"prefType" :"String",
"defaultValue" :"This is a ¥"String¥"."} ,

{"prefName" :"Pref3",
"prefType" :"Enumeration",
"enumerationList" : ["Item0", "Item1", "Item2"],
"defaultValue" :"Item0"} ,

{"prefName" :"Pref4",
"prefType" :"Binary",
"defaultValue" :" YWJjZGVmZWZn"}
]
}

Definition file is written in JSON format

Explain parameter definition file.

パラメータ定義ファイルのサイズ制約

アプリパラメータ定義ファイル（PrefDefFile：appPrefs.json）は最大64KB
※インストール時に定義ファイルのサイズが64KBを超える場合にはエラーとなる。

アプリパラメータ値内部管理ファイル（PrefValFile:appPrefs.json）は最大128KB
※パラメータ保存時に内部管理ファイルのサイズが128KBを超える場合にはエラーとなる。

・設定時にパラメータ値保存ファイルの最大サイズを128KB以下に抑えることで保存時のサイズエラーをなくすことが可能
・各パラメータの設定値を最大サイズ以下で扱う場合は、最大サイズが128KBを超えるように設定することも可能
・パラメータ保存ファイルのサイズは下記の計算式で計算することが出来る（単位：Byte）

Boolean型:prefNameのサイズ+154+valueのサイズ（true(4)/false(5)）+defaultValueのサイズ（ true (4)/ false (5) ）＋ webApiAccessのサイズ(ReadWrite(9)/Read(4)/None(4))＋ appApiAccessのサイズ(ReadWrite(9)/Read(4))
Integer型:prefNameのサイズ+154+valueのサイズ+defaultValueのサイズ＋ webApiAccessのサイズ(ReadWrite(9)/Read(4)/None(4))＋ appApiAccessのサイズ(ReadWrite(9)/Read(4))
String型:prefNameのサイズ+153+valueのサイズ+defaultValueのサイズ＋ webApiAccessのサイズ(ReadWrite(9)/Read(4)/None(4))＋ appApiAccessのサイズ(ReadWrite(9)/Read(4))
Enumeration型: prefNameのサイズ＋ 193 + 154+valueのサイズ+defaultValueのサイズ＋ (Enumeration Listの要素のサイズ+ 17) * Enumeration Listの要素数＋ webApiAccessのサイズ(ReadWrite(9)/Read(4)/None(4))＋ appApiAccessのサイズ(ReadWrite(9)/Read(4))
Binary型:prefNameのサイズ+153+valueのサイズ+defaultValueのサイズ＋ webApiAccessのサイズ(ReadWrite(9)/Read(4)/None(4))＋ appApiAccessのサイズ(ReadWrite(9)/Read(4))
パラメータ値保存ファイル:各パラメータ保存サイズの合計+109+majorVersionのサイズ＋minorVersionのサイズ＋各パラメータのprefNameとvalueとenumerationLisの中にあるエスケープ文字の数

アプリアップデート時の設定値の対応

インストール済みアプリ(A)のpreferenceVersionとアップデートパッケージ(B)中のpreferenceVersionを比較し、次の動作を行う

１．Majorバージョンが違う場合
アップデートパッケージのアプリパラメータ定義ファイルに置き換え → インストール済みアプリの値は一切利用しない
２．Minorバージョンが違う場合
(A)と(B)の両方に存在するパラメータ： (A)のvalueを設定
・ただし、その他の属性値は変更される（defaultValueや、appApiAccessなども値を変更される）
・同じパラメータ名で、型が変わる場合は、defaultValueを設定
・EnumerationListの要素にvalueがなければ、defaultValueを設定
(A)のみに存在するパラメータ：そのパラメータを削除
(B)のみに存在するパラメータ：そのパラメータを追加
３．MajorバージョンもMinorバージョンも同じ場合
(A)と(B)のvalue以外の属性値（defaultValue, webApiAccess, appApiAccess, EnumerationList）が一つでも異なっていればエラー
(A)と(B)の全ての属性値が同じ場合 (A)のvalueを設定

アップデート完了後、preferenceVersionは、アップデートパッケージのものに設定される

設定値Restore時の対応

インストール済みアプリ(A)のpreferenceVersionと、リストアファイル(B)のpreferenceVersionを比較し、次の動作を行う

１．Majorバージョンが違う場合
エラー
２．Minorバージョンが違う場合
(A)と(B)の両方に存在するパラメータ： (B)の値を設定
・ただし、 valueのみが変更され、その他の属性値は変更されない
（defaultValueや、appApiAccessなどは変更されない）
・同じパラメータ名で型が違う場合は、何もしない
・EnumerationListの要素に、(B)の値が無ければ、何もしない
(A)のみに存在するパラメータ：何もしない
(B)のみに存在するパラメータ：何もしない
３．MajorバージョンもMinorバージョンも同じ場合
(A)と(B)のvalue以外の属性値（defaultValue, webApiAccess, appApiAccess, EnumerationList）が一つでも異なっていればエラー
(A)と(B)の全ての属性値が同じ場合 (B)のvalueを設定

リストア完了後、preferenceVersionは変更されない

API仕様

WebAPI仕様については、AdamWebAPI仕様書(AdamWebAPI_Specification_Vx_xx.pdf)を参照してください。

アプリ向け仕様については、AdamAppAPI仕様書(AdamAppAPI_Specification_Vx_xx.pdf)を参照してください。

アプリ向けAPI仕様一覧

パラメータ取得API

E_ADAM_ERR ADAM_AppPref_GetBoolean(const char* pPrefName, bool* pValue);
E_ADAM_ERR ADAM_AppPref_GetInteger(const char* pPrefName, int64_t* pValue);
E_ADAM_ERR ADAM_AppPref_GetString(const char* pPrefName, char* pValue, unsigned int size);
E_ADAM_ERR ADAM_AppPref_GetEnumeration(const char* pPrefName, unsigned int* pValue);
E_ADAM_ERR ADAM_AppPref_GetBinary(const char* pPrefName, unsigned char* pValue,
unsigned int size);

パラメータ設定API

E_ADAM_ERR ADAM_AppPref_Lock();
E_ADAM_ERR ADAM_AppPref_Unlock();
E_ADAM_ERR ADAM_AppPref_BeginTransaction();
E_ADAM_ERR ADAM_AppPref_CancelTransaction();
E_ADAM_ERR ADAM_AppPref_SaveTransaction();
E_ADAM_ERR ADAM_AppPref_SetBoolean(const char* pPrefName, bool value);
E_ADAM_ERR ADAM_AppPref_SetInteger(const char* pPrefName, int64_t value);
E_ADAM_ERR ADAM_AppPref_SetString(const char* pPrefName, const char* pValue);
E_ADAM_ERR ADAM_AppPref_SetEnumeration(const char* pPrefName, unsigned int value);
E_ADAM_ERR ADAM_AppPref _SetBinary(const char* pPrefName, unsigned char* pValue,
unsigned int size)
E_ADAM_ERR ADAM_AppPref_Reset();

パラメータ更新通知用API

typedef void (T_ADAM_NOTIFY_APP_PREF_UPDATE_HANDLER)(char const pPrefName[], const
unsigned int prefSize);
typedef struct ST_ADAM_SYSTEM_HANDLERS {
T_ADAM_STOP_HANDLER m_stopHandler;
T_ADAM_NOTIFY_APP_PREF_UPDATE_HANDLER m_notifyAppPrefUpdateHandler;
T_ADAM_SERVER_REQUEST_RECEIVE_HANDLER m_serverRequestReceiveHandler;
} ST_ADAM_SYSTEM_HANDLERS;

パラメータファイルフォーマット

アプリパラメータ定義ファイル(PrefDefFile：appPrefs.json)

{
"preferenceVersion": {"major":"1", "minor":"1"},
"preference":[{"prefName" :"Pref0",
"prefType" :"Boolean",
"appApiAccess" :"ReadWrite",
"webApiAccess" :"ReadWrite",
"defaultValue" :"TRUE" },
{"prefName" :"Pref1",
"prefType" :"Integer",
"appApiAccess" :"Read",
"webApiAccess" :"None",
"defaultValue" :"0"} ,
{"prefName" :"Pref2",
"prefType" :"String",
"appApiAccess" :"Read",
"webApiAccess" :"Read",
"defaultValue" :"ABC"} ,
{"prefName" :"Pref3",
"prefType" :"Enumeration",
"enumerationList" :
["Item0", "Item1", "Item2"]
"defaultValue" :"Item0"} ,
}

アプリパラメータ内部管理ファイル(PrefValFile:appPrefs.json)

{
"funcId" :"123",
"preferenceVersion": {"major":"1", "minor":"1"},
"preference":[{"prefName" :"Pref0",
"prefType" :"Boolean",
"appApiAccess" :"ReadWrite",
"webApiAccess" :"ReadWrite",
"defaultValue" :"TRUE" ,
"value" :"TRUE"},

{"prefName" :"Pref1",
"prefType" :"Integer",
"appApiAccess" :"Read",
"webApiAccess" :"None",
"defaultValue" :"0" ,
"value" :"0"},

{"prefName" :"Pref2",
"prefType" :"String",
"appApiAccess" :"Read",
"webApiAccess" :"Read",
"defaultValue" :"ABC" ,
"value" :"ABC"},

{"prefName" :"Pref3",
"prefType" :"Enumeration",
"appApiAccess" :"ReadWrite",
"webApiAccess" :"ReadWrite",
"enumerationList" :
["Item0", "Item1", "Item2"]
"defaultValue" :"Item0" ,
"value" :"Item0"},
}

Application Preference Function Guide

Table of contents