Add documentation for Scene class.

Jojo-1000 · Moritz Wirger
1 parent 2578f2b7
Showing 7 changed files with 175 additions and 7 deletions
include/hueplusplus/Hue.h
include/hueplusplus/HueLight.h
include/hueplusplus/ModelPictures.h
include/hueplusplus/ResourceList.h
include/hueplusplus/Scene.h
include/hueplusplus/Schedule.h
src/TimePattern.cpp
@@ -324,7 +324,7 @@ public:
     bool scheduleExists(int id) const;
     //! \brief Create a new schedule.
-    //! \param params CreateSchedule parameters for the new group.
+    //! \param params CreateSchedule parameters for the new schedule.
     //! \returns The new schedule id or 0 if failed.
     //! \throws std::system_error when system or socket operations fail
     //! \throws HueException when response contains no body
@@ -336,12 +336,37 @@ public:
     ///! \name Scenes
     ///@{
+    //! \brief Get all scenes on this bridge.
+    //! \return A vector of references to every Scene.
+    //! \throws std::system_error when system or socket operations fail
+    //! \throws HueException when response contains no body
+    //! \throws HueAPIResponseException when response contains an error
+    //! \throws nlohmann::json::parse_error when response could not be parsed
     std::vector<std::reference_wrapper<Scene>> getAllScenes();
+    //! \brief Get scene specified by id.
+    //! \param id ID of the scene.
+    //! \returns Schedule that can be modified.
+    //! \throws std::system_error when system or socket operations fail
+    //! \throws HueException when id does not exist
+    //! \throws HueAPIResponseException when response contains an error
+    //! \throws nlohmann::json::parse_error when response could not be parsed
     Scene& getScene(const std::string& id);
+
+    //! \brief Checks whether a scene exists.
+    //! \param id ID of the scene.
+    //! \returns true when the scene exists.
+    //! \note Does not refresh the cached state.
     bool sceneExists(const std::string& id) const;
+    //! \brief Create a new scene.
+    //! \param params CreateScene parameters for the new scene.
+    //! \returns The new scene id or 0 if failed.
+    //! \throws std::system_error when system or socket operations fail
+    //! \throws HueException when response contains no body
+    //! \throws HueAPIResponseException when response contains an error
+    //! \throws nlohmann::json::parse_error when response could not be parsed
     std::string createScene(const CreateScene& params);
     ///@}
@@ -201,6 +201,8 @@ public:
     //! \return ColorType containig the color type of the light
     virtual ColorType getColorType() const;
+    //! \brief Get gamut space of possible light colors
+    //! \returns Used gamut, or \ref gamut::maxGamut when unknown.
     ColorGamut getColorGamut() const;
     ///@}
@@ -30,7 +30,7 @@ namespace hueplusplus
     //!
     //! \note This function will only return the filename without extension,
     //! because Philips provides different file types.
-    //! \param model_id Model Id of a device to get the picture of 
+    //! \param modelId Model Id of a device to get the picture of 
     //! \returns String that either contains the filename of the picture of the device 
     //! or an empty string if it was not found.
     std::string getPictureOfModel(const std::string& modelId);
@@ -73,7 +73,7 @@ public:
     //! \brief Deleted copy constructor
     ResourceList(const ResourceList&) = delete;
     //! \brief Defaulted move constructor
-    ResourceList(ResourceList&&) noexcept = default;
+    ResourceList(ResourceList&&) = default;
     //! \brief Deleted copy assignment
     ResourceList& operator=(const ResourceList&) = delete;
     //! \brief Defaulted move assignment
@@ -276,6 +276,10 @@ public:
     }
 };
+//! \brief Handles a group list with the special group 0
+//! \tparam Resource Resource type that is in the list
+//! \tparam CreateType Type that provides parameters for creation.
+//! Must have a const getRequest() function returning the JSON for the POST request.
 template <typename Resource, typename CreateType>
 class GroupResourceList : public CreateableResourceList<Resource, int, CreateType>
 {
@@ -38,30 +38,53 @@ namespace hueplusplus
 class LightState
 {
 public:
+    //! \brief Create LightState from json
+    //! \note Use LightStateBuilder for easier creation.
     explicit LightState(const nlohmann::json& state);
+    //! \brief Get whether the light is on
     bool isOn() const;
+    //! \brief Get whether a brightness is stored
     bool hasBrightness() const;
+    //! \brief Get brightness of the light
+    //! \returns Stored brightness, or 0
     int getBrightness() const;
+    //! \brief Get whether hue and saturation is stored
     bool hasHueSat() const;
+    //! \brief Get hue and saturation of the light
+    //! \returns Stored hue and saturation, or {0,0} if not stored
     HueSaturation getHueSat() const;
+    //! \brief Get whether xy color is stored
     bool hasXY() const;
+    //! \brief Get xy color of the light
+    //! \returns Stored x,y and brightness, or zeros if not stored
     XYBrightness getXY() const;
+    //! \brief Get whether color temperature is stored
     bool hasCt() const;
+    //! \brief Get color temperature of the light
+    //! \returns Stored color temperature in mired, or 0 if not stored
     int getCt() const;
+    //! \brief Get whether effect is stored
     bool hasEffect() const;
+    //! \brief Get whether colorloop effect is active
+    //! \returns true when colorloop is enabled, false otherwise or if not stored
     bool getColorloop() const;
+    //! \brief Get transition time to this light state
+    //! \returns Stored transition time or 4 by default
     int getTransitionTime() const;
+    //! \brief Convert to json representation
     nlohmann::json toJson() const;
+    //! \brief Equality comparison
     bool operator==(const LightState& other) const;
+    //! \brief Inequality comparison
     bool operator!=(const LightState& other) const;
 private:
@@ -86,51 +109,140 @@ private:
     nlohmann::json state;
 };
+//! \brief Scene stored in the bridge
+//!
+//! Scenes bundle the state of multiple lights so it can be recalled later.
 class Scene
 {
 public:
+    //! \brief Type of the scen
     enum class Type
     {
-        lightScene,
-        groupScene
+        lightScene, //!< The scene affects specific lights
+        groupScene //!< The scene affects all light of a specific group
     };
 public:
+    //! \brief Construct existing Scene
+    //! \param id Scene id
+    //! \param commands HueCommandAPI for requests
+    //! \param refreshDuration Time between refreshing the cached state
     Scene(const std::string& id, const HueCommandAPI& commands, std::chrono::steady_clock::duration refreshDuration);
+    //! \brief Refreshes internal cached state
+    //! \throws std::system_error when system or socket operations fail
+    //! \throws HueException when response contained no body
+    //! \throws HueAPIResponseException when response contains an error
+    //! \throws nlohmann::json::parse_error when response could not be parsed
     void refresh();
+
+    //! \brief Get scene identifier
     std::string getId() const;
+    //! \brief Get scene name
+    //!
+    //! The scene name is always unique for the bridge. It defaults to the id.
     std::string getName() const;
+    //! \brief Set scene name
+    //! \param name New name for the scene.
+    //! Must be unique for all schedules, otherwise a number is added.
+    //! \throws std::system_error when system or socket operations fail
+    //! \throws HueException when response contained no body
+    //! \throws HueAPIResponseException when response contains an error
+    //! \throws nlohmann::json::parse_error when response could not be parsed
     void setName(const std::string& name);
-
+    //! \brief Get scene type
+    //!
+    //! GroupScenes are deleted when the group is deleted.
     Type getType() const;
+    //! \brief Get group id for a GroupScene
+    //! \returns Group id or 0 if the scene is a LightScene.
     int getGroupId() const;
+    //! \brief Get light ids
+    //!
+    //! For a GroupScene, the light ids are the lights in the group.
     std::vector<int> getLightIds() const;
+    //! \brief Set light ids for LightScene
+    //! \param ids New light ids
+    //!
+    //! Light ids cannot be changed on GroupScene. Change the lights in the group instead.
+    //! \throws std::system_error when system or socket operations fail
+    //! \throws HueException when response contained no body
+    //! \throws HueAPIResponseException when response contains an error
+    //! \throws nlohmann::json::parse_error when response could not be parsed
     void setLightIds(const std::vector<int>& ids);
+    //! \brief Get user that created or last changed the scene.
     std::string getOwner() const;
+    //! \brief Get whether the scene can be automatically deleted
     bool getRecycle() const;
+    //! \brief Get whether scene is locked by a rule or schedule
     bool isLocked() const;
+    //! \brief Get app specific data
     std::string getAppdata() const;
+    //! \brief Get version of app specific data
     int getAppdataVersion() const;
+    //! \brief Set app specific data
+    //! \param data Custom data in any format, max length 16.
+    //! \param version Version of the data
+    //! \throws std::system_error when system or socket operations fail
+    //! \throws HueException when response contained no body
+    //! \throws HueAPIResponseException when response contains an error
+    //! \throws nlohmann::json::parse_error when response could not be parsed
     void setAppdata(const std::string& data, int version);
+    //! \brief Get picture, reserved for future use.
+    //!
+    //! Currently always an empty string.
     std::string getPicture() const;
+    //! \brief Get time the scene was created/updated.
     time::AbsoluteTime getLastUpdated() const;
+    //! \brief Get version of the scene
+    //! \returns 1 for legacy scene without lightstates
+    //! \returns 2 for updated scenes with lightstates
     int getVersion() const;
+    //! \brief Get stored states of the lights
+    //! \returns LightStates for each light in the scene, or an empty map for legacy scenes.
     std::map<int, LightState> getLightStates() const;
+    //! \brief Set light states
+    //! \param states New states for each light in the scene.
+    //! Should contain exactly the lights in the scene. Additional states might cause an error.
+    //! \throws std::system_error when system or socket operations fail
+    //! \throws HueException when response contained no body
+    //! \throws HueAPIResponseException when response contains an error
+    //! \throws nlohmann::json::parse_error when response could not be parsed
     void setLightStates(const std::map<int, LightState>& states);
+    //! \brief Store current light state of every light in the scene
+    //! \throws std::system_error when system or socket operations fail
+    //! \throws HueException when response contained no body
+    //! \throws HueAPIResponseException when response contains an error
+    //! \throws nlohmann::json::parse_error when response could not be parsed
     void storeCurrentLightState();
+    //! \brief Store current light state and update transition time
+    //! \param transition The updated transition time to this scene
+    //! \throws std::system_error when system or socket operations fail
+    //! \throws HueException when response contained no body
+    //! \throws HueAPIResponseException when response contains an error
+    //! \throws nlohmann::json::parse_error when response could not be parsed
     void storeCurrentLightState(int transition);
+    //! \brief Recall scene, putting every light in the stored state
+    //! \throws std::system_error when system or socket operations fail
+    //! \throws HueException when response contained no body
+    //! \throws HueAPIResponseException when response contains an error
+    //! \throws nlohmann::json::parse_error when response could not be parsed
     void recall();
 private:
+    //! \brief Send put request to specified sub path
+    //! \throws std::system_error when system or socket operations fail
+    //! \throws HueException when response contained no body
+    //! \throws HueAPIResponseException when response contains an error
+    //! \throws nlohmann::json::parse_error when response could not be parsed
     void sendPutRequest(const std::string& path, const nlohmann::json& request, FileInfo fileInfo);
 private:
@@ -138,16 +250,40 @@ private:
     APICache state;
 };
+//! \brief Parameters for creating a new Scene
+//!
+//! Can be used like a builder object with chained calls.
 class CreateScene
 {
 public:
+    //! \brief Set name
+    //! \see Scene::setName
     CreateScene& setName(const std::string& name);
+    //! \brief Set group id, making the scene a GroupScene
+    //! \param id Group id for the scene, not 0
+    //!
+    //! The group id cannot be changed after the scene was created.
+    //! \throws HueException when used after setLightIds
     CreateScene& setGroupId(int id);
+    //! \brief Set light ids, making the scene a LightScene
+    //! \param ids Ids of lights in the scene
+    //! \throws HueException when used after setGroupId
     CreateScene& setLightIds(const std::vector<int>& ids);
+    //! \brief Set whether the scene can be automatically deleted
+    //!
+    //! Cannot be changed after the scene was created.
     CreateScene& setRecycle(bool recycle);
+    //! \brief Set app specific data
+    //! \see Scene::setAppdata
     CreateScene& setAppdata(const std::string& data, int version);
+    //! \brief Set light states of the scene
+    //!
+    //! When omitted, the current light states are stored.
+    //! \see Scene::setLightStates
     CreateScene& setLightStates(const std::map<int, LightState>& states);
+    //! \brief Get request to create the scene.
+    //! \returns JSON request for a POST to create the new scene
     nlohmann::json getRequest() const;
 private:
@@ -212,6 +212,8 @@ public:
     //! When recycle is true, it is deleted when no resourcelinks refer to it.
     CreateSchedule& setRecycle(bool recycle);
+    //! \brief Get request to create the schedule.
+//! \returns JSON request for a POST to create the new schedule
     nlohmann::json getRequest() const;
 private:
@@ -90,7 +90,6 @@ std::chrono::system_clock::time_point parseUTCTimestamp(const std::string&amp; times
     // (also not officially thread-safe, but none of the time functions are)
     // Set local timezone to UTC and then set it back
     char* tz = std::getenv("TZ");
-    std::time_t ctime = std::mktime(&tm);
     if (tz)
     {
         tz = strdup(tz);