Peter M. Groen / hueplusplus

Commit 62e4a11c435d8b90cf249d4d00b9cd898ece486e

Authored by Jojo-1000
Committed by Jan
1 parent 57d0665e

Update throws documentation on Hue and HueLight.

Inline Side-by-side
Showing 7 changed files with 297 additions and 177 deletions
hueplusplus/Hue.cpp
  View file @62e4a11
... ... @@ -202,6 +202,10 @@ std::string Hue::requestUsername(const std::string& ip)
202 202 {
203 203 std::cout << "Link button not pressed!\n";
204 204 }
  205 + else
  206 + {
  207 + throw;
  208 + }
205 209 }
206 210 std::this_thread::sleep_until(lastCheck + std::chrono::seconds(1));
207 211 }
... ...
hueplusplus/include/BaseHttpHandler.h
  View file @62e4a11
... ... @@ -40,15 +40,6 @@ public:
40 40 //! \brief Virtual dtor
41 41 virtual ~BaseHttpHandler() = default;
42 42  
43   - //! \brief Send a message to a specified host and return the response.
44   - //!
45   - //! \param msg The message that should be sent to the specified address
46   - //! \param adr Ip or hostname in dotted decimal notation like "192.168.2.1"
47   - //! \param port Optional port the request is sent to, default is 80
48   - //! \return The response of the host as a string
49   - //! \throws std::system_error when system or socket operations fail
50   - virtual std::string send(const std::string& msg, const std::string& adr, int port = 80) const = 0;
51   -
52 43 //! \brief Send a message to a specified host and return the body of the response.
53 44 //!
54 45 //! \param msg The message that should sent to the specified address
... ... @@ -57,21 +48,7 @@ public:
57 48 //! \return The body of the response of the host as a string
58 49 //! \throws std::system_error when system or socket operations fail
59 50 //! \throws HueException when response contained no body
60   - virtual std::string sendGetHTTPBody(const std::string& msg, const std::string& adr, int port = 80) const;
61   -
62   - //! \brief Send a multicast request with a specified message.
63   - //!
64   - //! \param msg The message that should sent to the specified multicast address
65   - //! \param adr Optional ip or hostname in dotted decimal notation, default is "239.255.255.250"
66   - //! \param port Optional port the request is sent to, default is 1900
67   - //! \param timeout Optional time to wait for responses in seconds, default is 5
68   - //!
69   - //! Blocks for the duration of the timeout.
70   - //!
71   - //! \return vector of strings containing each received answer
72   - //! \throws std::system_error when system or socket operations fail
73   - virtual std::vector<std::string> sendMulticast(
74   - const std::string& msg, const std::string& adr = "239.255.255.250", int port = 1900, int timeout = 5) const = 0;
  51 + std::string sendGetHTTPBody(const std::string& msg, const std::string& adr, int port = 80) const override;
75 52  
76 53 //! \brief Send a HTTP request with the given method to the specified host and return the body of the response.
77 54 //!
... ... @@ -84,8 +61,8 @@ public:
84 61 //! \return Body of the response of the host
85 62 //! \throws std::system_error when system or socket operations fail
86 63 //! \throws HueException when response contained no body
87   - virtual std::string sendHTTPRequest(const std::string& method, const std::string& uri,
88   - const std::string& contentType, const std::string& body, const std::string& adr, int port = 80) const;
  64 + std::string sendHTTPRequest(const std::string& method, const std::string& uri, const std::string& contentType,
  65 + const std::string& body, const std::string& adr, int port = 80) const override;
89 66  
90 67 //! \brief Send a HTTP GET request to the specified host and return the body of the response.
91 68 //!
... ... @@ -98,8 +75,8 @@ public:
98 75 //! \return Body of the response of the host
99 76 //! \throws std::system_error when system or socket operations fail
100 77 //! \throws HueException when response contained no body
101   - virtual std::string GETString(const std::string& uri, const std::string& contentType, const std::string& body,
102   - const std::string& adr, int port = 80) const;
  78 + std::string GETString(const std::string& uri, const std::string& contentType, const std::string& body,
  79 + const std::string& adr, int port = 80) const override;
103 80  
104 81 //! \brief Send a HTTP POST request to the specified host and return the body of the response.
105 82 //!
... ... @@ -112,8 +89,8 @@ public:
112 89 //! \return Body of the response of the host
113 90 //! \throws std::system_error when system or socket operations fail
114 91 //! \throws HueException when response contained no body
115   - virtual std::string POSTString(const std::string& uri, const std::string& contentType, const std::string& body,
116   - const std::string& adr, int port = 80) const;
  92 + std::string POSTString(const std::string& uri, const std::string& contentType, const std::string& body,
  93 + const std::string& adr, int port = 80) const override;
117 94  
118 95 //! \brief Send a HTTP PUT request to the specified host and return the body of the response.
119 96 //!
... ... @@ -126,8 +103,8 @@ public:
126 103 //! \return Body of the response of the host
127 104 //! \throws std::system_error when system or socket operations fail
128 105 //! \throws HueException when response contained no body
129   - virtual std::string PUTString(const std::string& uri, const std::string& contentType, const std::string& body,
130   - const std::string& adr, int port = 80) const;
  106 + std::string PUTString(const std::string& uri, const std::string& contentType, const std::string& body,
  107 + const std::string& adr, int port = 80) const override;
131 108  
132 109 //! \brief Send a HTTP DELETE request to the specified host and return the body of the response.
133 110 //!
... ... @@ -140,8 +117,8 @@ public:
140 117 //! \return Body of the response of the host
141 118 //! \throws std::system_error when system or socket operations fail
142 119 //! \throws HueException when response contained no body
143   - virtual std::string DELETEString(const std::string& uri, const std::string& contentType, const std::string& body,
144   - const std::string& adr, int port = 80) const;
  120 + std::string DELETEString(const std::string& uri, const std::string& contentType, const std::string& body,
  121 + const std::string& adr, int port = 80) const override;
145 122  
146 123 //! \brief Send a HTTP GET request to the specified host and return the body of the response parsed as JSON.
147 124 //!
... ... @@ -153,8 +130,8 @@ public:
153 130 //! \throws std::system_error when system or socket operations fail
154 131 //! \throws HueException when response contained no body
155 132 //! \throws nlohmann::json::parse_error when the body could not be parsed
156   - virtual nlohmann::json GETJson(
157   - const std::string& uri, const nlohmann::json& body, const std::string& adr, int port = 80) const;
  133 + nlohmann::json GETJson(
  134 + const std::string& uri, const nlohmann::json& body, const std::string& adr, int port = 80) const override;
158 135  
159 136 //! \brief Send a HTTP POST request to the specified host and return the body of the response parsed as JSON.
160 137 //!
... ... @@ -166,8 +143,8 @@ public:
166 143 //! \throws std::system_error when system or socket operations fail
167 144 //! \throws HueException when response contained no body
168 145 //! \throws nlohmann::json::parse_error when the body could not be parsed
169   - virtual nlohmann::json POSTJson(
170   - const std::string& uri, const nlohmann::json& body, const std::string& adr, int port = 80) const;
  146 + nlohmann::json POSTJson(
  147 + const std::string& uri, const nlohmann::json& body, const std::string& adr, int port = 80) const override;
171 148  
172 149 //! \brief Send a HTTP PUT request to the specified host and return the body of the response parsed as JSON.
173 150 //!
... ... @@ -179,8 +156,8 @@ public:
179 156 //! \throws std::system_error when system or socket operations fail
180 157 //! \throws HueException when response contained no body
181 158 //! \throws nlohmann::json::parse_error when the body could not be parsed
182   - virtual nlohmann::json PUTJson(
183   - const std::string& uri, const nlohmann::json& body, const std::string& adr, int port = 80) const;
  159 + nlohmann::json PUTJson(
  160 + const std::string& uri, const nlohmann::json& body, const std::string& adr, int port = 80) const override;
184 161  
185 162 //! \brief Send a HTTP DELETE request to the specified host and return the body of the response parsed as JSON.
186 163 //!
... ... @@ -192,8 +169,8 @@ public:
192 169 //! \throws std::system_error when system or socket operations fail
193 170 //! \throws HueException when response contained no body
194 171 //! \throws nlohmann::json::parse_error when the body could not be parsed
195   - virtual nlohmann::json DELETEJson(
196   - const std::string& uri, const nlohmann::json& body, const std::string& adr, int port = 80) const;
  172 + nlohmann::json DELETEJson(
  173 + const std::string& uri, const nlohmann::json& body, const std::string& adr, int port = 80) const override;
197 174 };
198 175  
199 176 #endif
... ...
hueplusplus/include/Hue.h
  View file @62e4a11
... ... @@ -57,21 +57,25 @@ public:
57 57 public:
58 58 //! \brief Constructor of HueFinder class
59 59 //!
60   - //! \param handler HttpHandler of type \ref IHttpHandler for communication
61   - //! with the bridge
  60 + //! \param handler HttpHandler of type \ref IHttpHandler for communication with the bridge
62 61 HueFinder(std::shared_ptr<const IHttpHandler> handler);
63 62  
64   - //! \brief Function that finds all bridges in the network and returns them.
  63 + //! \brief Finds all bridges in the network and returns them.
65 64 //!
66   - //! The user should be given the opportunity to select the correct one based
67   - //! on the mac address. \return vector containing ip and mac of all found
68   - //! bridges
  65 + //! The user should be given the opportunity to select the correct one based on the mac address.
  66 + //! \return vector containing ip and mac of all found bridges
  67 + //! \throws std::system_error when system or socket operations fail
  68 + //! \throws HueException when response contained no body
69 69 std::vector<HueIdentification> FindBridges() const;
70 70  
71   - //! \brief Function that gets a \ref Hue bridge based on its identification
  71 + //! \brief Gets a \ref Hue bridge based on its identification
72 72 //!
73 73 //! \param identification \ref HueIdentification that specifies a bridge
74 74 //! \return \ref Hue class object
  75 + //! \throws std::system_error when system or socket operations fail
  76 + //! \throws HueException when response contained no body or username could not be requested
  77 + //! \throws HueAPIResponseException when response contains an error
  78 + //! \throws nlohmann::json::parse_error when response could not be parsed
75 79 Hue GetBridge(const HueIdentification& identification);
76 80  
77 81 //! \brief Function that adds a username to the \ref usernames map
... ... @@ -88,15 +92,14 @@ public:
88 92 const std::map<std::string, std::string>& GetAllUsernames() const;
89 93  
90 94 //! \brief Normalizes mac address to plain hex number.
91   - //! \returns \p input without separators and whitespace, in upper case.
  95 + //! \returns \p input without separators and whitespace, in lower case.
92 96 static std::string NormalizeMac(std::string input);
93 97  
94 98 private:
95 99 //! \brief Parses mac address from description.xml
96 100 //!
97   - //! \param description Content of description.xml file as returned by GET
98   - //! request. \returns Content of xml element \c serialNumber if description
99   - //! matches a Hue bridge, otherwise an empty string.
  101 + //! \param description Content of description.xml file as returned by GET request.
  102 + //! \returns Content of xml element \c serialNumber if description matches a Hue bridge, otherwise an empty string.
100 103 static std::string ParseDescription(const std::string& description);
101 104  
102 105 std::map<std::string, std::string> usernames; //!< Maps all macs to usernames added by \ref
... ... @@ -129,15 +132,18 @@ public:
129 132 //! \return integer containing port
130 133 int getBridgePort();
131 134  
132   - //! \brief Function that sends a username request to the Hue bridge.
  135 + //! \brief Send a username request to the Hue bridge.
133 136 //!
134   - //! It does that for about 30 seconds and you have 5 seconds to prepare
135   - //! It automatically sets the \ref username variable according to the username
136   - //! received and returns the username received This function should only be
137   - //! called once to acquire a username to control the bridge and the username
138   - //! should be saved for future use \param ip String that specifies the ip (in
139   - //! dotted decimal notation like "192.168.2.1") the request is send to \return
140   - //! String containing username
  137 + //! Blocks for about 30 seconds and 5 seconds to prepare.
  138 + //! It automatically sets the \ref username variable according to the username received and returns the username received.
  139 + //! This function should only be called once to acquire a username to control the bridge and the username
  140 + //! should be saved for future use.
  141 + //! \param ip String that specifies the ip (in dotted decimal notation like "192.168.2.1") the request is send to
  142 + //! \return username for API usage
  143 + //! \throws std::system_error when system or socket operations fail
  144 + //! \throws HueException when response contained no body
  145 + //! \throws HueAPIResponseException when response contains an error except link button not pressed.
  146 + //! \throws nlohmann::json::parse_error when response could not be parsed
141 147 std::string requestUsername(const std::string& ip);
142 148  
143 149 //! \brief Function that returns the \ref username
... ... @@ -147,8 +153,7 @@ public:
147 153  
148 154 //! \brief Function to set the ip address of this class representing a bridge
149 155 //!
150   - //! \param ip String that specifies the ip in dotted decimal notation like
151   - //! "192.168.2.1"
  156 + //! \param ip String that specifies the ip in dotted decimal notation like "192.168.2.1"
152 157 void setIP(const std::string& ip);
153 158  
154 159 //! \brief Function to set the port of this class representing a bridge
... ... @@ -161,17 +166,24 @@ public:
161 166 //!
162 167 //! \param id Integer that specifies the ID of a Hue light
163 168 //! \return \ref HueLight that can be controlled
  169 + //! \throws std::system_error when system or socket operations fail
  170 + //! \throws HueException when id does not exist or type is unknown
  171 + //! \throws HueAPIResponseException when response contains an error
  172 + //! \throws nlohmann::json::parse_error when response could not be parsed
164 173 HueLight& getLight(int id);
165 174  
166 175 //! \brief Function to remove a light from the bridge
167 176 //!
168   - //! \attention Any use of the light after it was successfully removed results
169   - //! in undefined behavior \param id Id of the light to remove \return Bool
170   - //! that is true on success
  177 + //! \attention Any use of the light after it was successfully removed results in undefined behavior
  178 + //! \param id Id of the light to remove
  179 + //! \return true on success
  180 + //! \throws std::system_error when system or socket operations fail
  181 + //! \throws HueException when response contains no body
  182 + //! \throws HueAPIResponseException when response contains an error
  183 + //! \throws nlohmann::json::parse_error when response could not be parsed
171 184 bool removeLight(int id);
172 185  
173   - //! \brief Function that returns all light types that are associated with this
174   - //! bridge
  186 + //! \brief Function that returns all light types that are associated with this bridge
175 187 //!
176 188 //! \return A map mapping light id's to light types for every light
177 189 // const std::map<uint8_t, ColorType>& getAllLightTypes();
... ... @@ -180,15 +192,21 @@ public:
180 192 //! bridge
181 193 //!
182 194 //! \return A vector containing references to every HueLight
  195 + //! \throws std::system_error when system or socket operations fail
  196 + //! \throws HueException when response contains no body
  197 + //! \throws HueAPIResponseException when response contains an error
  198 + //! \throws nlohmann::json::parse_error when response could not be parsed
183 199 std::vector<std::reference_wrapper<HueLight>> getAllLights();
184 200  
185   - //! \brief Function that tells whether a given light id represents an existing
186   - //! light
  201 + //! \brief Function that tells whether a given light id represents an existing light
187 202 //!
188 203 //! Calls refreshState to update the local bridge state
189 204 //! \param id Id of a light to check for existance
190   - //! \return Bool that is true when a light with the given id exists and false
191   - //! when not
  205 + //! \return Bool that is true when a light with the given id exists and false when not
  206 + //! \throws std::system_error when system or socket operations fail
  207 + //! \throws HueException when response contains no body
  208 + //! \throws HueAPIResponseException when response contains an error
  209 + //! \throws nlohmann::json::parse_error when response could not be parsed
192 210 bool lightExists(int id);
193 211  
194 212 //! \brief Const function that tells whether a given light id represents an
... ... @@ -231,6 +249,10 @@ public:
231 249  
232 250 private:
233 251 //! \brief Function that refreshes the local \ref state of the Hue bridge
  252 + //! \throws std::system_error when system or socket operations fail
  253 + //! \throws HueException when response contained no body
  254 + //! \throws HueAPIResponseException when response contains an error
  255 + //! \throws nlohmann::json::parse_error when response could not be parsed
234 256 void refreshState();
235 257  
236 258 private:
... ...
hueplusplus/include/HueCommandAPI.h
  View file @62e4a11
... ... @@ -37,62 +37,59 @@ class HueCommandAPI
37 37 public:
38 38 //! \brief Construct from ip, username and HttpHandler
39 39 //!
40   - //! \param ip String that specifies the ip address of the Hue bridge in dotted
41   - //! decimal notation like "192.168.2.1" \param port of the hue bridge
42   - //! \param username String that specifies the username that is used to control
43   - //! the bridge \param handler HttpHandler of type \ref IHttpHandler for
44   - //! communication with the bridge
45   - HueCommandAPI(const std::string& ip, const int port, const std::string& username,
46   - std::shared_ptr<const IHttpHandler> httpHandler);
  40 + //! \param ip ip address of the Hue bridge in dotted decimal notation like "192.168.2.1"
  41 + //! \param username username that is used to control the bridge
  42 + //! \param port of the hue bridge
  43 + //! \param handler HttpHandler for communication with the bridge
  44 + HueCommandAPI(const std::string& ip, const std::string& username, std::shared_ptr<const IHttpHandler> httpHandler);
47 45  
48 46 //! \brief Copy construct from other HueCommandAPI
49   - //! \note All copies refer to the same timeout data, so even calls from
50   - //! different objects will be delayed
  47 + //! \note All copies refer to the same timeout data, so even calls from different objects will be delayed
51 48 HueCommandAPI(const HueCommandAPI&) = default;
52 49 //! \brief Move construct from other HueCommandAPI
53   - //! \note All copies refer to the same timeout data, so even calls from
54   - //! different objects will be delayed
  50 + //! \note All copies refer to the same timeout data, so even calls from different objects will be delayed
55 51 HueCommandAPI(HueCommandAPI&&) = default;
56 52  
57 53 //! \brief Copy assign from other HueCommandAPI
58   - //! \note All copies refer to the same timeout data, so even calls from
59   - //! different objects will be delayed
  54 + //! \note All copies refer to the same timeout data, so even calls from different objects will be delayed
60 55 HueCommandAPI& operator=(const HueCommandAPI&) = default;
61 56 //! \brief Move assign from other HueCommandAPI
62   - //! \note All copies refer to the same timeout data, so even calls from
63   - //! different objects will be delayed
  57 + //! \note All copies refer to the same timeout data, so even calls from different objects will be delayed
64 58 HueCommandAPI& operator=(HueCommandAPI&&) = default;
65 59  
66   - //! \brief Sends a HTTP PUT request via the \ref httpHandler to the bridge and
67   - //! returns the response
  60 + //! \brief Sends a HTTP PUT request via the \ref httpHandler to the bridge and returns the response
68 61 //!
69   - //! This function will block until at least \ref minDelay has passed to any
70   - //! previous request \param path String that contains the request path
71   - //! (appended after /api/<username>) \param request Json value containing the
72   - //! request. May be empty \returns The return value of the underlying \ref
73   - //! IHttpHandler::PUTJson call
  62 + //! This function will block until at least \ref minDelay has passed to any previous request
  63 + //! \param path API request path (appended after /api/<username>)
  64 + //! \param request Request to the api, may be empty
  65 + //! \returns The return value of the underlying \ref IHttpHandler::PUTJson call
  66 + //! \throws std::system_error when system or socket operations fail
  67 + //! \throws HueException when response contains no body
  68 + //! \throws HueAPIResponseException when response contains an error
74 69 nlohmann::json PUTRequest(const std::string& path, const nlohmann::json& request) const;
75 70 nlohmann::json PUTRequest(const std::string& path, const nlohmann::json& request, FileInfo fileInfo) const;
76 71  
77   - //! \brief Sends a HTTP GET request via the \ref httpHandler to the bridge and
78   - //! returns the response
  72 + //! \brief Sends a HTTP GET request via the \ref httpHandler to the bridge and returns the response
79 73 //!
80   - //! This function will block until at least \ref minDelay has passed to any
81   - //! previous request \param path String that contains the request path
82   - //! (appended after /api/<username>) \param request Json value containing the
83   - //! request. May be empty \returns The return value of the underlying \ref
84   - //! IHttpHandler::GETJson call
  74 + //! This function will block until at least \ref minDelay has passed to any previous request
  75 + //! \param path API request path (appended after /api/<username>)
  76 + //! \param request Request to the api, may be empty
  77 + //! \returns The return value of the underlying \ref IHttpHandler::GETJson call
  78 + //! \throws std::system_error when system or socket operations fail
  79 + //! \throws HueException when response contains no body
  80 + //! \throws HueAPIResponseException when response contains an error
85 81 nlohmann::json GETRequest(const std::string& path, const nlohmann::json& request) const;
86 82 nlohmann::json GETRequest(const std::string& path, const nlohmann::json& request, FileInfo fileInfo) const;
87 83  
88   - //! \brief Sends a HTTP DELETE request via the \ref httpHandler to the bridge
89   - //! and returns the response
  84 + //! \brief Sends a HTTP DELETE request via the \ref httpHandler to the bridge and returns the response
90 85 //!
91   - //! This function will block until at least \ref minDelay has passed to any
92   - //! previous request \param path String that contains the request path
93   - //! (appended after /api/<username>) \param request Json value containing the
94   - //! request. May be empty \returns The return value of the underlying \ref
95   - //! IHttpHandler::DELETEJson call
  86 + //! This function will block until at least \ref minDelay has passed to any previous request
  87 + //! \param path API request path (appended after /api/<username>)
  88 + //! \param request Request to the api, may be empty
  89 + //! \returns The return value of the underlying \ref IHttpHandler::DELETEJson call
  90 + //! \throws std::system_error when system or socket operations fail
  91 + //! \throws HueException when response contains no body
  92 + //! \throws HueAPIResponseException when response contains an error
96 93 nlohmann::json DELETERequest(const std::string& path, const nlohmann::json& request) const;
97 94 nlohmann::json DELETERequest(const std::string& path, const nlohmann::json& request, FileInfo fileInfo) const;
98 95  
... ... @@ -104,9 +101,12 @@ private:
104 101 };
105 102  
106 103 //! \brief Throws an exception if response contains an error, passes though value
  104 + //! \throws HueAPIResponseException when response contains an error
  105 + //! \returns \ref response if there is no error
107 106 nlohmann::json HandleError(FileInfo fileInfo, const nlohmann::json& response) const;
108 107  
109 108 //! \brief Combines path with api prefix and username
  109 + //! \returns "/api/<username>/<path>"
110 110 std::string CombinedPath(const std::string& path) const;
111 111  
112 112 private:
... ...
hueplusplus/include/HueLight.h
  View file @62e4a11
... ... @@ -106,19 +106,31 @@ public:
106 106  
107 107 //! \brief Function that turns the light on.
108 108 //!
109   - //! \param transition Optional parameter to set the transition from current
110   - //! state to new, standard is 4 = 400ms \return Bool that is true on success
  109 + //! \param transition Optional parameter to set the transition from current state to new, standard is 4 = 400ms
  110 + //! \return true on success
  111 + //! \throws std::system_error when system or socket operations fail
  112 + //! \throws HueException when response contained no body
  113 + //! \throws HueAPIResponseException when response contains an error
  114 + //! \throws nlohmann::json::parse_error when response could not be parsed
111 115 virtual bool On(uint8_t transition = 4);
112 116  
113 117 //! \brief Function that turns the light off.
114 118 //!
115   - //! \param transition Optional parameter to set the transition from current
116   - //! state to new, standard is 4 = 400ms \return Bool that is true on success
  119 + //! \param transition Optional parameter to set the transition from current state to new, standard is 4 = 400ms
  120 + //! \return Bool that is true on success
  121 + //! \throws std::system_error when system or socket operations fail
  122 + //! \throws HueException when response contained no body
  123 + //! \throws HueAPIResponseException when response contains an error
  124 + //! \throws nlohmann::json::parse_error when response could not be parsed
117 125 virtual bool Off(uint8_t transition = 4);
118 126  
119 127 //! \brief Function to check whether a light is on or off
120 128 //!
121 129 //! \return Bool that is true, when the light is on and false, when off
  130 + //! \throws std::system_error when system or socket operations fail
  131 + //! \throws HueException when response contained no body
  132 + //! \throws HueAPIResponseException when response contains an error
  133 + //! \throws nlohmann::json::parse_error when response could not be parsed
122 134 virtual bool isOn();
123 135  
124 136 //! \brief Const function to check whether a light is on or off
... ... @@ -140,6 +152,10 @@ public:
140 152 //! \brief Function that returns the name of the light.
141 153 //!
142 154 //! \return String containig the name of the light
  155 + //! \throws std::system_error when system or socket operations fail
  156 + //! \throws HueException when response contained no body
  157 + //! \throws HueAPIResponseException when response contains an error
  158 + //! \throws nlohmann::json::parse_error when response could not be parsed
143 159 virtual std::string getName();
144 160  
145 161 //! \brief Const function that returns the name of the light.
... ... @@ -156,34 +172,34 @@ public:
156 172 //! \brief Const function that returns the uniqueid of the light
157 173 //!
158 174 //! \note Only working on bridges with versions starting at 1.4
159   - //! \return String containing the uniqueid or an empty string when the
160   - //! function is not supported
  175 + //! \return String containing the uniqueid or an empty string when the function is not supported
161 176 virtual std::string getUId() const;
162 177  
163 178 //! \brief Const function that returns the manufacturername of the light
164 179 //!
165 180 //! \note Only working on bridges with versions starting at 1.7
166   - //! \return String containing the manufacturername or an empty string when the
167   - //! function is not supported
  181 + //! \return String containing the manufacturername or an empty string when the function is not supported
168 182 virtual std::string getManufacturername() const;
169 183  
170 184 //! \brief Const function that returns the productname of the light
171 185 //!
172 186 //! \note Only working on bridges with versions starting at 1.24
173   - //! \return String containing the productname or an empty string when the
174   - //! function is not supported
  187 + //! \return String containing the productname or an empty string when the function is not supported
175 188 virtual std::string getProductname() const;
176 189  
177 190 //! \brief Const function that returns the luminaireuniqueid of the light
178 191 //!
179 192 //! \note Only working on bridges with versions starting at 1.9
180   - //! \return String containing the luminaireuniqueid or an empty string when
181   - //! the function is not supported
  193 + //! \return String containing the luminaireuniqueid or an empty string when the function is not supported
182 194 virtual std::string getLuminaireUId() const;
183 195  
184 196 //! \brief Function that returns the software version of the light
185 197 //!
186 198 //! \return String containing the software version
  199 + //! \throws std::system_error when system or socket operations fail
  200 + //! \throws HueException when response contained no body
  201 + //! \throws HueAPIResponseException when response contains an error
  202 + //! \throws nlohmann::json::parse_error when response could not be parsed
187 203 virtual std::string getSwVersion();
188 204  
189 205 //! \brief Const function that returns the software version of the light
... ... @@ -195,6 +211,10 @@ public:
195 211 //! \brief Function that sets the name of the light
196 212 //!
197 213 //! \return Bool that is true on success
  214 + //! \throws std::system_error when system or socket operations fail
  215 + //! \throws HueException when response contained no body
  216 + //! \throws HueAPIResponseException when response contains an error
  217 + //! \throws nlohmann::json::parse_error when response could not be parsed
198 218 virtual bool setName(const std::string& name);
199 219  
200 220 //! \brief Const function that returns the color type of the light.
... ... @@ -237,9 +257,14 @@ public:
237 257 //!
238 258 //! \note The brightness will only be set if the light has a reference to a
239 259 //! specific \ref BrightnessStrategy. The brightness can range from 0 = off to
240   - //! 254 = fully lit. \param bri Unsigned int that specifies the brightness
241   - //! \param transition Optional parameter to set the transition from current
242   - //! state to new, standard is 4 = 400ms \return Bool that is true on success
  260 + //! 254 = fully lit.
  261 + //! \param bri Unsigned int that specifies the brightness
  262 + //! \param transition Optional parameter to set the transition from current state to new, standard is 4 = 400ms
  263 + //! \return Bool that is true on success
  264 + //! \throws std::system_error when system or socket operations fail
  265 + //! \throws HueException when response contained no body
  266 + //! \throws HueAPIResponseException when response contains an error
  267 + //! \throws nlohmann::json::parse_error when response could not be parsed
243 268 virtual bool setBrightness(unsigned int bri, uint8_t transition = 4)
244 269 {
245 270 if (brightnessStrategy)
... ... @@ -268,7 +293,12 @@ public:
268 293 //!
269 294 //! \note The brightness will only be returned if the light has a reference to
270 295 //! a specific \ref BrightnessStrategy. The brightness can range from 0 = off
271   - //! to 254 = fully lit. \return Unsigned int that is 0 when function failed
  296 + //! to 254 = fully lit.
  297 + //! \return Unsigned int that is 0 when function failed
  298 + //! \throws std::system_error when system or socket operations fail
  299 + //! \throws HueException when response contained no body
  300 + //! \throws HueAPIResponseException when response contains an error
  301 + //! \throws nlohmann::json::parse_error when response could not be parsed
272 302 virtual unsigned int getBrightness()
273 303 {
274 304 if (brightnessStrategy)
... ... @@ -282,10 +312,14 @@ public:
282 312 //!
283 313 //! \note The color temperature will only be set if the light has a reference
284 314 //! to a specific \ref ColorTemperatureStrategy. The color temperature can
285   - //! range from 153 to 500. \param mired Unsigned int that specifies the color
286   - //! temperature in Mired \param transition Optional parameter to set the
287   - //! transition from current state to new, standard is 4 = 400ms \return Bool
288   - //! that is true on success
  315 + //! range from 153 to 500.
  316 + //! \param mired Unsigned int that specifies the color temperature in Mired
  317 + //! \param transition Optional parameter to set the transition from current state to new, standard is 4 = 400ms
  318 + //! \return Bool that is true on success
  319 + //! \throws std::system_error when system or socket operations fail
  320 + //! \throws HueException when response contained no body
  321 + //! \throws HueAPIResponseException when response contains an error
  322 + //! \throws nlohmann::json::parse_error when response could not be parsed
289 323 virtual bool setColorTemperature(unsigned int mired, uint8_t transition = 4)
290 324 {
291 325 if (colorTemperatureStrategy)
... ... @@ -319,8 +353,13 @@ public:
319 353 //! reference to a specific \ref ColorTemperatureStrategy.
320 354 //! Updates the lights state by calling refreshState()
321 355 //! The color temperature in mired ranges from 153 to 500 whereas 153 is cold
322   - //! and 500 is warm. \param light A reference of the light \return Unsigned
323   - //! int representing the color temperature in mired or 0 when failed
  356 + //! and 500 is warm.
  357 + //! \param light A reference of the light
  358 + //! \return Unsigned int representing the color temperature in mired or 0 when failed
  359 + //! \throws std::system_error when system or socket operations fail
  360 + //! \throws HueException when response contained no body
  361 + //! \throws HueAPIResponseException when response contains an error
  362 + //! \throws nlohmann::json::parse_error when response could not be parsed
324 363 virtual unsigned int getColorTemperature()
325 364 {
326 365 if (colorTemperatureStrategy)
... ... @@ -334,10 +373,14 @@ public:
334 373 //!
335 374 //! \note The color will only be set if the light has a reference to a
336 375 //! specific \ref ColorHueStrategy. The hue can range from 0 to 65535, whereas
337   - //! 65535 and 0 are red, 25500 is green and 46920 is blue. \param hue uint16_t
338   - //! that specifies the hue \param transition Optional parameter to set the
339   - //! transition from current state to new, standard is 4 = 400ms \return Bool
340   - //! that is true on success
  376 + //! 65535 and 0 are red, 25500 is green and 46920 is blue.
  377 + //! \param hue uint16_t that specifies the hue
  378 + //! \param transition Optional parameter to set the transition from current state to new, standard is 4 = 400ms
  379 + //! \return Bool that is true on success
  380 + //! \throws std::system_error when system or socket operations fail
  381 + //! \throws HueException when response contained no body
  382 + //! \throws HueAPIResponseException when response contains an error
  383 + //! \throws nlohmann::json::parse_error when response could not be parsed
341 384 virtual bool setColorHue(uint16_t hue, uint8_t transition = 4)
342 385 {
343 386 if (colorHueStrategy)
... ... @@ -351,10 +394,14 @@ public:
351 394 //!
352 395 //! \note The color will only be set if the light has a reference to a
353 396 //! specific \ref ColorHueStrategy. The saturation can range from 0 to 254,
354   - //! whereas 0 is least saturated (white) and 254 is most saturated. \param sat
355   - //! uint8_t that specifies the saturation \param transition Optional parameter
356   - //! to set the transition from current state to new, standard is 4 = 400ms
  397 + //! whereas 0 is least saturated (white) and 254 is most saturated.
  398 + //! \param sat uint8_t that specifies the saturation
  399 + //! \param transition Optional parameter to set the transition from current state to new, standard is 4 = 400ms
357 400 //! \return Bool that is true on success
  401 + //! \throws std::system_error when system or socket operations fail
  402 + //! \throws HueException when response contained no body
  403 + //! \throws HueAPIResponseException when response contains an error
  404 + //! \throws nlohmann::json::parse_error when response could not be parsed
358 405 virtual bool setColorSaturation(uint8_t sat, uint8_t transition = 4)
359 406 {
360 407 if (colorHueStrategy)
... ... @@ -368,10 +415,15 @@ public:
368 415 //! saturation.
369 416 //!
370 417 //! \note The color will only be set if the light has a reference to a
371   - //! specific \ref ColorHueStrategy. \param hue uint16_t that specifies the hue
  418 + //! specific \ref ColorHueStrategy.
  419 + //! \param hue uint16_t that specifies the hue
372 420 //! \param sat uint8_t that specifies the saturation
373   - //! \param transition Optional parameter to set the transition from current
374   - //! state to new, standard is 4 = 400ms. \return Bool that is true on success
  421 + //! \param transition Optional parameter to set the transition from current state to new, standard is 4 = 400ms.
  422 + //! \return Bool that is true on success
  423 + //! \throws std::system_error when system or socket operations fail
  424 + //! \throws HueException when response contained no body
  425 + //! \throws HueAPIResponseException when response contains an error
  426 + //! \throws nlohmann::json::parse_error when response could not be parsed
375 427 virtual bool setColorHueSaturation(uint16_t hue, uint8_t sat, uint8_t transition = 4)
376 428 {
377 429 if (colorHueStrategy)
... ... @@ -388,8 +440,11 @@ public:
388 440 //! has a reference to a specific \ref ColorHueStrategy.
389 441 //! \note This will not refresh the light state
390 442 //! \param light A reference of the light
391   - //! \return Pair containing the hue as first value and saturation as second
392   - //! value or an empty one when failed
  443 + //! \return Pair containing the hue as first value and saturation as second value or an empty one when failed
  444 + //! \throws std::system_error when system or socket operations fail
  445 + //! \throws HueException when response contained no body
  446 + //! \throws HueAPIResponseException when response contains an error
  447 + //! \throws nlohmann::json::parse_error when response could not be parsed
393 448 virtual std::pair<uint16_t, uint8_t> getColorHueSaturation() const
394 449 {
395 450 if (colorHueStrategy)
... ... @@ -406,8 +461,11 @@ public:
406 461 //! has a reference to a specific \ref ColorHueStrategy. Updates the lights
407 462 //! state by calling refreshState()
408 463 //! \param light A const reference of the light
409   - //! \return Pair containing the hue as first value and saturation as second
410   - //! value or an empty one when failed
  464 + //! \return Pair containing the hue as first value and saturation as second value or an empty one when failed
  465 + //! \throws std::system_error when system or socket operations fail
  466 + //! \throws HueException when response contained no body
  467 + //! \throws HueAPIResponseException when response contains an error
  468 + //! \throws nlohmann::json::parse_error when response could not be parsed
411 469 virtual std::pair<uint16_t, uint8_t> getColorHueSaturation()
412 470 {
413 471 if (colorHueStrategy)
... ... @@ -420,11 +478,15 @@ public:
420 478 //! \brief Function to set the color of this light in CIE with specified x y.
421 479 //!
422 480 //! \note The color will only be set if the light has a reference to a
423   - //! specific \ref ColorHueStrategy. The values of x and y are ranging from 0
424   - //! to 1. \param x float that specifies the x coordinate in CIE \param y float
425   - //! that specifies the y coordinate in CIE \param transition Optional
426   - //! parameter to set the transition from current state to new, standard is 4 =
427   - //! 400ms \return Bool that is true on success
  481 + //! specific \ref ColorHueStrategy. The values of x and y are ranging from 0 to 1.
  482 + //! \param x float that specifies the x coordinate in CIE
  483 + //! \param y float that specifies the y coordinate in CIE
  484 + //! \param transition Optional parameter to set the transition from current state to new, standard is 4 = 400ms
  485 + //! \return Bool that is true on success
  486 + //! \throws std::system_error when system or socket operations fail
  487 + //! \throws HueException when response contained no body
  488 + //! \throws HueAPIResponseException when response contains an error
  489 + //! \throws nlohmann::json::parse_error when response could not be parsed
428 490 virtual bool setColorXY(float x, float y, uint8_t transition = 4)
429 491 {
430 492 if (colorHueStrategy)
... ... @@ -457,8 +519,11 @@ public:
457 519 //! reference to a specific \ref ColorHueStrategy.
458 520 //! Updates the lights state by calling refreshState()
459 521 //! \param light A reference of the light
460   - //! \return Pair containing the x as first value and y as second value or an
461   - //! empty one when failed
  522 + //! \return Pair containing the x as first value and y as second value or an empty one when failed
  523 + //! \throws std::system_error when system or socket operations fail
  524 + //! \throws HueException when response contained no body
  525 + //! \throws HueAPIResponseException when response contains an error
  526 + //! \throws nlohmann::json::parse_error when response could not be parsed
462 527 virtual std::pair<float, float> getColorXY()
463 528 {
464 529 if (colorHueStrategy)
... ... @@ -476,8 +541,12 @@ public:
476 541 //! ranging from 0 to 255. \param r uint8_t that specifies the red color value
477 542 //! \param g uint8_t that specifies the green color value
478 543 //! \param b uint8_t that specifies the blue color value
479   - //! \param transition Optional parameter to set the transition from current
480   - //! state to new, standard is 4 = 400ms \return Bool that is true on success
  544 + //! \param transition Optional parameter to set the transition from current state to new, standard is 4 = 400ms
  545 + //! \return Bool that is true on success
  546 + //! \throws std::system_error when system or socket operations fail
  547 + //! \throws HueException when response contained no body
  548 + //! \throws HueAPIResponseException when response contains an error
  549 + //! \throws nlohmann::json::parse_error when response could not be parsed
481 550 virtual bool setColorRGB(uint8_t r, uint8_t g, uint8_t b, uint8_t transition = 4)
482 551 {
483 552 if (colorHueStrategy)
... ... @@ -491,14 +560,23 @@ public:
491 560 //!
492 561 //! Can be used for locating a light.
493 562 //! \return bool that is true on success
  563 + //! \throws std::system_error when system or socket operations fail
  564 + //! \throws HueException when response contained no body
  565 + //! \throws HueAPIResponseException when response contains an error
  566 + //! \throws nlohmann::json::parse_error when response could not be parsed
494 567 virtual bool alert();
495 568  
496 569 //! \brief Function that lets the light perform one breath cycle in specified
497 570 //! color temperature.
498 571 //!
499 572 //! \note The breath cylce will only be performed if the light has a reference
500   - //! to a specific \ref ColorTemperatureStrategy. \param mired Color
501   - //! temperature in mired \return Bool that is true on success
  573 + //! to a specific \ref ColorTemperatureStrategy.
  574 + //! \param mired Color temperature in mired
  575 + //! \return Bool that is true on success
  576 + //! \throws std::system_error when system or socket operations fail
  577 + //! \throws HueException when response contained no body
  578 + //! \throws HueAPIResponseException when response contains an error
  579 + //! \throws nlohmann::json::parse_error when response could not be parsed
502 580 virtual bool alertTemperature(unsigned int mired)
503 581 {
504 582 if (colorTemperatureStrategy)
... ... @@ -512,9 +590,14 @@ public:
512 590 //! color.
513 591 //!
514 592 //! \note The breath cylce will only be performed if the light has a reference
515   - //! to a specific \ref ColorHueStrategy. \param hue uint16_t that specifies
516   - //! the hue \param sat uint8_t that specifies the saturation \return Bool that
517   - //! is true on success
  593 + //! to a specific \ref ColorHueStrategy.
  594 + //! \param hue uint16_t that specifies the hue
  595 + //! \param sat uint8_t that specifies the saturation
  596 + //! \return Bool that is true on success
  597 + //! \throws std::system_error when system or socket operations fail
  598 + //! \throws HueException when response contained no body
  599 + //! \throws HueAPIResponseException when response contains an error
  600 + //! \throws nlohmann::json::parse_error when response could not be parsed
518 601 virtual bool alertHueSaturation(uint16_t hue, uint8_t sat)
519 602 {
520 603 if (colorHueStrategy)
... ... @@ -529,9 +612,14 @@ public:
529 612 //!
530 613 //! \note The breath cylce will only be performed if the light has a reference
531 614 //! to a specific \ref ColorHueStrategy. The values of x and y are ranging
532   - //! from 0 to 1. \param x float that specifies the x coordinate in CIE \param
533   - //! y float that specifies the y coordinate in CIE \return Bool that is true
534   - //! on success
  615 + //! from 0 to 1.
  616 + //! \param x float that specifies the x coordinate in CIE
  617 + //! \param y float that specifies the y coordinate in CIE
  618 + //! \return Bool that is true on success
  619 + //! \throws std::system_error when system or socket operations fail
  620 + //! \throws HueException when response contained no body
  621 + //! \throws HueAPIResponseException when response contains an error
  622 + //! \throws nlohmann::json::parse_error when response could not be parsed
535 623 virtual bool alertXY(float x, float y)
536 624 {
537 625 if (colorHueStrategy)
... ... @@ -546,10 +634,15 @@ public:
546 634 //!
547 635 //! \note The breath cylce will only be performed if the light has a reference
548 636 //! to a specific \ref ColorHueStrategy. The values of red, green and blue are
549   - //! ranging from 0 to 255. \param r uint8_t that specifies the red color value
  637 + //! ranging from 0 to 255.
  638 + //! \param r uint8_t that specifies the red color value
550 639 //! \param g uint8_t that specifies the green color value
551 640 //! \param b uint8_t that specifies the blue color value
552 641 //! \return Bool that is true on success
  642 + //! \throws std::system_error when system or socket operations fail
  643 + //! \throws HueException when response contained no body
  644 + //! \throws HueAPIResponseException when response contains an error
  645 + //! \throws nlohmann::json::parse_error when response could not be parsed
553 646 virtual bool alertRGB(uint8_t r, uint8_t g, uint8_t b)
554 647 {
555 648 if (colorHueStrategy)
... ... @@ -570,6 +663,10 @@ public:
570 663 //! alternatively call Off() and then use any of the setter functions. \param
571 664 //! on bool that enables this feature when true and disables it when false
572 665 //! \return Bool that is true on success
  666 + //! \throws std::system_error when system or socket operations fail
  667 + //! \throws HueException when response contained no body
  668 + //! \throws HueAPIResponseException when response contains an error
  669 + //! \throws nlohmann::json::parse_error when response could not be parsed
573 670 virtual bool setColorLoop(bool on)
574 671 {
575 672 if (colorHueStrategy)
... ... @@ -596,6 +693,10 @@ protected:
596 693 //! \param brightnessStrategy Strategy for brightness. May be nullptr.
597 694 //! \param colorTempStrategy Strategy for color temperature. May be nullptr.
598 695 //! \param colorHueStrategy Strategy for color hue/saturation. May be nullptr.
  696 + //! \throws std::system_error when system or socket operations fail
  697 + //! \throws HueException when response contained no body
  698 + //! \throws HueAPIResponseException when response contains an error
  699 + //! \throws nlohmann::json::parse_error when response could not be parsed
599 700 HueLight(int id, const HueCommandAPI& commands, std::shared_ptr<const BrightnessStrategy> brightnessStrategy,
600 701 std::shared_ptr<const ColorTemperatureStrategy> colorTempStrategy,
601 702 std::shared_ptr<const ColorHueStrategy> colorHueStrategy);
... ... @@ -637,25 +738,41 @@ protected:
637 738  
638 739 //! \brief Function that turns the light on without refreshing its state.
639 740 //!
640   - //! \param transition Optional parameter to set the transition from current
641   - //! state to new standard is 4 = 400ms \return Bool that is true on success
  741 + //! \param transition Optional parameter to set the transition from current state to new standard is 4 = 400ms
  742 + //! \return Bool that is true on success
  743 + //! \throws std::system_error when system or socket operations fail
  744 + //! \throws HueException when response contained no body
  745 + //! \throws HueAPIResponseException when response contains an error
  746 + //! \throws nlohmann::json::parse_error when response could not be parsed
642 747 virtual bool OnNoRefresh(uint8_t transition = 4);
643 748  
644 749 //! \brief Function that turns the light off without refreshing its state.
645 750 //!
646   - //! \param transition Optional parameter to set the transition from current
647   - //! state to new standard is 4 = 400ms \return Bool that is true on success
  751 + //! \param transition Optional parameter to set the transition from current state to new standard is 4 = 400ms
  752 + //! \return Bool that is true on success
  753 + //! \throws std::system_error when system or socket operations fail
  754 + //! \throws HueException when response contained no body
  755 + //! \throws HueAPIResponseException when response contains an error
  756 + //! \throws nlohmann::json::parse_error when response could not be parsed
648 757 virtual bool OffNoRefresh(uint8_t transition = 4);
649 758  
650 759 //! \brief Utility function to send a put request to the light.
651 760 //!
652 761 //! \throws nlohmann::json::parse_error if the reply could not be parsed
653 762 //! \param request A nlohmann::json aka the request to send
654   - //! \param subPath A path that is appended to the uri, note it should always
655   - //! start with a slash ("/") \return The parsed reply
  763 + //! \param subPath A path that is appended to the uri, note it should always start with a slash ("/")
  764 + //! \return The parsed reply
  765 + //! \throws std::system_error when system or socket operations fail
  766 + //! \throws HueException when response contained no body
  767 + //! \throws HueAPIResponseException when response contains an error
  768 + //! \throws nlohmann::json::parse_error when response could not be parsed
656 769 virtual nlohmann::json SendPutRequest(const nlohmann::json& request, const std::string& subPath, FileInfo fileInfo);
657 770  
658 771 //! \brief Virtual function that refreshes the \ref state of the light.
  772 + //! \throws std::system_error when system or socket operations fail
  773 + //! \throws HueException when response contained no body
  774 + //! \throws HueAPIResponseException when response contains an error
  775 + //! \throws nlohmann::json::parse_error when response could not be parsed
659 776 virtual void refreshState();
660 777  
661 778 protected:
... ...
hueplusplus/include/UPnP.h
  View file @62e4a11
... ... @@ -33,13 +33,13 @@
33 33 class UPnP
34 34 {
35 35 public:
36   - //! \brief Function that searches for UPnP devices and returns all found ones.
  36 + //! \brief Searches for UPnP devices and returns all found ones.
37 37 //!
38   - //! It does it by sending an m-search packet and waits for all responses.
39   - //! Since responses can be received multiple times this function conveniently
40   - //! removes all duplicates. \param handler HttpHandler of type \ref
41   - //! IHttpHandler for communication with the bridge \return A vector containing
42   - //! pairs of address and name of all found devices
  38 + //! It does it by sending an m-search packet and waits for all responses.
  39 + //! Since responses can be received multiple times this function conveniently removes all duplicates.
  40 + //! \param handler HttpHandler for communication
  41 + //! \return A vector containing pairs of address and name of all found devices
  42 + //! \throws std::system_error when system or socket operations fail
43 43 std::vector<std::pair<std::string, std::string>> getDevices(std::shared_ptr<const IHttpHandler> handler);
44 44 };
45 45  
... ...
hueplusplus/include/WinHttpHandler.h
  View file @62e4a11
... ... @@ -48,7 +48,7 @@ public:
48 48 //! decimal notation like "192.168.2.1" \param port Optional integer that
49 49 //! specifies the port to which the request is sent to. Default is 80 \return
50 50 //! String containing the response of the host
51   - std::string send(const std::string& msg, const std::string& adr, int port = 80) const;
  51 + std::string send(const std::string& msg, const std::string& adr, int port = 80) const override;
52 52  
53 53 //! \brief Function that sends a multicast request with the specified message.
54 54 //!
... ... @@ -59,8 +59,8 @@ public:
59 59 //! 1900 \param timeout Optional Integer that specifies the timeout of the
60 60 //! request in seconds. Default is 5 \return Vector containing strings of each
61 61 //! answer received
62   - std::vector<std::string> sendMulticast(
63   - const std::string& msg, const std::string& adr = "239.255.255.250", int port = 1900, int timeout = 5) const;
  62 + std::vector<std::string> sendMulticast(const std::string& msg, const std::string& adr = "239.255.255.250",
  63 + int port = 1900, int timeout = 5) const override;
64 64  
65 65 private:
66 66 WSADATA wsaData;
... ...