service/scene-manager/include/RemoteScene.h

   1 //******************************************************************
   2 //
   3 // Copyright 2016 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 #ifndef SM_REMOTE_SCENE_H_
  22 #define SM_REMOTE_SCENE_H_
  23
  24 #include <memory>
  25 #include <string>
  26 #include <unordered_map>
  27 #include <mutex>
  28
  29 #include "RemoteSceneAction.h"
  30 #include "RCSRemoteResourceObject.h"
  31
  32 namespace OIC
  33 {
  34     namespace Service
  35     {
  36         class SceneCollectionResourceRequestor;
  37         class SceneMemberResourceRequestor;
  38
  39         /*
  40         * @class RemoteScene
  41         *
  42         * @brief RemoteScene class is an interface class to send a request to a Scene provided by
  43         * SceneCollection resource on remote side. This class provides APIs for adding new
  44         * SceneAction to the Scene and creating a new SceneAction instance, retrieving all
  45         * SceneAction instances created before. And it also provides an API to execute a Scene
  46         * on remote side.
  47         */
  48         class RemoteScene
  49         {
  50             public:
  51                 typedef std::shared_ptr< RemoteScene > Ptr;
  52
  53                 /**
  54                 * Callback definition to be invoked a the response of addNewSceneAction is
  55                 * received.
  56                 *
  57                 * @param action created RemoteSceneAction instance pointer
  58                 * @param eCode the error code received
  59                 *
  60                 * @note Error code '200' stands for success, '400' for bad request,
  61                 * and '500' for internal error.
  62                 *
  63                 * @see addNewSceneAction
  64                 */
  65                 typedef std::function< void(RemoteSceneAction::Ptr action, int eCode) >
  66                     AddNewSceneActionCallback;
  67
  68                 /**
  69                 * Callback definition to be invoked when a response of execute is
  70                 * received.
  71                 *
  72                 * @param sceneName name of the scene which is executed
  73                 * @param eCode the error code received
  74                 *
  75                 * @note Error code '200' stands for success, '400' for bad request,
  76                 * and '500' for internal error.
  77                 *
  78                 * @see execute
  79                 */
  80                 typedef std::function< void(const std::string &sceneName, int eCode) >
  81                     RemoteSceneExecuteCallback;
  82
  83             public:
  84                 ~RemoteScene() = default;
  85
  86                 /**
  87                 * Requests to add new SceneAction to the Scene on remote side and
  88                 * creates RemoteSceneAction instance corresponding to the created SceneAction.
  89                 *
  90                 * @param targetResource A pointer of discovered resource
  91                 * @param attrs AttributeS to set when the Scene executed
  92                 * @param cb A callback to receive created RemoteSceneAction instance
  93                 *
  94                 * @throws RCSInvalidParameterException If parameter is invalid.
  95                 * @throws PlatformException If the platform operation failed
  96                 *
  97                 * @note RemoteSceneAction instance is only produced by RemoteScene class
  98                 *
  99                 * @see RCSResourceAttributes
 100                 */
 101                 void addNewSceneAction(RCSRemoteResourceObject::Ptr targetResource,
 102                     const RCSResourceAttributes &attrs, AddNewSceneActionCallback cb);
 103
 104                 /**
 105                 * Requests to add new SceneAction to the Scene on remote side and
 106                 * creates RemoteSceneAction instance corresponding to the created SceneAction.
 107                 *
 108                 * @param targetResource A pointer of discovered resource
 109                 * @param key A key of an attribute
 110                 * @param value A value to be mapped against the key
 111                 * @param cb A callback to receive created RemoteSceneAction instance
 112                 *
 113                 * @throws RCSInvalidParameterException If parameter is invalid.
 114                 * @throws PlatformException If the platform operation failed
 115                 *
 116                 * @note RemoteSceneAction instance is only produced by RemoteScene class
 117                 *
 118                 * @see RCSResourceAttributes::Value
 119                 */
 120                 void addNewSceneAction(RCSRemoteResourceObject::Ptr targetResource,
 121                                        const std::string &key,
 122                                        const RCSResourceAttributes::Value &value,
 123                                        AddNewSceneActionCallback cb);
 124
 125                 /**
 126                 * Gets all RemoteSceneAction instances included in the Scene.
 127                 *
 128                 * @return A vector of shared pointer of RemoteSceneAction instances
 129                 */
 130                 std::vector< RemoteSceneAction::Ptr > getRemoteSceneActions() const;
 131
 132                 /**
 133                 * Gets RemoteSceneAction instance by using a certain discovered resource.
 134                 *
 135                 * @param targetResource A pointer of discovered resource
 136                 *
 137                 * @return A shared pointer of RemoteSceneAction instance
 138                 *
 139                 * @throws RCSInvalidParameterException If targetResource is invalid
 140                 */
 141                 RemoteSceneAction::Ptr getRemoteSceneAction(
 142                     const RCSRemoteResourceObject::Ptr targetResource) const;
 143
 144                 /**
 145                 * Gets a name attribute of the Scene.
 146                 *
 147                 * @return A name of the Scene
 148                 */
 149                 std::string getName() const;
 150
 151                 /**
 152                 * Requests to execute the Scene on remote side.
 153                 *
 154                 * @param cb A callback to receive result of Scene execution
 155                 *
 156                 * @throws RCSInvalidParameterException If callback is null
 157                 * @throws PlatformException If the platform operation failed
 158                 */
 159                 void execute(RemoteSceneExecuteCallback cb);
 160
 161             private:
 162                 RemoteScene(
 163                     const std::string &name, std::shared_ptr< SceneCollectionResourceRequestor >);
 164
 165                 RemoteSceneAction::Ptr createRemoteSceneAction(
 166                     const std::string &,  const RCSResourceAttributes &);
 167
 168                 void addExistingRemoteSceneAction(const std::string &, const std::string &,
 169                     RCSRemoteResourceObject::Ptr, const std::string &key,
 170                     const RCSResourceAttributes::Value &);
 171
 172                 void onSceneActionAdded(
 173                     int, RCSRemoteResourceObject::Ptr,
 174                     const RCSResourceAttributes &, const AddNewSceneActionCallback &);
 175
 176                 void onSceneExecuted(const std::string &name, int,
 177                                     const RemoteSceneExecuteCallback &);
 178
 179             private:
 180                 std::string m_name;
 181                 mutable std::mutex m_sceneActionLock;
 182                 std::unordered_map < std::string, RemoteSceneAction::Ptr >
 183                     m_remoteSceneActions;
 184
 185                 std::shared_ptr< SceneCollectionResourceRequestor > m_requestor;
 186
 187                 friend class RemoteSceneCollection;
 188         };
 189
 190     }
 191 }
 192
 193 #endif /* SM_REMOTE_SCENE_H_ */