diff options
Diffstat (limited to 'SDL_Core/doc/doxygen/components/SmartObjects')
8 files changed, 375 insertions, 0 deletions
diff --git a/SDL_Core/doc/doxygen/components/SmartObjects/Smart Objects Types/Type casts.txt b/SDL_Core/doc/doxygen/components/SmartObjects/Smart Objects Types/Type casts.txt new file mode 100644 index 000000000..3ae636c92 --- /dev/null +++ b/SDL_Core/doc/doxygen/components/SmartObjects/Smart Objects Types/Type casts.txt @@ -0,0 +1,204 @@ +/*! \page components_smartobjects_types_cast Type cast for SmartObjects + +One of easy and probably intuitive way to work with values in the Smart Object is simple use of the type casts. Implementation of NsSmartDeviceLink::NsSmartObjects::CSmartObject class has all necessary declarations to support all required types. + +Example 1 (Work with int value): + +<pre> +NsSmartDeviceLink::NsSmartObjects::CSmartObject obj; + +obj = 1; //Assign int value + +int i = (int)obj; //Get int value + +</pre> + +Example 2 (Work with long value): + +<pre> + +NsSmartDeviceLink::NsSmartObjects::CSmartObject obj; + +obj = 100l; //Assign long value + +long l = (long)obj; //Get long value + +</pre> + +Example 3 (Work with double value): + +<pre> + +NsSmartDeviceLink::NsSmartObjects::CSmartObject obj; + +obj = 3.14; //Assign double value + +double d = (double)obj; //Get double value + +</pre> + +Example 4 (Work with char value): + +<pre> + +NsSmartDeviceLink::NsSmartObjects::CSmartObject obj; + +obj = 'a'; //Assign char value + +char c = (char)obj; //Get char value + +</pre> + +Example 5 (Work with bool value): + +<pre> + +NsSmartDeviceLink::NsSmartObjects::CSmartObject obj; + +obj = true; //Assign bool value + +bool b = (bool)obj; //Get bool value + +</pre> + +Example 6 (Work with string values): + +<pre> + +NsSmartDeviceLink::NsSmartObjects::CSmartObject obj1; + +obj1 = "Hello, world"; //Assign char* string value + +obj2 = std::string("Hello, world"); //Assign std::string value + +std::string s1 = (std::string)obj1; + +std::string s2 = (std::string)obj2; + +</pre> + +Example 7 (Work with arrays): + +<pre> + +NsSmartDeviceLink::NsSmartObjects::CSmartObject simpleArray; + +simpleArray[0] = 1; + +simpleArray[1] = true; + +simpleArray[2] = 'a'; + +simpleArray[3] = 3.14; + +int val0 = (int)simpleArray[0]; + +bool val1 = (bool)simpleArray[1]; + +char val2 = (char)simpleArray[2]; + +double val3 = (double)simpleArray[3]; + +NsSmartDeviceLink::NsSmartObjects::CSmartObject deepArray; + +deepArray[0] = 1; + +deepArray[1][0] = 3.14; + +deepArray[1][1][0] = true; + +int val0 = (int)obj[0]; + +double val1_0 = (double)obj[1][0]; + +bool val1_1_0 = (bool)obj[1][1][0]; + +</pre> + + +Example 8 (Work with maps): + +<pre> + +NsSmartDeviceLink::NsSmartObjects::CSmartObject simpleMap; + +simpleMap["name"] = "My name"; + +simpleMap["count"] = 10; + +simpleMap["isValid"] = true; + +std::string name = (std::string)obj["name"]; + +int count = (int)obj["count"]; + +bool isValid = (bool)obj["isValid"]; + +NsSmartDeviceLink::NsSmartObjects::CSmartObject deepMap; + +deepMap["request"]["name"] = "My Request"; + +deepMap["request"]["id"] = 123; + +deepMap["response"]["name"] = "My Response"; + +deepMap["response"]["id"] = 456; + +deepMap["we"]["need"]["to"]["go"]["deeper"] = true; + +std::string requestName = (std::string)deepMap["request"]["name"]; + +int requestId = (int)deepMap["request"]["id"]; + +std::string responseName = (std::string)deepMap["response"]["name"]; + +int responseId = (int)deepMap["response"]["id"]; + +deepFlag = (bool)deepMap["we"]["need"]["to"]["go"]["deeper"]; + +</pre> + + +Example 9 (Removing elements from Map): + +<pre> + +NsSmartDeviceLink::NsSmartObjects::CSmartObject mapObj; + +mapObj["first"] = "first value"; +mapObj["second"] = "second value"; +mapObj["to delete"] = 1234; +mapObj["third"] = "third value"; + +bool result = mapObj.erase("to delete"); + +</pre> + + +Example 10 (Using alternative method of accessing SmartObject values) + +<pre> + +NsSmartDeviceLink::NsSmartObjects::CSmartObject obj; + +obj = 1; //Assign int value +int i = obj.asInt(); //Get int value + +obj = 100l; //Assign long value +long l = obj.asLong(); //Get long value + +obj = 3.14; //Assign double value +double d = obj.asDouble(); //Get double value + +obj = true; +bool b = obj.asBool(); // Get bool value + +obj = 'c'; +char c = obj.asChar(); // Get char value + +obj = "some string"; +std::string str = obj.asString(); // Get string value + +</pre> + +*/ diff --git a/SDL_Core/doc/doxygen/components/SmartObjects/Smart Objects Types/Value representation.txt b/SDL_Core/doc/doxygen/components/SmartObjects/Smart Objects Types/Value representation.txt new file mode 100644 index 000000000..6505ae6f4 --- /dev/null +++ b/SDL_Core/doc/doxygen/components/SmartObjects/Smart Objects Types/Value representation.txt @@ -0,0 +1,25 @@ +/*! \page components_smartobjects_types_repr Type value representation methods for SmartObjects + +As alternative to the type casts NsSmartDeviceLink::NsSmartObjects::CSmartObject class defines set of usable methods that allow to represent object values as desired type. Use of these methods may change code style and readability but functionally it completely similar to the type casts of Smart Objects. + +Example: + +<pre> +NsSmartDeviceLink::NsSmartObjects::CSmartObject obj; + +obj[0] = 1; + +obj[1] = true; + +obj[2] = 'a'; + +obj[3] = 3.14; + +int i = obj[0].asInt(); + +char c = obj[1].asChar(); + +double d = obj[2].asDouble(); +</pre> + +*/ diff --git a/SDL_Core/doc/doxygen/components/SmartObjects/Smart Objects Types/index.txt b/SDL_Core/doc/doxygen/components/SmartObjects/Smart Objects Types/index.txt new file mode 100644 index 000000000..9ca3fb3e9 --- /dev/null +++ b/SDL_Core/doc/doxygen/components/SmartObjects/Smart Objects Types/index.txt @@ -0,0 +1,9 @@ +/*! \page components_smartobjects_types Smart Objects Types + +Current implementation of Smart Objects contains definitions that allow working with every Smart Object +as variable of one of the basic types: bool, int, long, double, char, string (both as char* and std::string), array and map. + +There are two different ways to work with type values in SmartObjects: + - \subpage components_smartobjects_types_cast "Type cast for SmartObjects" + - \subpage components_smartobjects_types_repr "Type value representation methods for SmartObjects" +*/ diff --git a/SDL_Core/doc/doxygen/components/SmartObjects/Smart Objects Validation/Schema Structure.txt b/SDL_Core/doc/doxygen/components/SmartObjects/Smart Objects Validation/Schema Structure.txt new file mode 100644 index 000000000..2e611f74b --- /dev/null +++ b/SDL_Core/doc/doxygen/components/SmartObjects/Smart Objects Validation/Schema Structure.txt @@ -0,0 +1,101 @@ +/*! \page components_smartobjects_validation_items Schema structure: Schema Items + +In order to create new Schema (new object of class NsSmartDeviceLink::NsSmartObjects::CSmartSchema) client first must define all required Schema Items. Actually every Schema is a tree of respective Schema Items. Each node and leaf of that tree defines structural rules for some Smart Object data structure. + +Schema Items are represented as class hierarchy. The base class for all schema items is a NsSmartDeviceLink::NsSmartObjects::ISchemaItem class. This base class defines generic validation interface for Schema Items. + +To define special elements with always successful or always failing validation there are two special Schema Items: NsSmartDeviceLink::NsSmartObjects::CAlwaysTrueSchemaItem and NsSmartDeviceLink::NsSmartObjects::CAlwaysFalseSchemaItem. + +NsSmartDeviceLink::NsSmartObjects::CBoolSchemaItem is used for boolean values and has no parameters (only verifies that respective Smart Object is really has boolean value). + +NsSmartDeviceLink::NsSmartObjects::TNumberSchemaItem is template Schema Item that can be used for both integer and floating point values. In addition to the regular type verification it is possible to set min and max value range (these values are optional). + +NsSmartDeviceLink::NsSmartObjects::TEnumSchemaItem is used to verify any custom client-defined enum. + +NsSmartDeviceLink::NsSmartObjects::CStringSchemaItem is used to verify a string values. As optional parameter max length of the string could be set. + +NsSmartDeviceLink::NsSmartObjects::CArraySchemaItem provides validation for array. Can be used to verify special type and array size. + +NsSmartDeviceLink::NsSmartObjects::CObjectSchemaItem used in case when Schema Item includes another Schema Item. Actually this is only way to create tree node of new Schema. All other Schema Items will be used only to become leafs of validation tree. + +After creation of all required Schema Items (which is actually bind in the tree) it is possible to create Schema. +Schema can be initialized not only by raw root Schema Item, but also by special abstraction called Member (defined by NsSmartDeviceLink::NsSmartObjects::CObjectSchemaItem::SMember class). So every root item (NsSmartDeviceLink::NsSmartObjects::CObjectSchemaItem) firstly should be wrapped as Member. This wrapping process also allows to set "is mandatory" status for every Member. + + and pass root Schema Item as initial parameter to the new Schema. + +Currently Schemas are generated by the InterfaceGenerator. For supported ALRPC.v1/.v2 Schema has following structure: + +<pre> + +ROOT + | + -- PARAMS + | | + | -- FUNCTION_ID + | | + | -- MESSAGE_TYPE + | | + | -- CORRELATION_ID + | | + | -- PROTOCOL_VERSION + | | + | -- PROTOCOL_TYPE + | + -- MSG_PARAMS + | + -- OBJECT + | + -- (Actually contains function-specific leaf item) + ... +</pre> + +Example: + +<pre> + +// Function parameter success. +// +// true, if successful +// false, if failed +TSharedPtr<ISchemaItem> success_SchemaItem = CBoolSchemaItem::create(TSchemaItemParameter<bool>()); + +// Function parameter resultCode. +// +// See Result +TSharedPtr<ISchemaItem> resultCode_SchemaItem = TEnumSchemaItem<Result::eType>::create(resultCode_allowedEnumSubsetValues, TSchemaItemParameter<Result::eType>()); + +// Function parameter info. +// +// Provides additional human readable info regarding the result. +TSharedPtr<ISchemaItem> info_SchemaItem = CStringSchemaItem::create(TSchemaItemParameter<size_t>(1000), TSchemaItemParameter<std::string>()); + +schemaMembersMap["success"] = CObjectSchemaItem::SMember(success_SchemaItem, true); + +schemaMembersMap["resultCode"] = CObjectSchemaItem::SMember(resultCode_SchemaItem, true); + +schemaMembersMap["info"] = CObjectSchemaItem::SMember(info_SchemaItem, false); + +std::map<std::string, CObjectSchemaItem::SMember> paramsMembersMap; + +paramsMembersMap[NsSmartDeviceLink::NsJSONHandler::strings::S_FUNCTION_ID] = CObjectSchemaItem::SMember(TEnumSchemaItem<FunctionID::eType>::create(FunctionIDItems), true); + +paramsMembersMap[NsSmartDeviceLink::NsJSONHandler::strings::S_MESSAGE_TYPE] = CObjectSchemaItem::SMember(TEnumSchemaItem<messageType::eType>::create(MessageTypeItems), true); + +paramsMembersMap[NsSmartDeviceLink::NsJSONHandler::strings::S_CORRELATION_ID] = CObjectSchemaItem::SMember(TNumberSchemaItem<int>::create(), true); + +paramsMembersMap[NsSmartDeviceLink::NsJSONHandler::strings::S_PROTOCOL_VERSION] = CObjectSchemaItem::SMember(TNumberSchemaItem<int>::create(1, 2), true); + +paramsMembersMap[NsSmartDeviceLink::NsJSONHandler::strings::S_PROTOCOL_TYPE] = CObjectSchemaItem::SMember(TNumberSchemaItem<int>::create(), true); + +std::map<std::string, CObjectSchemaItem::SMember> rootMembersMap; + +rootMembersMap[NsSmartDeviceLink::NsJSONHandler::strings::S_MSG_PARAMS] = CObjectSchemaItem::SMember(CObjectSchemaItem::create(schemaMembersMap), true); + +rootMembersMap[NsSmartDeviceLink::NsJSONHandler::strings::S_PARAMS] = CObjectSchemaItem::SMember(CObjectSchemaItem::create(paramsMembersMap), true); + + +CSmartSchema(CObjectSchemaItem::create(rootMembersMap)); + +</pre> + +*/ diff --git a/SDL_Core/doc/doxygen/components/SmartObjects/Smart Objects Validation/Validation.txt b/SDL_Core/doc/doxygen/components/SmartObjects/Smart Objects Validation/Validation.txt new file mode 100644 index 000000000..a02f0be4b --- /dev/null +++ b/SDL_Core/doc/doxygen/components/SmartObjects/Smart Objects Validation/Validation.txt @@ -0,0 +1,9 @@ +/*! \page components_smartobjects_validation_use Using Schema for validation + +The main purpose of Schema is validation of existing Smart Object. This process includes type and value validation. The client can use results of validation to determine if given Smart Object is valid or not. Validation of specific Smart Object can be triggered by using NsSmartDeviceLink::NsSmartObjects::CSmartSchema::validate method. Internally Schema triggers respective validate method of every Schema Item in order to perform validation. + +Another feature of Schema is capability to be applied to the Smart Object. Applying means that Schema tries to modify object to "normalize" data. Currently this "normalization" effects on string representation of enums. Applying of the Schema can be triggered by using NsSmartDeviceLink::NsSmartObjects::CSmartSchema::applySchema method. Internally Schema triggers respective apply method of every Schema Item and at the moment only enum Schema Items try to covert string representation to enum values. + +To "unapply" modifications done by apply feature Schema has NsSmartDeviceLink::NsSmartObjects::CSmartSchema::unapplySchema method. It can be used to make string representations of enums. + +*/ diff --git a/SDL_Core/doc/doxygen/components/SmartObjects/Smart Objects Validation/index.txt b/SDL_Core/doc/doxygen/components/SmartObjects/Smart Objects Validation/index.txt new file mode 100644 index 000000000..d42579187 --- /dev/null +++ b/SDL_Core/doc/doxygen/components/SmartObjects/Smart Objects Validation/index.txt @@ -0,0 +1,10 @@ +/*! \page components_smartobjects_validation Smart Objects validation + +The mechanism of Smart Objects validation includes special Schema. This Schema is similar to the regular XML schema. In other words Schema defines structural description of desired object. After that definition is done Schema can be applied to the object in order to make validation. + +Every Schema is constructed from objects called SchemaItems. Every SchemaItem defines type and restriction of specific data structure. + +For more details please review: + - \subpage components_smartobjects_validation_items "Schema structure: Schema Items" + - \subpage components_smartobjects_validation_use "Using Schema for validation" +*/ diff --git a/SDL_Core/doc/doxygen/components/SmartObjects/Use of Smart Objects/index.txt b/SDL_Core/doc/doxygen/components/SmartObjects/Use of Smart Objects/index.txt new file mode 100644 index 000000000..6ad626de4 --- /dev/null +++ b/SDL_Core/doc/doxygen/components/SmartObjects/Use of Smart Objects/index.txt @@ -0,0 +1,6 @@ +/*! \page components_smartobjects_usage Use Smart Objects + +There are lots of useful applications for the Smart Objects. They allow building complex dynamic data +structures in runtime and can be used to store and provide almost any data. For example any array can contain an item which is other array and so on. + +*/ diff --git a/SDL_Core/doc/doxygen/components/SmartObjects/index.txt b/SDL_Core/doc/doxygen/components/SmartObjects/index.txt new file mode 100644 index 000000000..3844e1ab6 --- /dev/null +++ b/SDL_Core/doc/doxygen/components/SmartObjects/index.txt @@ -0,0 +1,11 @@ +/*! \page components_smartobjects Smart Objects + +Smart Object is building block for a custom dynamic data structures with virtually unlimited complexity. Client code can use Smart Objects to create containers for simple basic types such as bools, ints, doubles, chars, strings end enums as well as arrays and maps. + +Smart Objects solution also includes validation/normalization mechanism of schemas witch is similar to the XML schemas. This feature allows client to validate any data structure. + +More detailed information is described in following chapters: + - \subpage components_smartobjects_types "Smart Objects Types" + - \subpage components_smartobjects_usage "Use of Smart Objects" + - \subpage components_smartobjects_validation "Smart Objects validation" +*/ |