service/things-manager/sdk/inc/ThingsManager.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 /// @file   ThingsManager.h
  22 ///
  23 /// @brief  This file contains the declaration of  ThingsManager class
  24 ///         and its members related to ThingsManager.
  25
  26 #ifndef __OC_THINGSMANAGER__
  27 #define __OC_THINGSMANAGER__
  28
  29 #include <string>
  30 #include <vector>
  31 #include <map>
  32 #include <cstdlib>
  33 #include "OCPlatform.h"
  34 #include "OCApi.h"
  35 #include "GroupManager.h"
  36
  37 using namespace OC;
  38
  39 namespace OIC
  40 {
  41     /**
  42      * @class   ThingsManager
  43      * @brief   This class provides a set of functions regarding group management,
  44      *          synchronization of group, configuration of things, and diagnostics about things.
  45      *
  46      */
  47     class ThingsManager
  48     {
  49     public:
  50         /**
  51          * Constructor for ThingsManager
  52          */
  53         ThingsManager(void);
  54
  55         /**
  56          * Virtual destructor for ThingsManager
  57          */
  58         ~ThingsManager(void);
  59
  60         /**
  61          * API for discoverying candidate resources.
  62          * Callback is called  when all resource types are found.
  63          *
  64          * @param resourceTypes - required resource types(called "candidate")
  65          * @param candidateCallback - callback. Returns OCResource vector.
  66          *
  67          * @return OCStackResult - return value of this API.
  68          *                         It returns OC_STACK_OK if success.
  69          *
  70          * NOTE: OCStackResult is defined in ocstack.h.
  71          */
  72         OCStackResult findCandidateResources(std::vector< std::string > resourceTypes,
  73                 std::function< void(std::vector< std::shared_ptr< OCResource > >) > callback,
  74                 int waitsec = -1);
  75
  76         /**
  77          * API for subscribing child's state.
  78          *
  79          * @param resource - collection resource for subscribing presence of all child resources.
  80          * @param callback - callback funcion for result of child's presence.
  81          *
  82          * @return OCStackResult - return value of this API.
  83          *                         It returns OC_STACK_OK if success.
  84          *
  85          * NOTE: OCStackResult is defined in ocstack.h.
  86          */
  87         OCStackResult subscribeCollectionPresence(std::shared_ptr< OCResource > resource,
  88                 std::function< void(std::string, OCStackResult) > callback);
  89
  90         /**
  91          * API for register and bind resource to group.
  92          *
  93          * @param childHandle - child resource handle. It will be filled from resource param.
  94          * @param resource - resource for register and bind to group. It has all data.
  95          * @param collectionHandle - collection resource handle. It will be added child resource.
  96          *
  97          * @return OCStackResult - return value of this API.
  98          *                         It returns OC_STACK_OK if success.
  99          *
 100          * NOTE: OCStackResult is defined in ocstack.h.
 101          */
 102         OCStackResult bindResourceToGroup(OCResourceHandle& childHandle,
 103                 std::shared_ptr< OCResource > resource, OCResourceHandle& collectionHandle);
 104
 105         // Group Synchronization
 106
 107         /**
 108          * API for finding a specific remote group when a resource tries to join a group.
 109          * Callback is called when a group is found or not.
 110          *
 111          * @param collectionResourceTypes - resource types of a group to find and join
 112          * @param callback - callback. It has OCResource param.
 113          *                    If a group is found, OCResource has the group resource.
 114          *                    Otherwise, OCResource is NULL.
 115          *
 116          * @return OCStackResult - return value of this API.
 117          *                         It returns OC_STACK_OK if success.
 118          *
 119          * NOTE: OCStackResult is defined in ocstack.h.
 120          */
 121         OCStackResult findGroup(std::vector< std::string > collectionResourceTypes,
 122                 FindCallback callback);
 123
 124         /**
 125          * API for creating a new group.
 126          *
 127          * @param collectionResourceType - resource type of a group to create
 128          *
 129          * @return OCStackResult - return value of this API.
 130          *                         It returns OC_STACK_OK if success.
 131          *
 132          * NOTE: OCStackResult is defined in ocstack.h.
 133          */
 134         OCStackResult createGroup(std::string collectionResourceType);
 135
 136         /**
 137          * API for joining a group. This API is used when a resource that has a group tries
 138          * to find a specific remote resource and makes it join a group
 139          *
 140          * @param collectionResourceType - resource type of a group to join.
 141          * @param resourceHandle - resource handle to join a group.
 142          *
 143          * @return OCStackResult - return value of this API.
 144          *                         It returns OC_STACK_OK if success.
 145          *
 146          * NOTE: OCStackResult is defined in ocstack.h.
 147          */
 148         OCStackResult joinGroup(std::string collectionResourceType,
 149                 OCResourceHandle resourceHandle);
 150
 151         /**
 152          * API for joining a group. This API is used when a resource that
 153          * doesn't have a group tries to find and join a specific remote group.
 154          *
 155          * @param resource - group resource pointer to join.
 156          *                   It can be the callback result of findGroup().
 157          * @param resourceHandle - resource handle to join a group.
 158          *
 159          * @return OCStackResult - return value of this API.
 160          *                         It returns OC_STACK_OK if success.
 161          *
 162          * NOTE: OCStackResult is defined in ocstack.h.
 163          */
 164         OCStackResult joinGroup(const std::shared_ptr< OCResource > resource,
 165                 OCResourceHandle resourceHandle);
 166
 167         /**
 168          * API for leaving a joined group.
 169          *
 170          * @param collectionResourceType - resource type of a group to leave.
 171          * @param resourceHandle - resource handle to leave a group.
 172          *
 173          * @return OCStackResult - return value of this API.
 174          *                         It returns OC_STACK_OK if success.
 175          *
 176          * NOTE: OCStackResult is defined in ocstack.h.
 177          */
 178         OCStackResult leaveGroup(std::string collectionResourceType,
 179                 OCResourceHandle resourceHandle);
 180
 181         /**
 182          * API for deleting a group.
 183          *
 184          * @param collectionResourceType - resource type of a group to delete.
 185          *
 186          * @return void
 187          */
 188         void deleteGroup(std::string collectionResourceType);
 189
 190         /**
 191          * API for getting a list of joined groups.
 192          *
 193          * @param void
 194          *
 195          * @return std::map - return value of this API.
 196          *                  It returns group resource type and group resource handle as a map type.
 197          */
 198         std::map< std::string, OCResourceHandle > getGroupList(void);
 199
 200         // Things Configuration
 201
 202         /**
 203          * API for updating configuration value of multiple things of a target group
 204          * or a single thing.
 205          * Callback is called when a response arrives.
 206          * Before using the below function, a developer should acquire a resource pointer of
 207          * (collection) resource that he wants to send a request by calling findResource() function
 208          * provided in OCPlatform. And he should also notice a "Configuration Name" term which
 209          * represents a nickname of a target attribute of a resource that he wants to update.
 210          * The base motivation to introduce the term is to avoid a usage of URI to access a resource
 211          * from a developer. Thus, a developer should know which configuration names are supported
 212          * by Things Configuration class and what the configuration name means.
 213          * To get a list of supported configuration names,
 214          * use getListOfSupportedConfigurationUnits()
 215          * function, which provides the list in JSON format.
 216          *
 217          * @param resource - resource pointer representing the target group or the single thing.
 218          * @param configurations - ConfigurationUnit: a nickname of attribute of target resource
 219          *                         (e.g., installedlocation, currency, (IP)address)
 220          *                         Value : a value to be updated
 221          * @param callback - callback for updateConfigurations.
 222          *
 223          * @return OCStackResult - return value of this API.
 224          *                         It returns OC_STACK_OK if success.
 225          *
 226          * NOTE: OCStackResult is defined in ocstack.h.
 227          */
 228         OCStackResult updateConfigurations(std::shared_ptr< OCResource > resource,
 229                 std::map< std::string, std::string > configurations,
 230                 std::function<
 231                         void(const HeaderOptions& headerOptions, const OCRepresentation& rep,
 232                                 const int eCode) > callback);
 233
 234         /**
 235          * API for getting configuration value of multiple things of a target group
 236          * or a single thing.
 237          * Callback is called when a response arrives.
 238          *
 239          * @param resource - resource pointer representing the target group or the single thing.
 240          * @param configurations - ConfigurationUnit: a nickname of attribute of target resource.
 241          * @param callback - callback for getConfigurations.
 242          *
 243          * @return OCStackResult - return value of this API.
 244          *                         It returns OC_STACK_OK if success.
 245          *
 246          * NOTE: OCStackResult is defined in ocstack.h.
 247          */
 248         OCStackResult getConfigurations(std::shared_ptr< OCResource > resource,
 249                 std::vector< std::string > configurations,
 250                 std::function<
 251                         void(const HeaderOptions& headerOptions, const OCRepresentation& rep,
 252                                 const int eCode) > callback);
 253
 254         /**
 255          * API for showing the list of supported configuration units (configurable parameters)
 256          * Callback is called when a response arrives.
 257          *
 258          * @param void
 259          * @return std::string - return value of this API.
 260          *                       It returns the list in JSON format
 261          */
 262         std::string getListOfSupportedConfigurationUnits();
 263
 264         /**
 265          * API for boostrapping system configuration parameters from a bootstrap server.
 266          * Callback call when a response from the bootstrap server arrives.
 267          *
 268          * @param callback - callback for doBootstrap.
 269          *
 270          * @return OCStackResult - return value of this API.
 271          *                         It returns OC_STACK_OK if success.
 272          *
 273          * NOTE: OCStackResult is defined in ocstack.h.
 274          */
 275         OCStackResult doBootstrap(
 276                 std::function<
 277                         void(const HeaderOptions& headerOptions, const OCRepresentation& rep,
 278                                 const int eCode) > callback);
 279
 280         // Things Diagnostics
 281
 282         /**
 283          * API to let thing(device) reboot.
 284          * The target thing could be a group of multiple things or a single thing.
 285          * Callback is called when a response arrives.
 286          *
 287          * @param resource - resource pointer representing the target group
 288          * @param callback - callback for reboot.
 289          *
 290          * @return OCStackResult - return value of this API.
 291          *                         It returns OC_STACK_OK if success.
 292          *
 293          * NOTE: OCStackResult is defined in ocstack.h.
 294          */
 295         OCStackResult reboot(std::shared_ptr< OCResource > resource,
 296                 std::function<
 297                         void(const HeaderOptions& headerOptions, const OCRepresentation& rep,
 298                                 const int eCode) > callback);
 299
 300         /**
 301          * API for factory reset on thing(device).
 302          * The target thing could be a group of multiple things or a single thing.
 303          * Callback is called when a response arrives.
 304          *
 305          * @param resource - resource pointer representing the target group
 306          * @param callback - callback for factoryReset.
 307          *
 308          * @return OCStackResult - return value of this API.
 309          *                         It returns OC_STACK_OK if success.
 310          *
 311          * NOTE: OCStackResult is defined in ocstack.h.
 312          */
 313         OCStackResult factoryReset(std::shared_ptr< OCResource > resource,
 314                 std::function<
 315                         void(const HeaderOptions& headerOptions, const OCRepresentation& rep,
 316                                 const int eCode) > callback);
 317
 318         // Group Action.
 319
 320         /**
 321          * API for extracting Action Set string from the Action Set class instance
 322          *
 323          * @param newActionSet - pointer of Action Set
 324          *
 325          * @return std::string - return value of this API.
 326          *                                           It returns Action Set String.
 327          *
 328          * NOTE: OCStackResult is defined in ocstack.h.
 329          */
 330         std::string getStringFromActionSet(const ActionSet *newActionSet);
 331
 332         /**
 333          * API for extrracting Action Set class instance from Action Set String.
 334          *
 335          * @param desc - description of Action set
 336          *
 337          * @return ActionSet* - return value of this API.
 338          *                      It returns pointer of ActionSet.
 339          */
 340         ActionSet* getActionSetfromString(std::string desc);
 341
 342         /**
 343          * API for adding an Action Set.
 344          * Callback is called when the response of PUT operation arrives.
 345          *
 346          * @param resource - resource pointer of the group resource
 347          * @param newActionSet - pointer of Action Set
 348          * @param callback - callback for PUT operation.
 349          *
 350          * @return OCStackResult - return value of this API.
 351          *                         It returns OC_STACK_OK if success.
 352          *
 353          * NOTE: OCStackResult is defined in ocstack.h.
 354          */
 355         OCStackResult addActionSet(std::shared_ptr< OCResource > resource,
 356                 const ActionSet* newActionSet, PutCallback cb);
 357
 358         /**
 359          * API for executing the Action Set.
 360          * Callback is called when the response of  POST operation arrives.
 361          *
 362          * @param resource - resource pointer of the group resource
 363          * @param actionsetName - Action Set name for executing the Action set
 364          * @param callback - callback for POST operation.
 365          *
 366          * @return OCStackResult - return value of this API.
 367          *                         It returns OC_STACK_OK if success.
 368          *
 369          * NOTE: OCStackResult is defined in ocstack.h.
 370          */
 371         OCStackResult executeActionSet(std::shared_ptr< OCResource > resource,
 372                 std::string actionsetName, PostCallback cb);
 373
 374         /**
 375          * API for reading the Action Set.
 376          * Callback is called when the response of  GET operation arrives.
 377          *
 378          * @param resource - resource pointer of the group resource
 379          * @param actionsetName - Action Set name for reading the Action set
 380          * @param callback - callback for GET operation.
 381          *
 382          * @return OCStackResult - return value of this API.
 383          *                         It returns OC_STACK_OK if success.
 384          *
 385          * NOTE: OCStackResult is defined in ocstack.h.
 386          */
 387         OCStackResult getActionSet(std::shared_ptr< OCResource > resource,
 388                 std::string actionsetName, GetCallback cb);
 389
 390         /**
 391          * API for removing the Action Set.
 392          * Callback is called when the response of  POST operation arrives.
 393          *
 394          * @param resource - resource pointer of the group resource
 395          * @param actionsetName - Action Set name for removing the Action set
 396          * @param callback - callback for POST operation.
 397          *
 398          * @return OCStackResult - return value of this API.
 399          *                         It returns OC_STACK_OK if success.
 400          *
 401          * NOTE: OCStackResult is defined in ocstack.h.
 402          */
 403         OCStackResult deleteActionSet(std::shared_ptr< OCResource > resource,
 404                 std::string actionsetName, PostCallback);
 405
 406     };
 407 }
 408 #endif  /* __OC_THINGSMANAGER__*/