service/things-manager/sdk/inc/ThingsConfiguration.h

   1 //******************************************************************
   2 //
   3 // Copyright 2014 Samsung Electronics All Rights Reserved.
   4 //
   5 //-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
   6 //
   7 // Licensed under the Apache License, Version 2.0 (the "License");
   8 // you may not use this file except in compliance with the License.
   9 // You may obtain a copy of the License at
  10 //
  11 //      http://www.apache.org/licenses/LICENSE-2.0
  12 //
  13 // Unless required by applicable law or agreed to in writing, software
  14 // distributed under the License is distributed on an "AS IS" BASIS,
  15 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  16 // See the License for the specific language governing permissions and
  17 // limitations under the License.
  18 //
  19 //-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
  20
  21 /**
  22  * @file
  23  *
  24  * This file contains the declaration of classes and its members related to
  25  * ThingsConfiguration.
  26  */
  27
  28 #ifndef __OC_THINGSCONFIGURATION__
  29 #define __OC_THINGSCONFIGURATION__
  30
  31 #include <string>
  32 #include <vector>
  33 #include <map>
  34 #include <cstdlib>
  35 #include "GroupManager.h"
  36 #include "OCPlatform.h"
  37 #include "OCApi.h"
  38
  39 using namespace OC;
  40
  41 namespace OIC
  42 {
  43 /// Declearation of Configuation Callback funtion type
  44     typedef std::function<
  45             void(const HeaderOptions& headerOptions, const OCRepresentation& rep, const int eCode)
  46             > ConfigurationCallback;
  47
  48     typedef std::string ConfigurationName;
  49     typedef std::string ConfigurationValue;
  50
  51     /**
  52      * @brief
  53      * The following class is used as a item stacking in request queue. The class stores a request
  54      * and referential information (e.g., a configuration name, a target resource object, a callback
  55      * function passed from the applications, and a update value). When the function for updating/
  56      * getting configuration value is called from applications, this class instance is created and
  57      * stored in the request queue. The queue is maintained in a std::map structure so if desiring
  58      * to find a specific request, you can find it by querying a configuration name.
  59      */
  60     class ConfigurationRequestEntry
  61     {
  62     public:
  63         ConfigurationRequestEntry(std::string ID, ConfigurationCallback callback,
  64                 std::shared_ptr< OCResource > resource, std::string updateVal);
  65
  66         // Configuration Name (used in key value in std::map structure)
  67         // e.g., time, network, security, and so on
  68         std::string m_ID;
  69         // Reference callback pointer
  70         ConfigurationCallback m_callback;
  71         // Reference resource object
  72         std::shared_ptr< OCResource > m_resource;
  73         // Update value only used for configuration update
  74         std::string m_updateVal;
  75     };
  76
  77     /**
  78      * @brief
  79      * The following class is used to store providing configuration name and its relevant
  80      * information. The relevant information includes a brief description, uri, and attribute key.
  81      * Note that a developer only specifies a configuration name, not URI nor attribute key, to
  82      * update/get a value to a remote. Thus, using configuration name, we convert it to more
  83      * specific information (i.e. uri and attribute key) to send a request. This class is reponsible
  84      * to storing these information.
  85      */
  86     class ConfigurationUnitInfo
  87     {
  88     public:
  89
  90         std::string m_name;
  91         std::string m_attribute;
  92         std::string m_uri;
  93
  94         ConfigurationUnitInfo(std::string name, std::string attribute, std::string uri);
  95
  96         // If a developer wants to know a list of configuration names, gives it in JSON format.
  97         std::string getJSON();
  98     };
  99
 100 #define NUMCONFUNIT 6
 101     typedef std::string ConfigurationName;
 102     typedef std::string ConfigurationValue;
 103
 104     /**
 105      * @class ThingsConfiguration
 106      * @brief
 107      * There are two main usages of this class: (1) On a server side, bootstrapping requisite
 108      * information (i.e. system configuration parameters) from a bootstrap server to access other
 109      * IoT services, (2) On a client side, getting/updating the system configuration parameters
 110      * from/to multiple remote things.
 111      */
 112     class ThingsConfiguration
 113     {
 114     public:
 115         /**
 116          * Constructor for ThingsConfiguration. Constructs a new ThingsConfiguration
 117          */
 118         ThingsConfiguration(void);
 119
 120         /**
 121          * Virtual destructor
 122          */
 123         ~ThingsConfiguration(void);
 124
 125         static ThingsConfiguration *thingsConfigurationInstance;
 126         static ThingsConfiguration* getInstance();
 127
 128         // TODO: deprecated
 129         void deleteInstance();
 130         void setGroupManager(GroupManager *groupmanager);
 131
 132         /**
 133          * API for updating configuration value of multiple things of a target group or a single
 134          * thing.
 135          * Callback is called when a response arrives.
 136          * Before using the below function, a developer should acquire a resource pointer of
 137          * (collection) resource that he want to send a request by calling findResource() function
 138          * provided in OCPlatform. And he should also notice a "Configuration Name" term which
 139          * represents a nickname of a target attribute of a resource that he wants to update.
 140          * The base motivation to introduce the term is to avoid a usage of URI to access a resource
 141          * from a developer. Thus, a developer should know which configuration names are supported
 142          * by Things Configuration class and what the configuration name means.
 143          * To get a list of supported configuration names, use getListOfSupportedConfigurationUnits(
 144          * ) function, which provides the list in JSON format.
 145          * NOTICE: A series of callback functions is called from updateConfigurations() function:
 146          * (1) For a collection resource
 147          * updateConfiguration()->onDeleteActionSet()->onGetChildInfoForUpdate()->onCreateActionSet(
 148          * )->...(CoAP msg. is transmitted)->OnExecuteForGroupAction()->callback function in APP.
 149          * (2) For a simple resource
 150          * updateConfiguration()->...(CoAP msg. is transmitted)->OnPut()->callback function in APP.
 151          *
 152          * @param resource - resource pointer representing the target group or the single thing.
 153          * @param configurations - ConfigurationUnit: an attribute key of target resource
 154          *                         (e.g., loc, st, c, r)
 155          *                         Value : a value to be updated
 156          * @param callback - callback.
 157          *
 158          * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
 159          *
 160          * NOTE: OCStackResult is defined in ocstack.h.
 161          */
 162         OCStackResult updateConfigurations(std::shared_ptr< OCResource > resource,
 163                 std::map< ConfigurationName, ConfigurationValue > configurations,
 164                 ConfigurationCallback callback);
 165
 166         /**
 167          * API for getting configuration value of multiple things of a target group or a single
 168          * thing.
 169          * Callback is called when a response arrives.
 170          * NOTICE: A series of callback functions is called from getConfigurations() function:
 171          * (1) For a collection resource
 172          * getConfigurations()->onGetChildInfoForGet()->...(CoAP msg. is transmitted)
 173          * ->callback function in APP.
 174          * (2) For a simple resource
 175          * getConfigurations()->...(CoAP msg. is transmitted)->onGet()->callback function in APP.
 176          *
 177          * @param resource - resource pointer representing the target group or the single thing.
 178          * @param configurations - ConfigurationUnit: an attribute key of target resource.
 179          * @param callback - callback.
 180          *
 181          * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
 182          *
 183          * NOTE: OCStackResult is defined in ocstack.h.
 184          */
 185         OCStackResult getConfigurations(std::shared_ptr< OCResource > resource,
 186                 std::vector< ConfigurationName > configurations, ConfigurationCallback callback);
 187
 188         /**
 189          * API to show a list of supported configuration units (configurable parameters)
 190          * Callback call when a response arrives.
 191          *
 192          * @return the list in JSON format
 193          */
 194         std::string getListOfSupportedConfigurationUnits();
 195
 196         /**
 197          * API for bootstrapping functionality. Find a bootstrap server and get configuration
 198          * information from the bootstrap server. With the information, make a configuration
 199          * resource.
 200          *
 201          * @param callback - callback.
 202          *
 203          * @return OCStackResult return value of this API. Returns OC_STACK_OK if success.
 204          *
 205          * NOTE: OCStackResult is defined in ocstack.h.
 206          */
 207         OCStackResult doBootstrap(ConfigurationCallback callback);
 208
 209     private:
 210
 211         GroupManager *g_groupmanager;
 212
 213         std::vector< ConfigurationUnitInfo > ConfigurationUnitTable;
 214
 215         void onExecuteForGroupAction(const HeaderOptions& headerOptions,
 216                 const OCRepresentation& rep, const int eCode, std::string conf);
 217         void onGetChildInfoForUpdate(const HeaderOptions& headerOptions,
 218                 const OCRepresentation& rep, const int eCode, std::string conf);
 219         void onGetChildInfoForGet(const HeaderOptions& headerOptions, const OCRepresentation& rep,
 220                 const int eCode, std::string conf);
 221         void onCreateActionSet(const HeaderOptions& headerOptions, const OCRepresentation& rep,
 222                 const int eCode, std::string conf);
 223         void onGetActionSet(const HeaderOptions& headerOptions, const OCRepresentation& rep,
 224                 const int eCode, std::string conf);
 225         void onDeleteActionSet(const HeaderOptions& headerOptions, const OCRepresentation& rep,
 226                 const int eCode, std::string conf);
 227         void onGet(const HeaderOptions& headerOptions, const OCRepresentation& rep, const int eCode,
 228                 std::string conf);
 229         void onPut(const HeaderOptions& headerOptions, const OCRepresentation& rep, const int eCode,
 230                 std::string conf);
 231         static void onFoundBootstrapServer(std::vector< std::shared_ptr< OCResource > > resources);
 232         static void onGetBootstrapInformation(const HeaderOptions& headerOptions,
 233                 const OCRepresentation& rep, const int eCode);
 234
 235         std::shared_ptr< OCResource > getResource(std::string conf);
 236         ConfigurationCallback getCallback(std::string conf);
 237         std::string getUpdateVal(std::string conf);
 238         std::string getAttributeByConfigurationName(ConfigurationName name);
 239         std::string getUriByConfigurationName(ConfigurationName name);
 240
 241         std::string getHostFromURI(std::string oldUri);
 242
 243         bool isSimpleResource(std::shared_ptr< OCResource > resource);
 244         bool hasBatchInterface(std::shared_ptr< OCResource > resource);
 245
 246     };
 247 }
 248 #endif  /* __OC_THINGSCONFIGURATION__*/
 249