Table of contents

Overview

A schematic diagram is shown below.

Open

How to Manage Parameters

Open

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"}
]
}

Explain parameter definition file.

Size Limitation of Parameter Files

Maximum Parameter Definition File(PrefDefFile：appPrefs.json) size is 64KB.
※the file size is checked when Application Package is installed. (it returns preference error if the definition file size exceeds 64KB)

Maximum Parameter Saved File(PrefValFile:appPrefs.json) size is 128KB.
※the file size is checked when parameter file is saved. (it returns preference error if the definition file size exceeds 128KB)

・If maximum size of saved parameter file is 128 KB or less, preference error is not returned.

・You can set 128KB or more as the maximum size when preference value of each parameter is the maximum size or less.

・you can calculate the size of saved parameter file by following calculation formula（Byte）

Boolean type:size of prefName + 154 + size of value(true(4)/false(5)）+ size of defaultValue(true(4)/false(5)）＋ size of webApiAccess(ReadWrite(9)/Read(4)/None(4)) ＋ size of appApiAccess(ReadWrite(9)/Read(4))

 

Integer type:size of prefName + 154 + size of value + size of defaultValue＋ size of webApiAccess(ReadWrite(9)/Read(4)/None(4)) ＋ size of appApiAccess(ReadWrite(9)/Read(4))

 

String type:size of prefName + 153 + size of value + size of defaultValue＋ size of webApiAccess(ReadWrite(9)/Read(4)/None(4)) ＋ size of appApiAccess(ReadWrite(9)/Read(4))

 

Enumeration型:size of prefName ＋ 193 + size of value + size of defaultValue＋ (size of named Value + 17) * Number of Enumeration List＋ size of webApiAccess(ReadWrite(9)/Read(4)/None(4)) ＋ size of appApiAccess(ReadWrite(9)/Read(4))

 

Binary type:size of prefNam + 153 + size of value + size of defaultValue＋ size of webApiAccess(ReadWrite(9)/Read(4)/None(4)) ＋ size of appApiAccess(ReadWrite(9)/Read(4))

 

Size of Parameter Saved File: each parameter size + 109 + size of majorVersion ＋ size of minorVersion＋ number of escape characters

How to Update Application Parameters

Compare preferenceVersion of Installed Application(A) and that of update package(B)

Case: Major version is different
Replace parameter file(A) by parameter file(B).The parameter
of previously Installed Application is not used.

 

Case: Minor version is different
The parameters found both (A) and (B) :
Set the value of parameter (A). Other attributions are replaced by (B) (defaultValue,
webApiAccess and appApiAccess is changed）
Same parameter name but prefType is different :
Set defaultValue by (B)
EnumerationList have no value :
Set defaultValue by (B)
The parameters found only in(A) :
The parameter is deleted
The parameters found only in(B) :
The parameter is added

 

Case: Both Major version and Minor version are the same
Attributions other than value （defaultValue, webApiAccess, appApiAccess, EnumerationList） are different :
Preference error is returned
Attributions other than value are the same :
Set the value of parameter (A)

preferenceVersion is replaced by (B) when updated.

How to Restore Parameters

Making a comparison between The preferenceVersion of Installed Application(A) and the preferenceVersion of restore file(B)

Case: Major version is different
Preference error is returned

 

Case: Minor version is different
The parameters which is existed in both (A) and (B) :
Set the value of parameter (B) without changing other
attributions such as defaultValue, webApiAccess andappApiAccess
Same parameter name but prefType is different :
Do nothing
EnumerationList have no value :
Do nothing
The parameters found only in (A) :
Do nothing
The parameters found only in (B) :
Do nothing

 

Case: Both Major version and Minor are the same
Attributions other than value （defaultValue, webApiAccess,
appApiAccess, EnumerationList） are different :
Preference error is returned
Attributions other than value are the same :
Set the value of parameter (B)

preferenceVersion does not change after the restoration

API Specification

For the WebAPI specification, please refer to AdamWebAPI(AdamWebAPI_Specification_Vx_xx.pdf).

For the AppAPI specification, please refer to AdamAppAPI(AdamAppAPI_Specification_Vx_xx.pdf).

API List for AdamApp

Parameter Getting 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);

Parameter setting 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();

Update Notification 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;

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",
"appApiAccess" :"Read",
"webApiAccess" :"Read",
"defaultValue" :"ABC"} ,

 

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

Parameter Saved File(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"},
}