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      * The following class is used as a item stacking in request queue. The class stores a request
  53      * and referential information (e.g., a configuration name, a target resource object, a callback
  54      * function passed from the applications, and a update value). When the function for updating/
  55      * getting configuration value is called from applications, this class instance is created and
  56      * stored in the request queue. The queue is maintained in a std::map structure so if desiring
  57      * to find a specific request, you can find it by querying a configuration name.
  58      */
  59     class ConfigurationRequestEntry
  60     {
  61     public:
  62         ConfigurationRequestEntry(std::string ID, ConfigurationCallback callback,
  63                 std::shared_ptr< OCResource > resource, std::string updateVal);
  64
  65         // Configuration Name (used in key value in std::map structure)
  66         // e.g., time, network, security, and so on
  67         std::string m_ID;
  68         // Reference callback pointer
  69         ConfigurationCallback m_callback;
  70         // Reference resource object
  71         std::shared_ptr< OCResource > m_resource;
  72         // Update value only used for configuration update
  73         std::string m_updateVal;
  74     };
  75
  76     /**
  77      * The following class is used to store providing configuration name and its relevant
  78      * information. The relevant information includes a brief description, uri, and attribute key.
  79      * Note that a developer only specifies a configuration name, not URI nor attribute key, to
  80      * update/get a value to a remote. Thus, using configuration name, we convert it to more
  81      * specific information (i.e. uri and attribute key) to send a request. This class is reponsible
  82      * to storing these information.
  83      */
  84     class ConfigurationUnitInfo
  85     {
  86     public:
  87
  88         std::string m_name;
  89         std::string m_attribute;
  90         std::string m_uri;
  91
  92         ConfigurationUnitInfo(std::string name, std::string attribute, std::string uri);
  93
  94         // If a developer wants to know a list of configuration names, gives it in JSON format.
  95         std::string getJSON();
  96     };
  97
  98 #define NUMCONFUNIT 6
  99     typedef std::string ConfigurationName;
 100     typedef std::string ConfigurationValue;
 101
 102     /**
 103      * @par There are two main usages of this class:
 104      * -# On a server side, bootstrapping requisite information (i.e. system configuration parameters)
 105      * from a bootstrap server to access other IoT services,
 106      * -# On a client side, getting/updating the system configuration parameters from/to multiple remote things.
 107      * @par
 108      */
 109     class ThingsConfiguration
 110     {
 111     public:
 112         /**
 113          * Constructor for ThingsConfiguration. Constructs a new ThingsConfiguration
 114          */
 115         ThingsConfiguration(void);
 116
 117         /**
 118          * Virtual destructor
 119          */
 120         ~ThingsConfiguration(void);
 121
 122         static ThingsConfiguration *thingsConfigurationInstance;
 123         static ThingsConfiguration* getInstance();
 124
 125         // TODO: deprecated
 126         void deleteInstance();
 127         void setGroupManager(GroupManager *groupmanager);
 128
 129         /**
 130          * API for updating configuration value of multiple things of a target group or a single
 131          * thing.
 132          * Callback is called when a response arrives.
 133          * Before using the below function, a developer should acquire a resource pointer of
 134          * (collection) resource that he want to send a request by calling findResource() function
 135          * provided in OCPlatform. And he should also notice a "Configuration Name" term which
 136          * represents a nickname of a target attribute of a resource that he wants to update.
 137          * The base motivation to introduce the term is to avoid a usage of URI to access a resource
 138          * from a developer. Thus, a developer should know which configuration names are supported
 139          * by Things Configuration class and what the configuration name means.
 140          * To get a list of supported configuration names, use getListOfSupportedConfigurationUnits(
 141          * ) function, which provides the list in JSON format.
 142          *
 143          * NOTICE: A series of callback functions is called from updateConfigurations() function:
 144          * @par
 145          * -# For a collection resource
 146          * updateConfiguration()->onDeleteActionSet()->onGetChildInfoForUpdate()->onCreateActionSet(
 147          * )->...(CoAP msg. is transmitted)->OnExecuteForGroupAction()->callback function in APP.
 148          * -# For a simple resource
 149          * updateConfiguration()->...(CoAP msg. is transmitted)->OnPut()->callback function in APP.
 150          * @par
 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 Returns ::OC_STACK_OK if success, some other value upon failure.
 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          *
 171          * NOTICE: A series of callback functions is called from getConfigurations() function:
 172          * @par
 173          * -# For a collection resource
 174          * getConfigurations()->onGetChildInfoForGet()->...(CoAP msg. is transmitted)
 175          * ->callback function in APP.
 176          * -# For a simple resource
 177          * getConfigurations()->...(CoAP msg. is transmitted)->onGet()->callback function in APP.
 178          * @par
 179          *
 180          * @param resource resource pointer representing the target group or the single thing.
 181          * @param configurations ConfigurationUnit: an attribute key of target resource.
 182          * @param callback callback.
 183          *
 184          * @return Returns ::OC_STACK_OK if success, some other value upon failure.
 185          *
 186          * @note OCStackResult is defined in ocstack.h.
 187          */
 188         OCStackResult getConfigurations(std::shared_ptr< OCResource > resource,
 189                 std::vector< ConfigurationName > configurations, ConfigurationCallback callback);
 190
 191         /**
 192          * API to show a list of supported configuration units (configurable parameters)
 193          * Callback call when a response arrives.
 194          *
 195          * @return the list in JSON format
 196          */
 197         std::string getListOfSupportedConfigurationUnits();
 198
 199         /**
 200          * API for bootstrapping functionality. Find a bootstrap server and get configuration
 201          * information from the bootstrap server. With the information, make a configuration
 202          * resource.
 203          *
 204          * @param callback callback.
 205          *
 206          * @return Returns ::OC_STACK_OK if success, some other value upon failure.
 207          *
 208          * @note OCStackResult is defined in ocstack.h.
 209          */
 210         OCStackResult doBootstrap(ConfigurationCallback callback);
 211
 212     private:
 213
 214         GroupManager *g_groupmanager;
 215
 216         std::vector< ConfigurationUnitInfo > ConfigurationUnitTable;
 217
 218         void onExecuteForGroupAction(const HeaderOptions& headerOptions,
 219                 const OCRepresentation& rep, const int eCode, std::string conf);
 220         void onGetChildInfoForUpdate(const HeaderOptions& headerOptions,
 221                 const OCRepresentation& rep, const int eCode, std::string conf);
 222         void onGetChildInfoForGet(const HeaderOptions& headerOptions, const OCRepresentation& rep,
 223                 const int eCode, std::string conf);
 224         void onCreateActionSet(const HeaderOptions& headerOptions, const OCRepresentation& rep,
 225                 const int eCode, std::string conf);
 226         void onGetActionSet(const HeaderOptions& headerOptions, const OCRepresentation& rep,
 227                 const int eCode, std::string conf);
 228         void onDeleteActionSet(const HeaderOptions& headerOptions, const OCRepresentation& rep,
 229                 const int eCode, std::string conf);
 230         void onGet(const HeaderOptions& headerOptions, const OCRepresentation& rep, const int eCode,
 231                 std::string conf);
 232         void onPut(const HeaderOptions& headerOptions, const OCRepresentation& rep, const int eCode,
 233                 std::string conf);
 234         static void onFoundBootstrapServer(std::vector< std::shared_ptr< OCResource > > resources);
 235         static void onGetBootstrapInformation(const HeaderOptions& headerOptions,
 236                 const OCRepresentation& rep, const int eCode);
 237
 238         std::shared_ptr< OCResource > getResource(std::string conf);
 239         ConfigurationCallback getCallback(std::string conf);
 240         std::string getUpdateVal(std::string conf);
 241         std::string getAttributeByConfigurationName(ConfigurationName name);
 242         std::string getUriByConfigurationName(ConfigurationName name);
 243
 244         std::string getHostFromURI(std::string oldUri);
 245
 246         bool isSimpleResource(std::shared_ptr< OCResource > resource);
 247         bool hasBatchInterface(std::shared_ptr< OCResource > resource);
 248
 249     };
 250 }
 251 #endif  /* __OC_THINGSCONFIGURATION__*/
 252