From 2f28783458c773dae5870a12c9763e7bc4443ba4 Mon Sep 17 00:00:00 2001 From: Jojo-1000 <33495614+Jojo-1000@users.noreply.github.com> Date: Sun, 24 May 2020 17:21:17 +0200 Subject: [PATCH] Add documentation for Scene class. --- include/hueplusplus/Hue.h | 27 ++++++++++++++++++++++++++- include/hueplusplus/HueLight.h | 2 ++ include/hueplusplus/ModelPictures.h | 2 +- include/hueplusplus/ResourceList.h | 6 +++++- include/hueplusplus/Scene.h | 142 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++--- include/hueplusplus/Schedule.h | 2 ++ src/TimePattern.cpp | 1 - 7 files changed, 175 insertions(+), 7 deletions(-) diff --git a/include/hueplusplus/Hue.h b/include/hueplusplus/Hue.h index aa122e2..d652387 100644 --- a/include/hueplusplus/Hue.h +++ b/include/hueplusplus/Hue.h @@ -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> 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); ///@} diff --git a/include/hueplusplus/HueLight.h b/include/hueplusplus/HueLight.h index ff8f0e8..00907ab 100644 --- a/include/hueplusplus/HueLight.h +++ b/include/hueplusplus/HueLight.h @@ -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; ///@} diff --git a/include/hueplusplus/ModelPictures.h b/include/hueplusplus/ModelPictures.h index 411c9fc..6fad834 100644 --- a/include/hueplusplus/ModelPictures.h +++ b/include/hueplusplus/ModelPictures.h @@ -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); diff --git a/include/hueplusplus/ResourceList.h b/include/hueplusplus/ResourceList.h index 5024c09..952b0a8 100644 --- a/include/hueplusplus/ResourceList.h +++ b/include/hueplusplus/ResourceList.h @@ -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 class GroupResourceList : public CreateableResourceList { diff --git a/include/hueplusplus/Scene.h b/include/hueplusplus/Scene.h index cb0ae79..b8a68e6 100644 --- a/include/hueplusplus/Scene.h +++ b/include/hueplusplus/Scene.h @@ -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 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& 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 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& 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& 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& states); + //! \brief Get request to create the scene. + //! \returns JSON request for a POST to create the new scene nlohmann::json getRequest() const; private: diff --git a/include/hueplusplus/Schedule.h b/include/hueplusplus/Schedule.h index 17785bc..b422546 100644 --- a/include/hueplusplus/Schedule.h +++ b/include/hueplusplus/Schedule.h @@ -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: diff --git a/src/TimePattern.cpp b/src/TimePattern.cpp index 239c737..3622afa 100644 --- a/src/TimePattern.cpp +++ b/src/TimePattern.cpp @@ -90,7 +90,6 @@ std::chrono::system_clock::time_point parseUTCTimestamp(const std::string& 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); -- libgit2 0.21.4