Host library for controlling a WiConnect enabled Wi-Fi module.
Dependents: wiconnect-ota_example wiconnect-web_setup_example wiconnect-test-console wiconnect-tcp_server_example ... more
GhmInterface.h
00001 /** 00002 * ACKme WiConnect Host Library is licensed under the BSD licence: 00003 * 00004 * Copyright (c)2014 ACKme Networks. 00005 * All rights reserved. 00006 * 00007 * Redistribution and use in source and binary forms, with or without modification, 00008 * are permitted provided that the following conditions are met: 00009 * 00010 * 1. Redistributions of source code must retain the above copyright notice, 00011 * this list of conditions and the following disclaimer. 00012 * 2. Redistributions in binary form must reproduce the above copyright notice, 00013 * this list of conditions and the following disclaimer in the documentation 00014 * and/or other materials provided with the distribution. 00015 * 3. The name of the author may not be used to endorse or promote products 00016 * derived from this software without specific prior written permission. 00017 * 00018 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS AND ANY EXPRESS OR IMPLIED 00019 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF 00020 * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT 00021 * SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 00022 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT 00023 * OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 00024 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 00025 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING 00026 * IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY 00027 * OF SUCH DAMAGE. 00028 */ 00029 #pragma once 00030 00031 #include "Wiconnect.h" 00032 00033 #include "api/types/WiconnectSocket.h" 00034 #include "api/types/GhmMessageList.h" 00035 00036 /** 00037 * @namespace wiconnect 00038 */ 00039 namespace wiconnect { 00040 00041 /** 00042 * @ingroup api_ghm_macro 00043 * @brief Helper macro for adding an integer value to a @ref GhmElementArray 00044 */ 00045 #define GHM_ADD_INT(array, name, integerVal) \ 00046 { \ 00047 array.elementName = name; \ 00048 array.type = GHM_VALUE_INT; \ 00049 array.u.intValue = (uint32_t)integerVal; \ 00050 } 00051 00052 00053 /** 00054 * @ingroup api_ghm_macro 00055 * @brief Helper macro for adding a string value to a @ref GhmElementArray 00056 */ 00057 #define GHM_ADD_STR(array, name, stringVal) \ 00058 { \ 00059 array.elementName = name; \ 00060 array.type = GHM_VALUE_STR; \ 00061 array.u.strValue = (const char*)stringVal; \ 00062 } 00063 00064 00065 00066 00067 /** 00068 * @ingroup api_ghm_types 00069 * 00070 * @brief The provides an interface for http://goHACK.me 00071 * 00072 * The goHACK.me API provided by WiConnect enables monitoring and control of your ACKme device. 00073 * You can set up a goHACK.me account, then using goHACK.me commands and goHACK.me variables, 00074 * you can activate your device and synchronize data, control and messages with the goHACK.me cloud service. 00075 * 00076 * More information here: http://wiconnect.ack.me/2.0/gohackme 00077 * 00078 * @note This class is an interface to the Wiconnect class. It should never be 00079 * independently instantiated or the parent of another class. 00080 */ 00081 class GhmInterface 00082 { 00083 public: 00084 00085 /** 00086 * @ingroup api_ghm_activate 00087 * 00088 * @brief Download a device capabilities file to WiFi module's internal 00089 * file system. 00090 * 00091 * @param[in] capsNameOrCustomUrl Optional, specify the caps file name or URL to caps file 00092 * @param[in] version Optional, version to set downloaded caps file as 00093 * @return Result of method. See @ref WiconnectResult 00094 */ 00095 WiconnectResult ghmDownloadCapabilities(const char *capsNameOrCustomUrl = NULL, uint32_t version = 0); 00096 00097 /** 00098 * @ingroup api_ghm_activate 00099 * 00100 * @brief Activate WiFi module with http://goHACK.me 00101 * 00102 * @note You must first sign-up with http://goHACK.me before you can 00103 * activate the device. Go to http://goHACK.me to sign-up. 00104 * 00105 * @param[in] userName Your username 00106 * @param[in] password Your password 00107 * @param[in] capsFilename Optional, filename of existing capabilities file on module's internal file system. 00108 * @return Result of method. See @ref WiconnectResult 00109 */ 00110 WiconnectResult ghmActivate(const char *userName, const char *password, const char *capsFilename = NULL); 00111 00112 /** 00113 * @ingroup api_ghm_activate 00114 * 00115 * @brief Deactivate WiFi module with http://goHACK.me 00116 * 00117 * @note You must first sign-up with http://goHACK.me before you can 00118 * deactivate the device. Go to http://goHACK.me to sign-up. 00119 * 00120 * @param[in] userName Your username 00121 * @param[in] password Your password 00122 * @return Result of method. See @ref WiconnectResult 00123 */ 00124 WiconnectResult ghmDeactivate(const char *userName, const char *password); 00125 00126 /** 00127 * @ingroup api_ghm_activate 00128 * 00129 * @brief Return if WiFi module is activated with http://goHACK.me 00130 * 00131 * @param[out] statusPtr Pointer to hold activation status. 00132 * @return Result of method. See @ref WiconnectResult 00133 */ 00134 WiconnectResult ghmIsActivated(bool *statusPtr); 00135 00136 00137 // ------------------------------------------------------------------------ 00138 00139 00140 /** 00141 * @ingroup api_ghm_com 00142 * 00143 * @brief Read control data from http://goHACK.me 00144 * 00145 * @note The WiFi module must first be activated. See @ref ghmActivate() 00146 * 00147 * @param[in] controlName The name of the control in the activated capabilities file. 00148 * @param[in] valueStrPtr Pointer to pointer to hold control's string value 00149 * @return Result of method. See @ref WiconnectResult 00150 */ 00151 WiconnectResult ghmRead(const char *controlName, const char **valueStrPtr); 00152 00153 /** 00154 * @ingroup api_ghm_com 00155 * 00156 * @brief Read control data from http://goHACK.me 00157 * 00158 * @note The WiFi module must first be activated. See @ref ghmActivate() 00159 * 00160 * @param[in] controlName The name of the control in the activated capabilities file. 00161 * @param[in] valueIntPtr Pointer hold control's integer value 00162 * @return Result of method. See @ref WiconnectResult 00163 */ 00164 WiconnectResult ghmRead(const char *controlName, uint32_t *valueIntPtr); 00165 00166 /** 00167 * @ingroup api_ghm_com 00168 * 00169 * @brief Read control data from http://goHACK.me 00170 * 00171 * @note The WiFi module must first be activated. See @ref ghmActivate() 00172 * 00173 * @param[in] controlName The name of the control in the activated capabilities file. 00174 * @param[in] valueBuffer Buffer to hold control's string value 00175 * @param[in] valueBufferLen Length of valueBuffer 00176 * @return Result of method. See @ref WiconnectResult 00177 */ 00178 WiconnectResult ghmRead(const char *controlName, char *valueBuffer, uint16_t valueBufferLen); 00179 00180 /** 00181 * @ingroup api_ghm_com 00182 * 00183 * @brief Write stream or control data to http://goHACK.me 00184 * 00185 * @note The WiFi module must first be activated. See @ref ghmActivate() 00186 * 00187 * @param[in] elementName The name of the control or stream in the activated capabilities file. 00188 * @param[in] strValue String value of control or stream 00189 * @return Result of method. See @ref WiconnectResult 00190 */ 00191 WiconnectResult ghmWrite(const char *elementName, const char *strValue); 00192 00193 /** 00194 * @ingroup api_ghm_com 00195 * 00196 * @brief Write stream or control data to http://goHACK.me 00197 * 00198 * @note The WiFi module must first be activated. See @ref ghmActivate() 00199 * 00200 * @param[in] elementName The name of the control or stream in the activated capabilities file. 00201 * @param[in] uintValue Unsigned integer value of control or stream 00202 * @return Result of method. See @ref WiconnectResult 00203 */ 00204 WiconnectResult ghmWrite(const char *elementName, uint32_t uintValue); 00205 00206 /** 00207 * @ingroup api_ghm_com 00208 * 00209 * @brief Write stream or control data to http://goHACK.me 00210 * 00211 * @note The WiFi module must first be activated. See @ref ghmActivate() 00212 * 00213 * @param[in] elementName The name of the control or stream in the activated capabilities file. 00214 * @param[in] intValue signed integer value of control or stream 00215 * @return Result of method. See @ref WiconnectResult 00216 */ 00217 WiconnectResult ghmWrite(const char *elementName, int32_t intValue); 00218 00219 /** 00220 * @ingroup api_ghm_com 00221 * 00222 * @brief Write stream or control data to http://goHACK.me 00223 * 00224 * @note The WiFi module must first be activated. See @ref ghmActivate() 00225 * 00226 * @param[in] elementArray Array of stream and/or control values to send to http://goHACK.me 00227 * @return Result of method. See @ref WiconnectResult 00228 */ 00229 WiconnectResult ghmWrite(const GhmElementArray *elementArray); 00230 00231 /** 00232 * @ingroup api_ghm_com 00233 * 00234 * @brief Synchronize WiFi module with http://goHACK.me 00235 * 00236 * @note The WiFi module must first be activated. See @ref ghmActivate() 00237 * 00238 * @param[in] type Type of synchronization. See @ref GhmSyncType 00239 * @return Result of method. See @ref WiconnectResult 00240 */ 00241 WiconnectResult ghmSynchronize(GhmSyncType type = GHM_SYNC_ALL); 00242 00243 00244 // ------------------------------------------------------------------------ 00245 00246 00247 /** 00248 * @ingroup api_ghm_msg 00249 * 00250 * @brief POST message to http://goHACK.me 00251 * 00252 * @note The WiFi module must first be activated. See @ref ghmActivate() 00253 * 00254 * @param[out] socket @ref WiconnectSocket used to send message data to http://goHACK.me 00255 * @param[in] jsonFormatted If true, the input message data should be JSON formatted, else the message data should be ASCII formatted. 00256 * @return Result of method. See @ref WiconnectResult 00257 */ 00258 WiconnectResult ghmPostMessage(WiconnectSocket &socket, bool jsonFormatted=false); 00259 00260 /** 00261 * @ingroup api_ghm_msg 00262 * 00263 * @brief GET message from http://goHACK.me 00264 * 00265 * @note The WiFi module must first be activated. See @ref ghmActivate() 00266 * 00267 * @param[out] socket @ref WiconnectSocket used to receive message data from http://goHACK.me 00268 * @param[in] getType The additional message data to receive. See @ref GhmMessageGetType 00269 * @return Result of method. See @ref WiconnectResult 00270 */ 00271 WiconnectResult ghmGetMessage(WiconnectSocket &socket, GhmMessageGetType getType = GHM_MSG_GET_DATA_ONLY); 00272 00273 /** 00274 * @ingroup api_ghm_msg 00275 * 00276 * @brief GET message from http://goHACK.me 00277 * 00278 * @note @ref ghmListMessages() must be called first before using this method. 00279 * 00280 * @note The WiFi module must first be activated. See @ref ghmActivate() 00281 * 00282 * @param[out] socket @ref WiconnectSocket used to receive message data from http://goHACK.me 00283 * @param[in] listIndex The index of the message returned from ghmListMessages() 00284 * @param[in] getType The additional message data to receive. See @ref GhmMessageGetType 00285 * @return Result of method. See @ref WiconnectResult 00286 */ 00287 WiconnectResult ghmGetMessage(WiconnectSocket &socket, uint8_t listIndex, GhmMessageGetType getType = GHM_MSG_GET_DATA_ONLY); 00288 00289 /** 00290 * @ingroup api_ghm_msg 00291 * 00292 * @brief GET message from http://goHACK.me 00293 * 00294 * @note The WiFi module must first be activated. See @ref ghmActivate() 00295 * 00296 * @param[out] socket @ref WiconnectSocket used to receive message data from http://goHACK.me 00297 * @param[in] msgId The http://goHACK.me message ID. 00298 * @param[in] getType The additional message data to receive. See @ref GhmMessageGetType 00299 * @return Result of method. See @ref WiconnectResult 00300 */ 00301 WiconnectResult ghmGetMessage(WiconnectSocket &socket, const char *msgId, GhmMessageGetType getType = GHM_MSG_GET_DATA_ONLY); 00302 00303 /** 00304 * @ingroup api_ghm_msg 00305 * 00306 * @brief Delete message from http://goHACK.me 00307 * 00308 * @note @ref ghmListMessages() must be called first before using this method. 00309 * 00310 * @note The WiFi module must first be activated. See @ref ghmActivate() 00311 * 00312 * @param[in] listIndex The index of the message returned from ghmListMessages() 00313 * @return Result of method. See @ref WiconnectResult 00314 */ 00315 WiconnectResult ghmDeleteMessage(uint8_t listIndex); 00316 00317 /** 00318 * @ingroup api_ghm_msg 00319 * 00320 * @brief Delete message from http://goHACK.me 00321 * 00322 * @note The WiFi module must first be activated. See @ref ghmActivate() 00323 * 00324 * @param[in] msgId The http://goHACK.me message ID. 00325 * @return Result of method. See @ref WiconnectResult 00326 */ 00327 WiconnectResult ghmDeleteMessage(const char *msgId); 00328 00329 /** 00330 * @ingroup api_ghm_msg 00331 * 00332 * @brief List available messages for device on http://goHACK.me 00333 * 00334 * @note The WiFi module must first be activated. See @ref ghmActivate() 00335 * 00336 * @param[out] msgList @ref GhmMessageList to hold received messages. 00337 * @param[in] maxCount Optional, the maximum number of messages to receive. If 0, 00338 * receive all messages (max of 25). 00339 * @return Result of method. See @ref WiconnectResult 00340 */ 00341 WiconnectResult ghmListMessages(GhmMessageList &msgList, uint8_t maxCount = 0); 00342 00343 00344 protected: 00345 GhmInterface(Wiconnect *wiconnect); 00346 00347 WiconnectResult ghmGetMessage(WiconnectSocket &socket, uint8_t listIndex, const char *msgId, GhmMessageGetType getType); 00348 WiconnectResult processMessageList(char *resultStr, GhmMessageList &resultList); 00349 00350 private: 00351 Wiconnect *wiconnect; 00352 00353 }; 00354 00355 00356 }
Generated on Tue Jul 12 2022 17:35:58 by 1.7.2