diff --git a/hueplusplus/Hue.cpp b/hueplusplus/Hue.cpp index 9a4b547..fee5e16 100644 --- a/hueplusplus/Hue.cpp +++ b/hueplusplus/Hue.cpp @@ -202,6 +202,10 @@ std::string Hue::requestUsername(const std::string& ip) { std::cout << "Link button not pressed!\n"; } + else + { + throw; + } } std::this_thread::sleep_until(lastCheck + std::chrono::seconds(1)); } diff --git a/hueplusplus/include/BaseHttpHandler.h b/hueplusplus/include/BaseHttpHandler.h index 6ed6562..305a853 100644 --- a/hueplusplus/include/BaseHttpHandler.h +++ b/hueplusplus/include/BaseHttpHandler.h @@ -40,15 +40,6 @@ public: //! \brief Virtual dtor virtual ~BaseHttpHandler() = default; - //! \brief Send a message to a specified host and return the response. - //! - //! \param msg The message that should be sent to the specified address - //! \param adr Ip or hostname in dotted decimal notation like "192.168.2.1" - //! \param port Optional port the request is sent to, default is 80 - //! \return The response of the host as a string - //! \throws std::system_error when system or socket operations fail - virtual std::string send(const std::string& msg, const std::string& adr, int port = 80) const = 0; - //! \brief Send a message to a specified host and return the body of the response. //! //! \param msg The message that should sent to the specified address @@ -57,21 +48,7 @@ public: //! \return The body of the response of the host as a string //! \throws std::system_error when system or socket operations fail //! \throws HueException when response contained no body - virtual std::string sendGetHTTPBody(const std::string& msg, const std::string& adr, int port = 80) const; - - //! \brief Send a multicast request with a specified message. - //! - //! \param msg The message that should sent to the specified multicast address - //! \param adr Optional ip or hostname in dotted decimal notation, default is "239.255.255.250" - //! \param port Optional port the request is sent to, default is 1900 - //! \param timeout Optional time to wait for responses in seconds, default is 5 - //! - //! Blocks for the duration of the timeout. - //! - //! \return vector of strings containing each received answer - //! \throws std::system_error when system or socket operations fail - virtual std::vector sendMulticast( - const std::string& msg, const std::string& adr = "239.255.255.250", int port = 1900, int timeout = 5) const = 0; + std::string sendGetHTTPBody(const std::string& msg, const std::string& adr, int port = 80) const override; //! \brief Send a HTTP request with the given method to the specified host and return the body of the response. //! @@ -84,8 +61,8 @@ public: //! \return Body of the response of the host //! \throws std::system_error when system or socket operations fail //! \throws HueException when response contained no body - virtual std::string sendHTTPRequest(const std::string& method, const std::string& uri, - const std::string& contentType, const std::string& body, const std::string& adr, int port = 80) const; + std::string sendHTTPRequest(const std::string& method, const std::string& uri, const std::string& contentType, + const std::string& body, const std::string& adr, int port = 80) const override; //! \brief Send a HTTP GET request to the specified host and return the body of the response. //! @@ -98,8 +75,8 @@ public: //! \return Body of the response of the host //! \throws std::system_error when system or socket operations fail //! \throws HueException when response contained no body - virtual std::string GETString(const std::string& uri, const std::string& contentType, const std::string& body, - const std::string& adr, int port = 80) const; + std::string GETString(const std::string& uri, const std::string& contentType, const std::string& body, + const std::string& adr, int port = 80) const override; //! \brief Send a HTTP POST request to the specified host and return the body of the response. //! @@ -112,8 +89,8 @@ public: //! \return Body of the response of the host //! \throws std::system_error when system or socket operations fail //! \throws HueException when response contained no body - virtual std::string POSTString(const std::string& uri, const std::string& contentType, const std::string& body, - const std::string& adr, int port = 80) const; + std::string POSTString(const std::string& uri, const std::string& contentType, const std::string& body, + const std::string& adr, int port = 80) const override; //! \brief Send a HTTP PUT request to the specified host and return the body of the response. //! @@ -126,8 +103,8 @@ public: //! \return Body of the response of the host //! \throws std::system_error when system or socket operations fail //! \throws HueException when response contained no body - virtual std::string PUTString(const std::string& uri, const std::string& contentType, const std::string& body, - const std::string& adr, int port = 80) const; + std::string PUTString(const std::string& uri, const std::string& contentType, const std::string& body, + const std::string& adr, int port = 80) const override; //! \brief Send a HTTP DELETE request to the specified host and return the body of the response. //! @@ -140,8 +117,8 @@ public: //! \return Body of the response of the host //! \throws std::system_error when system or socket operations fail //! \throws HueException when response contained no body - virtual std::string DELETEString(const std::string& uri, const std::string& contentType, const std::string& body, - const std::string& adr, int port = 80) const; + std::string DELETEString(const std::string& uri, const std::string& contentType, const std::string& body, + const std::string& adr, int port = 80) const override; //! \brief Send a HTTP GET request to the specified host and return the body of the response parsed as JSON. //! @@ -153,8 +130,8 @@ public: //! \throws std::system_error when system or socket operations fail //! \throws HueException when response contained no body //! \throws nlohmann::json::parse_error when the body could not be parsed - virtual nlohmann::json GETJson( - const std::string& uri, const nlohmann::json& body, const std::string& adr, int port = 80) const; + nlohmann::json GETJson( + const std::string& uri, const nlohmann::json& body, const std::string& adr, int port = 80) const override; //! \brief Send a HTTP POST request to the specified host and return the body of the response parsed as JSON. //! @@ -166,8 +143,8 @@ public: //! \throws std::system_error when system or socket operations fail //! \throws HueException when response contained no body //! \throws nlohmann::json::parse_error when the body could not be parsed - virtual nlohmann::json POSTJson( - const std::string& uri, const nlohmann::json& body, const std::string& adr, int port = 80) const; + nlohmann::json POSTJson( + const std::string& uri, const nlohmann::json& body, const std::string& adr, int port = 80) const override; //! \brief Send a HTTP PUT request to the specified host and return the body of the response parsed as JSON. //! @@ -179,8 +156,8 @@ public: //! \throws std::system_error when system or socket operations fail //! \throws HueException when response contained no body //! \throws nlohmann::json::parse_error when the body could not be parsed - virtual nlohmann::json PUTJson( - const std::string& uri, const nlohmann::json& body, const std::string& adr, int port = 80) const; + nlohmann::json PUTJson( + const std::string& uri, const nlohmann::json& body, const std::string& adr, int port = 80) const override; //! \brief Send a HTTP DELETE request to the specified host and return the body of the response parsed as JSON. //! @@ -192,8 +169,8 @@ public: //! \throws std::system_error when system or socket operations fail //! \throws HueException when response contained no body //! \throws nlohmann::json::parse_error when the body could not be parsed - virtual nlohmann::json DELETEJson( - const std::string& uri, const nlohmann::json& body, const std::string& adr, int port = 80) const; + nlohmann::json DELETEJson( + const std::string& uri, const nlohmann::json& body, const std::string& adr, int port = 80) const override; }; #endif diff --git a/hueplusplus/include/Hue.h b/hueplusplus/include/Hue.h index a5b33e2..18cda3a 100644 --- a/hueplusplus/include/Hue.h +++ b/hueplusplus/include/Hue.h @@ -57,21 +57,25 @@ public: public: //! \brief Constructor of HueFinder class //! - //! \param handler HttpHandler of type \ref IHttpHandler for communication - //! with the bridge + //! \param handler HttpHandler of type \ref IHttpHandler for communication with the bridge HueFinder(std::shared_ptr handler); - //! \brief Function that finds all bridges in the network and returns them. + //! \brief Finds all bridges in the network and returns them. //! - //! The user should be given the opportunity to select the correct one based - //! on the mac address. \return vector containing ip and mac of all found - //! bridges + //! The user should be given the opportunity to select the correct one based on the mac address. + //! \return vector containing ip and mac of all found bridges + //! \throws std::system_error when system or socket operations fail + //! \throws HueException when response contained no body std::vector FindBridges() const; - //! \brief Function that gets a \ref Hue bridge based on its identification + //! \brief Gets a \ref Hue bridge based on its identification //! //! \param identification \ref HueIdentification that specifies a bridge //! \return \ref Hue class object + //! \throws std::system_error when system or socket operations fail + //! \throws HueException when response contained no body or username could not be requested + //! \throws HueAPIResponseException when response contains an error + //! \throws nlohmann::json::parse_error when response could not be parsed Hue GetBridge(const HueIdentification& identification); //! \brief Function that adds a username to the \ref usernames map @@ -88,15 +92,14 @@ public: const std::map& GetAllUsernames() const; //! \brief Normalizes mac address to plain hex number. - //! \returns \p input without separators and whitespace, in upper case. + //! \returns \p input without separators and whitespace, in lower case. static std::string NormalizeMac(std::string input); private: //! \brief Parses mac address from description.xml //! - //! \param description Content of description.xml file as returned by GET - //! request. \returns Content of xml element \c serialNumber if description - //! matches a Hue bridge, otherwise an empty string. + //! \param description Content of description.xml file as returned by GET request. + //! \returns Content of xml element \c serialNumber if description matches a Hue bridge, otherwise an empty string. static std::string ParseDescription(const std::string& description); std::map usernames; //!< Maps all macs to usernames added by \ref @@ -129,15 +132,18 @@ public: //! \return integer containing port int getBridgePort(); - //! \brief Function that sends a username request to the Hue bridge. + //! \brief Send a username request to the Hue bridge. //! - //! It does that for about 30 seconds and you have 5 seconds to prepare - //! It automatically sets the \ref username variable according to the username - //! received and returns the username received This function should only be - //! called once to acquire a username to control the bridge and the username - //! should be saved for future use \param ip String that specifies the ip (in - //! dotted decimal notation like "192.168.2.1") the request is send to \return - //! String containing username + //! Blocks for about 30 seconds and 5 seconds to prepare. + //! It automatically sets the \ref username variable according to the username received and returns the username received. + //! This function should only be called once to acquire a username to control the bridge and the username + //! should be saved for future use. + //! \param ip String that specifies the ip (in dotted decimal notation like "192.168.2.1") the request is send to + //! \return username for API usage + //! \throws std::system_error when system or socket operations fail + //! \throws HueException when response contained no body + //! \throws HueAPIResponseException when response contains an error except link button not pressed. + //! \throws nlohmann::json::parse_error when response could not be parsed std::string requestUsername(const std::string& ip); //! \brief Function that returns the \ref username @@ -147,8 +153,7 @@ public: //! \brief Function to set the ip address of this class representing a bridge //! - //! \param ip String that specifies the ip in dotted decimal notation like - //! "192.168.2.1" + //! \param ip String that specifies the ip in dotted decimal notation like "192.168.2.1" void setIP(const std::string& ip); //! \brief Function to set the port of this class representing a bridge @@ -161,17 +166,24 @@ public: //! //! \param id Integer that specifies the ID of a Hue light //! \return \ref HueLight that can be controlled + //! \throws std::system_error when system or socket operations fail + //! \throws HueException when id does not exist or type is unknown + //! \throws HueAPIResponseException when response contains an error + //! \throws nlohmann::json::parse_error when response could not be parsed HueLight& getLight(int id); //! \brief Function to remove a light from the bridge //! - //! \attention Any use of the light after it was successfully removed results - //! in undefined behavior \param id Id of the light to remove \return Bool - //! that is true on success + //! \attention Any use of the light after it was successfully removed results in undefined behavior + //! \param id Id of the light to remove + //! \return true on success + //! \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 bool removeLight(int id); - //! \brief Function that returns all light types that are associated with this - //! bridge + //! \brief Function that returns all light types that are associated with this bridge //! //! \return A map mapping light id's to light types for every light // const std::map& getAllLightTypes(); @@ -180,15 +192,21 @@ public: //! bridge //! //! \return A vector containing references to every HueLight + //! \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> getAllLights(); - //! \brief Function that tells whether a given light id represents an existing - //! light + //! \brief Function that tells whether a given light id represents an existing light //! //! Calls refreshState to update the local bridge state //! \param id Id of a light to check for existance - //! \return Bool that is true when a light with the given id exists and false - //! when not + //! \return Bool that is true when a light with the given id exists and false when not + //! \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 bool lightExists(int id); //! \brief Const function that tells whether a given light id represents an @@ -231,6 +249,10 @@ public: private: //! \brief Function that refreshes the local \ref state of the Hue bridge + //! \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 refreshState(); private: diff --git a/hueplusplus/include/HueCommandAPI.h b/hueplusplus/include/HueCommandAPI.h index e3e40fd..66de931 100644 --- a/hueplusplus/include/HueCommandAPI.h +++ b/hueplusplus/include/HueCommandAPI.h @@ -37,62 +37,59 @@ class HueCommandAPI public: //! \brief Construct from ip, username and HttpHandler //! - //! \param ip String that specifies the ip address of the Hue bridge in dotted - //! decimal notation like "192.168.2.1" \param port of the hue bridge - //! \param username String that specifies the username that is used to control - //! the bridge \param handler HttpHandler of type \ref IHttpHandler for - //! communication with the bridge - HueCommandAPI(const std::string& ip, const int port, const std::string& username, - std::shared_ptr httpHandler); + //! \param ip ip address of the Hue bridge in dotted decimal notation like "192.168.2.1" + //! \param username username that is used to control the bridge + //! \param port of the hue bridge + //! \param handler HttpHandler for communication with the bridge + HueCommandAPI(const std::string& ip, const std::string& username, std::shared_ptr httpHandler); //! \brief Copy construct from other HueCommandAPI - //! \note All copies refer to the same timeout data, so even calls from - //! different objects will be delayed + //! \note All copies refer to the same timeout data, so even calls from different objects will be delayed HueCommandAPI(const HueCommandAPI&) = default; //! \brief Move construct from other HueCommandAPI - //! \note All copies refer to the same timeout data, so even calls from - //! different objects will be delayed + //! \note All copies refer to the same timeout data, so even calls from different objects will be delayed HueCommandAPI(HueCommandAPI&&) = default; //! \brief Copy assign from other HueCommandAPI - //! \note All copies refer to the same timeout data, so even calls from - //! different objects will be delayed + //! \note All copies refer to the same timeout data, so even calls from different objects will be delayed HueCommandAPI& operator=(const HueCommandAPI&) = default; //! \brief Move assign from other HueCommandAPI - //! \note All copies refer to the same timeout data, so even calls from - //! different objects will be delayed + //! \note All copies refer to the same timeout data, so even calls from different objects will be delayed HueCommandAPI& operator=(HueCommandAPI&&) = default; - //! \brief Sends a HTTP PUT request via the \ref httpHandler to the bridge and - //! returns the response + //! \brief Sends a HTTP PUT request via the \ref httpHandler to the bridge and returns the response //! - //! This function will block until at least \ref minDelay has passed to any - //! previous request \param path String that contains the request path - //! (appended after /api/) \param request Json value containing the - //! request. May be empty \returns The return value of the underlying \ref - //! IHttpHandler::PUTJson call + //! This function will block until at least \ref minDelay has passed to any previous request + //! \param path API request path (appended after /api/) + //! \param request Request to the api, may be empty + //! \returns The return value of the underlying \ref IHttpHandler::PUTJson call + //! \throws std::system_error when system or socket operations fail + //! \throws HueException when response contains no body + //! \throws HueAPIResponseException when response contains an error nlohmann::json PUTRequest(const std::string& path, const nlohmann::json& request) const; nlohmann::json PUTRequest(const std::string& path, const nlohmann::json& request, FileInfo fileInfo) const; - //! \brief Sends a HTTP GET request via the \ref httpHandler to the bridge and - //! returns the response + //! \brief Sends a HTTP GET request via the \ref httpHandler to the bridge and returns the response //! - //! This function will block until at least \ref minDelay has passed to any - //! previous request \param path String that contains the request path - //! (appended after /api/) \param request Json value containing the - //! request. May be empty \returns The return value of the underlying \ref - //! IHttpHandler::GETJson call + //! This function will block until at least \ref minDelay has passed to any previous request + //! \param path API request path (appended after /api/) + //! \param request Request to the api, may be empty + //! \returns The return value of the underlying \ref IHttpHandler::GETJson call + //! \throws std::system_error when system or socket operations fail + //! \throws HueException when response contains no body + //! \throws HueAPIResponseException when response contains an error nlohmann::json GETRequest(const std::string& path, const nlohmann::json& request) const; nlohmann::json GETRequest(const std::string& path, const nlohmann::json& request, FileInfo fileInfo) const; - //! \brief Sends a HTTP DELETE request via the \ref httpHandler to the bridge - //! and returns the response + //! \brief Sends a HTTP DELETE request via the \ref httpHandler to the bridge and returns the response //! - //! This function will block until at least \ref minDelay has passed to any - //! previous request \param path String that contains the request path - //! (appended after /api/) \param request Json value containing the - //! request. May be empty \returns The return value of the underlying \ref - //! IHttpHandler::DELETEJson call + //! This function will block until at least \ref minDelay has passed to any previous request + //! \param path API request path (appended after /api/) + //! \param request Request to the api, may be empty + //! \returns The return value of the underlying \ref IHttpHandler::DELETEJson call + //! \throws std::system_error when system or socket operations fail + //! \throws HueException when response contains no body + //! \throws HueAPIResponseException when response contains an error nlohmann::json DELETERequest(const std::string& path, const nlohmann::json& request) const; nlohmann::json DELETERequest(const std::string& path, const nlohmann::json& request, FileInfo fileInfo) const; @@ -104,9 +101,12 @@ private: }; //! \brief Throws an exception if response contains an error, passes though value + //! \throws HueAPIResponseException when response contains an error + //! \returns \ref response if there is no error nlohmann::json HandleError(FileInfo fileInfo, const nlohmann::json& response) const; //! \brief Combines path with api prefix and username + //! \returns "/api//" std::string CombinedPath(const std::string& path) const; private: diff --git a/hueplusplus/include/HueLight.h b/hueplusplus/include/HueLight.h index b65079a..8c144c9 100644 --- a/hueplusplus/include/HueLight.h +++ b/hueplusplus/include/HueLight.h @@ -106,19 +106,31 @@ public: //! \brief Function that turns the light on. //! - //! \param transition Optional parameter to set the transition from current - //! state to new, standard is 4 = 400ms \return Bool that is true on success + //! \param transition Optional parameter to set the transition from current state to new, standard is 4 = 400ms + //! \return true on success + //! \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 virtual bool On(uint8_t transition = 4); //! \brief Function that turns the light off. //! - //! \param transition Optional parameter to set the transition from current - //! state to new, standard is 4 = 400ms \return Bool that is true on success + //! \param transition Optional parameter to set the transition from current state to new, standard is 4 = 400ms + //! \return Bool that is true on success + //! \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 virtual bool Off(uint8_t transition = 4); //! \brief Function to check whether a light is on or off //! //! \return Bool that is true, when the light is on and false, when off + //! \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 virtual bool isOn(); //! \brief Const function to check whether a light is on or off @@ -140,6 +152,10 @@ public: //! \brief Function that returns the name of the light. //! //! \return String containig the name of the light + //! \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 virtual std::string getName(); //! \brief Const function that returns the name of the light. @@ -156,34 +172,34 @@ public: //! \brief Const function that returns the uniqueid of the light //! //! \note Only working on bridges with versions starting at 1.4 - //! \return String containing the uniqueid or an empty string when the - //! function is not supported + //! \return String containing the uniqueid or an empty string when the function is not supported virtual std::string getUId() const; //! \brief Const function that returns the manufacturername of the light //! //! \note Only working on bridges with versions starting at 1.7 - //! \return String containing the manufacturername or an empty string when the - //! function is not supported + //! \return String containing the manufacturername or an empty string when the function is not supported virtual std::string getManufacturername() const; //! \brief Const function that returns the productname of the light //! //! \note Only working on bridges with versions starting at 1.24 - //! \return String containing the productname or an empty string when the - //! function is not supported + //! \return String containing the productname or an empty string when the function is not supported virtual std::string getProductname() const; //! \brief Const function that returns the luminaireuniqueid of the light //! //! \note Only working on bridges with versions starting at 1.9 - //! \return String containing the luminaireuniqueid or an empty string when - //! the function is not supported + //! \return String containing the luminaireuniqueid or an empty string when the function is not supported virtual std::string getLuminaireUId() const; //! \brief Function that returns the software version of the light //! //! \return String containing the software version + //! \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 virtual std::string getSwVersion(); //! \brief Const function that returns the software version of the light @@ -195,6 +211,10 @@ public: //! \brief Function that sets the name of the light //! //! \return Bool that is true on success + //! \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 virtual bool setName(const std::string& name); //! \brief Const function that returns the color type of the light. @@ -237,9 +257,14 @@ public: //! //! \note The brightness will only be set if the light has a reference to a //! specific \ref BrightnessStrategy. The brightness can range from 0 = off to - //! 254 = fully lit. \param bri Unsigned int that specifies the brightness - //! \param transition Optional parameter to set the transition from current - //! state to new, standard is 4 = 400ms \return Bool that is true on success + //! 254 = fully lit. + //! \param bri Unsigned int that specifies the brightness + //! \param transition Optional parameter to set the transition from current state to new, standard is 4 = 400ms + //! \return Bool that is true on success + //! \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 virtual bool setBrightness(unsigned int bri, uint8_t transition = 4) { if (brightnessStrategy) @@ -268,7 +293,12 @@ public: //! //! \note The brightness will only be returned if the light has a reference to //! a specific \ref BrightnessStrategy. The brightness can range from 0 = off - //! to 254 = fully lit. \return Unsigned int that is 0 when function failed + //! to 254 = fully lit. + //! \return Unsigned int that is 0 when function failed + //! \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 virtual unsigned int getBrightness() { if (brightnessStrategy) @@ -282,10 +312,14 @@ public: //! //! \note The color temperature will only be set if the light has a reference //! to a specific \ref ColorTemperatureStrategy. The color temperature can - //! range from 153 to 500. \param mired Unsigned int that specifies the color - //! temperature in Mired \param transition Optional parameter to set the - //! transition from current state to new, standard is 4 = 400ms \return Bool - //! that is true on success + //! range from 153 to 500. + //! \param mired Unsigned int that specifies the color temperature in Mired + //! \param transition Optional parameter to set the transition from current state to new, standard is 4 = 400ms + //! \return Bool that is true on success + //! \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 virtual bool setColorTemperature(unsigned int mired, uint8_t transition = 4) { if (colorTemperatureStrategy) @@ -319,8 +353,13 @@ public: //! reference to a specific \ref ColorTemperatureStrategy. //! Updates the lights state by calling refreshState() //! The color temperature in mired ranges from 153 to 500 whereas 153 is cold - //! and 500 is warm. \param light A reference of the light \return Unsigned - //! int representing the color temperature in mired or 0 when failed + //! and 500 is warm. + //! \param light A reference of the light + //! \return Unsigned int representing the color temperature in mired or 0 when failed + //! \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 virtual unsigned int getColorTemperature() { if (colorTemperatureStrategy) @@ -334,10 +373,14 @@ public: //! //! \note The color will only be set if the light has a reference to a //! specific \ref ColorHueStrategy. The hue can range from 0 to 65535, whereas - //! 65535 and 0 are red, 25500 is green and 46920 is blue. \param hue uint16_t - //! that specifies the hue \param transition Optional parameter to set the - //! transition from current state to new, standard is 4 = 400ms \return Bool - //! that is true on success + //! 65535 and 0 are red, 25500 is green and 46920 is blue. + //! \param hue uint16_t that specifies the hue + //! \param transition Optional parameter to set the transition from current state to new, standard is 4 = 400ms + //! \return Bool that is true on success + //! \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 virtual bool setColorHue(uint16_t hue, uint8_t transition = 4) { if (colorHueStrategy) @@ -351,10 +394,14 @@ public: //! //! \note The color will only be set if the light has a reference to a //! specific \ref ColorHueStrategy. The saturation can range from 0 to 254, - //! whereas 0 is least saturated (white) and 254 is most saturated. \param sat - //! uint8_t that specifies the saturation \param transition Optional parameter - //! to set the transition from current state to new, standard is 4 = 400ms + //! whereas 0 is least saturated (white) and 254 is most saturated. + //! \param sat uint8_t that specifies the saturation + //! \param transition Optional parameter to set the transition from current state to new, standard is 4 = 400ms //! \return Bool that is true on success + //! \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 virtual bool setColorSaturation(uint8_t sat, uint8_t transition = 4) { if (colorHueStrategy) @@ -368,10 +415,15 @@ public: //! saturation. //! //! \note The color will only be set if the light has a reference to a - //! specific \ref ColorHueStrategy. \param hue uint16_t that specifies the hue + //! specific \ref ColorHueStrategy. + //! \param hue uint16_t that specifies the hue //! \param sat uint8_t that specifies the saturation - //! \param transition Optional parameter to set the transition from current - //! state to new, standard is 4 = 400ms. \return Bool that is true on success + //! \param transition Optional parameter to set the transition from current state to new, standard is 4 = 400ms. + //! \return Bool that is true on success + //! \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 virtual bool setColorHueSaturation(uint16_t hue, uint8_t sat, uint8_t transition = 4) { if (colorHueStrategy) @@ -388,8 +440,11 @@ public: //! has a reference to a specific \ref ColorHueStrategy. //! \note This will not refresh the light state //! \param light A reference of the light - //! \return Pair containing the hue as first value and saturation as second - //! value or an empty one when failed + //! \return Pair containing the hue as first value and saturation as second value or an empty one when failed + //! \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 virtual std::pair getColorHueSaturation() const { if (colorHueStrategy) @@ -406,8 +461,11 @@ public: //! has a reference to a specific \ref ColorHueStrategy. Updates the lights //! state by calling refreshState() //! \param light A const reference of the light - //! \return Pair containing the hue as first value and saturation as second - //! value or an empty one when failed + //! \return Pair containing the hue as first value and saturation as second value or an empty one when failed + //! \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 virtual std::pair getColorHueSaturation() { if (colorHueStrategy) @@ -420,11 +478,15 @@ public: //! \brief Function to set the color of this light in CIE with specified x y. //! //! \note The color will only be set if the light has a reference to a - //! specific \ref ColorHueStrategy. The values of x and y are ranging from 0 - //! to 1. \param x float that specifies the x coordinate in CIE \param y float - //! that specifies the y coordinate in CIE \param transition Optional - //! parameter to set the transition from current state to new, standard is 4 = - //! 400ms \return Bool that is true on success + //! specific \ref ColorHueStrategy. The values of x and y are ranging from 0 to 1. + //! \param x float that specifies the x coordinate in CIE + //! \param y float that specifies the y coordinate in CIE + //! \param transition Optional parameter to set the transition from current state to new, standard is 4 = 400ms + //! \return Bool that is true on success + //! \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 virtual bool setColorXY(float x, float y, uint8_t transition = 4) { if (colorHueStrategy) @@ -457,8 +519,11 @@ public: //! reference to a specific \ref ColorHueStrategy. //! Updates the lights state by calling refreshState() //! \param light A reference of the light - //! \return Pair containing the x as first value and y as second value or an - //! empty one when failed + //! \return Pair containing the x as first value and y as second value or an empty one when failed + //! \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 virtual std::pair getColorXY() { if (colorHueStrategy) @@ -476,8 +541,12 @@ public: //! ranging from 0 to 255. \param r uint8_t that specifies the red color value //! \param g uint8_t that specifies the green color value //! \param b uint8_t that specifies the blue color value - //! \param transition Optional parameter to set the transition from current - //! state to new, standard is 4 = 400ms \return Bool that is true on success + //! \param transition Optional parameter to set the transition from current state to new, standard is 4 = 400ms + //! \return Bool that is true on success + //! \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 virtual bool setColorRGB(uint8_t r, uint8_t g, uint8_t b, uint8_t transition = 4) { if (colorHueStrategy) @@ -491,14 +560,23 @@ public: //! //! Can be used for locating a light. //! \return bool that is true on success + //! \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 virtual bool alert(); //! \brief Function that lets the light perform one breath cycle in specified //! color temperature. //! //! \note The breath cylce will only be performed if the light has a reference - //! to a specific \ref ColorTemperatureStrategy. \param mired Color - //! temperature in mired \return Bool that is true on success + //! to a specific \ref ColorTemperatureStrategy. + //! \param mired Color temperature in mired + //! \return Bool that is true on success + //! \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 virtual bool alertTemperature(unsigned int mired) { if (colorTemperatureStrategy) @@ -512,9 +590,14 @@ public: //! color. //! //! \note The breath cylce will only be performed if the light has a reference - //! to a specific \ref ColorHueStrategy. \param hue uint16_t that specifies - //! the hue \param sat uint8_t that specifies the saturation \return Bool that - //! is true on success + //! to a specific \ref ColorHueStrategy. + //! \param hue uint16_t that specifies the hue + //! \param sat uint8_t that specifies the saturation + //! \return Bool that is true on success + //! \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 virtual bool alertHueSaturation(uint16_t hue, uint8_t sat) { if (colorHueStrategy) @@ -529,9 +612,14 @@ public: //! //! \note The breath cylce will only be performed if the light has a reference //! to a specific \ref ColorHueStrategy. The values of x and y are ranging - //! from 0 to 1. \param x float that specifies the x coordinate in CIE \param - //! y float that specifies the y coordinate in CIE \return Bool that is true - //! on success + //! from 0 to 1. + //! \param x float that specifies the x coordinate in CIE + //! \param y float that specifies the y coordinate in CIE + //! \return Bool that is true on success + //! \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 virtual bool alertXY(float x, float y) { if (colorHueStrategy) @@ -546,10 +634,15 @@ public: //! //! \note The breath cylce will only be performed if the light has a reference //! to a specific \ref ColorHueStrategy. The values of red, green and blue are - //! ranging from 0 to 255. \param r uint8_t that specifies the red color value + //! ranging from 0 to 255. + //! \param r uint8_t that specifies the red color value //! \param g uint8_t that specifies the green color value //! \param b uint8_t that specifies the blue color value //! \return Bool that is true on success + //! \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 virtual bool alertRGB(uint8_t r, uint8_t g, uint8_t b) { if (colorHueStrategy) @@ -570,6 +663,10 @@ public: //! alternatively call Off() and then use any of the setter functions. \param //! on bool that enables this feature when true and disables it when false //! \return Bool that is true on success + //! \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 virtual bool setColorLoop(bool on) { if (colorHueStrategy) @@ -596,6 +693,10 @@ protected: //! \param brightnessStrategy Strategy for brightness. May be nullptr. //! \param colorTempStrategy Strategy for color temperature. May be nullptr. //! \param colorHueStrategy Strategy for color hue/saturation. May be nullptr. + //! \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 HueLight(int id, const HueCommandAPI& commands, std::shared_ptr brightnessStrategy, std::shared_ptr colorTempStrategy, std::shared_ptr colorHueStrategy); @@ -637,25 +738,41 @@ protected: //! \brief Function that turns the light on without refreshing its state. //! - //! \param transition Optional parameter to set the transition from current - //! state to new standard is 4 = 400ms \return Bool that is true on success + //! \param transition Optional parameter to set the transition from current state to new standard is 4 = 400ms + //! \return Bool that is true on success + //! \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 virtual bool OnNoRefresh(uint8_t transition = 4); //! \brief Function that turns the light off without refreshing its state. //! - //! \param transition Optional parameter to set the transition from current - //! state to new standard is 4 = 400ms \return Bool that is true on success + //! \param transition Optional parameter to set the transition from current state to new standard is 4 = 400ms + //! \return Bool that is true on success + //! \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 virtual bool OffNoRefresh(uint8_t transition = 4); //! \brief Utility function to send a put request to the light. //! //! \throws nlohmann::json::parse_error if the reply could not be parsed //! \param request A nlohmann::json aka the request to send - //! \param subPath A path that is appended to the uri, note it should always - //! start with a slash ("/") \return The parsed reply + //! \param subPath A path that is appended to the uri, note it should always start with a slash ("/") + //! \return The parsed reply + //! \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 virtual nlohmann::json SendPutRequest(const nlohmann::json& request, const std::string& subPath, FileInfo fileInfo); //! \brief Virtual function that refreshes the \ref state of the light. + //! \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 virtual void refreshState(); protected: diff --git a/hueplusplus/include/UPnP.h b/hueplusplus/include/UPnP.h index 0e49fb4..5c2bdf1 100755 --- a/hueplusplus/include/UPnP.h +++ b/hueplusplus/include/UPnP.h @@ -33,13 +33,13 @@ class UPnP { public: - //! \brief Function that searches for UPnP devices and returns all found ones. + //! \brief Searches for UPnP devices and returns all found ones. //! - //! It does it by sending an m-search packet and waits for all responses. - //! Since responses can be received multiple times this function conveniently - //! removes all duplicates. \param handler HttpHandler of type \ref - //! IHttpHandler for communication with the bridge \return A vector containing - //! pairs of address and name of all found devices + //! It does it by sending an m-search packet and waits for all responses. + //! Since responses can be received multiple times this function conveniently removes all duplicates. + //! \param handler HttpHandler for communication + //! \return A vector containing pairs of address and name of all found devices + //! \throws std::system_error when system or socket operations fail std::vector> getDevices(std::shared_ptr handler); }; diff --git a/hueplusplus/include/WinHttpHandler.h b/hueplusplus/include/WinHttpHandler.h index 3c12adb..e5c92dc 100644 --- a/hueplusplus/include/WinHttpHandler.h +++ b/hueplusplus/include/WinHttpHandler.h @@ -48,7 +48,7 @@ public: //! decimal notation like "192.168.2.1" \param port Optional integer that //! specifies the port to which the request is sent to. Default is 80 \return //! String containing the response of the host - std::string send(const std::string& msg, const std::string& adr, int port = 80) const; + std::string send(const std::string& msg, const std::string& adr, int port = 80) const override; //! \brief Function that sends a multicast request with the specified message. //! @@ -59,8 +59,8 @@ public: //! 1900 \param timeout Optional Integer that specifies the timeout of the //! request in seconds. Default is 5 \return Vector containing strings of each //! answer received - std::vector sendMulticast( - const std::string& msg, const std::string& adr = "239.255.255.250", int port = 1900, int timeout = 5) const; + std::vector sendMulticast(const std::string& msg, const std::string& adr = "239.255.255.250", + int port = 1900, int timeout = 5) const override; private: WSADATA wsaData;