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