ACKme / WiConnect

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

api/README.h@29:b6af04b77a56, 2014-10-27 (annotated)

Committer:
dan_ackme
Date:
Mon Oct 27 13:42:26 2014 -0700
Revision:
29:b6af04b77a56
Child:
34:2616445d0823
refactored library layout

Who changed what in which revision?

UserRevisionLine numberNew contents of line
dan_ackme 29:b6af04b77a56 1 /**
dan_ackme 29:b6af04b77a56 2 * @mainpage Library Overview
dan_ackme 29:b6af04b77a56 3 *
dan_ackme 29:b6af04b77a56 4 * @section Overview
dan_ackme 29:b6af04b77a56 5 * The WiConnect Library runs on a host MCU and controls a
dan_ackme 29:b6af04b77a56 6 * WiConnect enabled WiFi module. This library is essentially a
dan_ackme 29:b6af04b77a56 7 * programming API for the WiConnect serial command set. More infomation
dan_ackme 29:b6af04b77a56 8 * about the serial command set may be found here:
dan_ackme 29:b6af04b77a56 9 * <a href="http://wiconnect.ack.me" target="_blank">WiConnect Reference Guide</a>
dan_ackme 29:b6af04b77a56 10 *
dan_ackme 29:b6af04b77a56 11 * @section notes Important Notes
dan_ackme 29:b6af04b77a56 12 * - This class is implemented as a 'singleton'. This means it only needs to be
dan_ackme 29:b6af04b77a56 13 * instantiated once.
dan_ackme 29:b6af04b77a56 14 * - The WiConnect library does NOT call the global 'new' or 'malloc' functions.
dan_ackme 29:b6af04b77a56 15 * All memory allocation (if required) comes from a user supplied malloc function pointer or buffer
dan_ackme 29:b6af04b77a56 16 *
dan_ackme 29:b6af04b77a56 17 *
dan_ackme 29:b6af04b77a56 18 * @section features Library Settings
dan_ackme 29:b6af04b77a56 19 * The WiConnect Library has multiple settings so as to allow
dan_ackme 29:b6af04b77a56 20 * for the most flexibility within a user's application.
dan_ackme 29:b6af04b77a56 21 *
dan_ackme 29:b6af04b77a56 22 * Some of these configurations are as follows:
dan_ackme 29:b6af04b77a56 23 * - Blocking / Non-blocking
dan_ackme 29:b6af04b77a56 24 * - Dynamic / Static allocation
dan_ackme 29:b6af04b77a56 25 * - Asynchronous Processing
dan_ackme 29:b6af04b77a56 26 *
dan_ackme 29:b6af04b77a56 27 *
dan_ackme 29:b6af04b77a56 28 * @subsection setting_blocking_modes Blocking / Non-blocking Modes
dan_ackme 29:b6af04b77a56 29 * The WiConnect Library may be configured for either 'blocking' or
dan_ackme 29:b6af04b77a56 30 * 'non-blocking' operation:
dan_ackme 29:b6af04b77a56 31 * - blocking - API calls do not return until they complete successfully or timeout.
dan_ackme 29:b6af04b77a56 32 * - non-blocking - API calls return immediately. The caller should check the return code to see
dan_ackme 29:b6af04b77a56 33 * if the command is still processing, completed, or an error occurred. The caller
dan_ackme 29:b6af04b77a56 34 * should continue to call the API function (as often as possible) until it returns
dan_ackme 29:b6af04b77a56 35 * either a success or error code.
dan_ackme 29:b6af04b77a56 36 *
dan_ackme 29:b6af04b77a56 37 * @subsubsection setting_blocking_mode Blocking Mode
dan_ackme 29:b6af04b77a56 38 * In blocking mode, an API function will block until it completes.
dan_ackme 29:b6af04b77a56 39 * More details to come...
dan_ackme 29:b6af04b77a56 40 *
dan_ackme 29:b6af04b77a56 41 * @subsubsection setting_nonblocking_mode Non-Blocking Mode
dan_ackme 29:b6af04b77a56 42 * In non-blocking mode, an API function returns immediately.
dan_ackme 29:b6af04b77a56 43 * More details to come...
dan_ackme 29:b6af04b77a56 44 *
dan_ackme 29:b6af04b77a56 45 *
dan_ackme 29:b6af04b77a56 46 *
dan_ackme 29:b6af04b77a56 47 * @subsection setting_alloc Dynamic / Static Allocation
dan_ackme 29:b6af04b77a56 48 * There are two cases when memory allocation is required:
dan_ackme 29:b6af04b77a56 49 * - Buffer allocation
dan_ackme 29:b6af04b77a56 50 * - Class instantiation
dan_ackme 29:b6af04b77a56 51 *
dan_ackme 29:b6af04b77a56 52 * In both cases, either static or dynamic memory allocation may be used.
dan_ackme 29:b6af04b77a56 53 *
dan_ackme 29:b6af04b77a56 54 * In cases when memory allocation is needed, the API call requires a buffer pointer
dan_ackme 29:b6af04b77a56 55 * and length parameters. If both are supplied, the library uses the supplied external buffer.
dan_ackme 29:b6af04b77a56 56 * This is considered static allocation (however the buffer could have been dynamically allocated).
dan_ackme 29:b6af04b77a56 57 * The caller is responsible for maintaining the supplied buffer.
dan_ackme 29:b6af04b77a56 58 *
dan_ackme 29:b6af04b77a56 59 * If, however, only the buffer length is supplied and the buffer pointer is NULL
dan_ackme 29:b6af04b77a56 60 * the Wiconnect Library will call the user supplied malloc() function. This is considered
dan_ackme 29:b6af04b77a56 61 * dynamic allocation. In this case, the library will maintain the buffer and release it
dan_ackme 29:b6af04b77a56 62 * when necessary using the user supplied free() function.
dan_ackme 29:b6af04b77a56 63 *
dan_ackme 29:b6af04b77a56 64 * @note To use dynamic allocation the WiConnect Library must be compiled with
dan_ackme 29:b6af04b77a56 65 * @ref WICONNECT_ENABLE_MALLOC defined, and the Wiconnect() constructor must be
dan_ackme 29:b6af04b77a56 66 * supplied with pointers to malloc() and free() functions.
dan_ackme 29:b6af04b77a56 67 *
dan_ackme 29:b6af04b77a56 68 * @note The Wiconnect Library does NOT call the global 'new' operator. Classes that are
dan_ackme 29:b6af04b77a56 69 * internally instantiated overload the 'new' operator and either call the user
dan_ackme 29:b6af04b77a56 70 * supplied malloc() function or use the supplied static buffer.
dan_ackme 29:b6af04b77a56 71 *
dan_ackme 29:b6af04b77a56 72 *
dan_ackme 29:b6af04b77a56 73 * @subsection setting_async_processing Asynchronous Processing
dan_ackme 29:b6af04b77a56 74 * When applicable, the WiConnect Library will asynchronously process
dan_ackme 29:b6af04b77a56 75 * commands in the background. When the background processing completes, the
dan_ackme 29:b6af04b77a56 76 * supplied callback is called.
dan_ackme 29:b6af04b77a56 77 *
dan_ackme 29:b6af04b77a56 78 * User commands may also be executed in the background using the enqueueCommand()
dan_ackme 29:b6af04b77a56 79 * API function.
dan_ackme 29:b6af04b77a56 80 *
dan_ackme 29:b6af04b77a56 81 * @note The WiConnect Library must be compiled with @ref WICONNECT_ASYNC_TIMER_ENABLED
dan_ackme 29:b6af04b77a56 82 * defined for background processing to be enabled.
dan_ackme 29:b6af04b77a56 83 *
dan_ackme 29:b6af04b77a56 84 *
dan_ackme 29:b6af04b77a56 85 *
dan_ackme 29:b6af04b77a56 86 * @section send_command_desc Sending Commands To WiFi Module
dan_ackme 29:b6af04b77a56 87 * More details to come...
dan_ackme 29:b6af04b77a56 88 *
dan_ackme 29:b6af04b77a56 89 *
dan_ackme 29:b6af04b77a56 90 */
dan_ackme 29:b6af04b77a56 91
dan_ackme 29:b6af04b77a56 92 // ----------------------------------------------------------------------------
dan_ackme 29:b6af04b77a56 93
dan_ackme 29:b6af04b77a56 94 /**
dan_ackme 29:b6af04b77a56 95 * @defgroup api_core Core
dan_ackme 29:b6af04b77a56 96 * @brief This contains all core related operations
dan_ackme 29:b6af04b77a56 97 *
dan_ackme 29:b6af04b77a56 98 * @{
dan_ackme 29:b6af04b77a56 99 */
dan_ackme 29:b6af04b77a56 100
dan_ackme 29:b6af04b77a56 101 /**
dan_ackme 29:b6af04b77a56 102 * @defgroup api_core_settings Settings Methods
dan_ackme 29:b6af04b77a56 103 * @brief API getters/setters for core library settings
dan_ackme 29:b6af04b77a56 104 */
dan_ackme 29:b6af04b77a56 105
dan_ackme 29:b6af04b77a56 106 /**
dan_ackme 29:b6af04b77a56 107 * @defgroup api_core_send_command Send Command Methods
dan_ackme 29:b6af04b77a56 108 * @brief API methods for sending commands to WiConnect WiFi module
dan_ackme 29:b6af04b77a56 109 */
dan_ackme 29:b6af04b77a56 110
dan_ackme 29:b6af04b77a56 111 /**
dan_ackme 29:b6af04b77a56 112 * @defgroup api_core_misc Miscellaneous Methods
dan_ackme 29:b6af04b77a56 113 * @brief Other core methods
dan_ackme 29:b6af04b77a56 114 */
dan_ackme 29:b6af04b77a56 115
dan_ackme 29:b6af04b77a56 116 /**
dan_ackme 29:b6af04b77a56 117 * @defgroup api_core_types Types
dan_ackme 29:b6af04b77a56 118 * @brief Core Types
dan_ackme 29:b6af04b77a56 119 */
dan_ackme 29:b6af04b77a56 120
dan_ackme 29:b6af04b77a56 121
dan_ackme 29:b6af04b77a56 122 /**
dan_ackme 29:b6af04b77a56 123 * @defgroup api_core_macro Macros
dan_ackme 29:b6af04b77a56 124 * @brief Core macros
dan_ackme 29:b6af04b77a56 125 */
dan_ackme 29:b6af04b77a56 126
dan_ackme 29:b6af04b77a56 127 /**
dan_ackme 29:b6af04b77a56 128 * @defgroup api_core_examples Examples
dan_ackme 29:b6af04b77a56 129 * @brief Core examples
dan_ackme 29:b6af04b77a56 130 * * @ref ota/example.cpp
dan_ackme 29:b6af04b77a56 131 */
dan_ackme 29:b6af04b77a56 132
dan_ackme 29:b6af04b77a56 133 // @}
dan_ackme 29:b6af04b77a56 134
dan_ackme 29:b6af04b77a56 135
dan_ackme 29:b6af04b77a56 136 // ----------------------------------------------------------------------------
dan_ackme 29:b6af04b77a56 137
dan_ackme 29:b6af04b77a56 138 /**
dan_ackme 29:b6af04b77a56 139 * @defgroup api_network Network
dan_ackme 29:b6af04b77a56 140 * @brief This contains all network related operations
dan_ackme 29:b6af04b77a56 141 *
dan_ackme 29:b6af04b77a56 142 * @{
dan_ackme 29:b6af04b77a56 143 */
dan_ackme 29:b6af04b77a56 144
dan_ackme 29:b6af04b77a56 145 /**
dan_ackme 29:b6af04b77a56 146 * @defgroup api_network_settings Settings Methods
dan_ackme 29:b6af04b77a56 147 * @brief API getters/setters for module network settings
dan_ackme 29:b6af04b77a56 148 */
dan_ackme 29:b6af04b77a56 149
dan_ackme 29:b6af04b77a56 150 /**
dan_ackme 29:b6af04b77a56 151 * @defgroup api_network_wlan WLAN Methods
dan_ackme 29:b6af04b77a56 152 * @brief Methods for joining/leaving a WLAN
dan_ackme 29:b6af04b77a56 153 */
dan_ackme 29:b6af04b77a56 154
dan_ackme 29:b6af04b77a56 155 /**
dan_ackme 29:b6af04b77a56 156 * @defgroup api_network_setup Web Setup Methods
dan_ackme 29:b6af04b77a56 157 * @brief Methods for enabled/disabling module web setup
dan_ackme 29:b6af04b77a56 158 */
dan_ackme 29:b6af04b77a56 159
dan_ackme 29:b6af04b77a56 160 /**
dan_ackme 29:b6af04b77a56 161 * @defgroup api_network_util Utility Methods
dan_ackme 29:b6af04b77a56 162 * @brief Network utility methods
dan_ackme 29:b6af04b77a56 163 */
dan_ackme 29:b6af04b77a56 164
dan_ackme 29:b6af04b77a56 165 /**
dan_ackme 29:b6af04b77a56 166 * @defgroup api_network_types Types
dan_ackme 29:b6af04b77a56 167 * @brief Network Types
dan_ackme 29:b6af04b77a56 168 */
dan_ackme 29:b6af04b77a56 169
dan_ackme 29:b6af04b77a56 170 /**
dan_ackme 29:b6af04b77a56 171 * @defgroup api_network_macros Macros
dan_ackme 29:b6af04b77a56 172 * @brief Network specific macros
dan_ackme 29:b6af04b77a56 173 */
dan_ackme 29:b6af04b77a56 174
dan_ackme 29:b6af04b77a56 175 /**
dan_ackme 29:b6af04b77a56 176 * @defgroup api_network_examples Examples
dan_ackme 29:b6af04b77a56 177 * @brief Network examples
dan_ackme 29:b6af04b77a56 178 * * @ref web_setup/example.cpp
dan_ackme 29:b6af04b77a56 179 * * @ref join/example.cpp
dan_ackme 29:b6af04b77a56 180 */
dan_ackme 29:b6af04b77a56 181
dan_ackme 29:b6af04b77a56 182 // @}
dan_ackme 29:b6af04b77a56 183
dan_ackme 29:b6af04b77a56 184
dan_ackme 29:b6af04b77a56 185 // ----------------------------------------------------------------------------
dan_ackme 29:b6af04b77a56 186
dan_ackme 29:b6af04b77a56 187 /**
dan_ackme 29:b6af04b77a56 188 * @defgroup api_socket Socket
dan_ackme 29:b6af04b77a56 189 * @brief This contains all socket related operations
dan_ackme 29:b6af04b77a56 190 *
dan_ackme 29:b6af04b77a56 191 * @{
dan_ackme 29:b6af04b77a56 192 */
dan_ackme 29:b6af04b77a56 193
dan_ackme 29:b6af04b77a56 194 /**
dan_ackme 29:b6af04b77a56 195 * @defgroup api_socket_tcp TCP Methods
dan_ackme 29:b6af04b77a56 196 * @brief TCP methods
dan_ackme 29:b6af04b77a56 197 */
dan_ackme 29:b6af04b77a56 198
dan_ackme 29:b6af04b77a56 199 /**
dan_ackme 29:b6af04b77a56 200 * @defgroup api_socket_udp UDP Methods
dan_ackme 29:b6af04b77a56 201 * @brief UDP methods
dan_ackme 29:b6af04b77a56 202 */
dan_ackme 29:b6af04b77a56 203
dan_ackme 29:b6af04b77a56 204 /**
dan_ackme 29:b6af04b77a56 205 * @defgroup api_socket_tls TLS Methods
dan_ackme 29:b6af04b77a56 206 * @brief TLS methods
dan_ackme 29:b6af04b77a56 207 */
dan_ackme 29:b6af04b77a56 208
dan_ackme 29:b6af04b77a56 209 /**
dan_ackme 29:b6af04b77a56 210 * @defgroup api_socket_http HTTP Methods
dan_ackme 29:b6af04b77a56 211 * @brief HTTP methods
dan_ackme 29:b6af04b77a56 212 */
dan_ackme 29:b6af04b77a56 213
dan_ackme 29:b6af04b77a56 214 /**
dan_ackme 29:b6af04b77a56 215 * @defgroup api_socket_misc Miscellaneous Methods
dan_ackme 29:b6af04b77a56 216 * @brief Miscellaneous socket methods
dan_ackme 29:b6af04b77a56 217 */
dan_ackme 29:b6af04b77a56 218
dan_ackme 29:b6af04b77a56 219 /**
dan_ackme 29:b6af04b77a56 220 * @defgroup api_socket_types Types
dan_ackme 29:b6af04b77a56 221 * @brief Socket Types
dan_ackme 29:b6af04b77a56 222 */
dan_ackme 29:b6af04b77a56 223
dan_ackme 29:b6af04b77a56 224 /**
dan_ackme 29:b6af04b77a56 225 * @defgroup api_socket_macro Macros
dan_ackme 29:b6af04b77a56 226 * @brief Socket specific macros
dan_ackme 29:b6af04b77a56 227 */
dan_ackme 29:b6af04b77a56 228
dan_ackme 29:b6af04b77a56 229 /**
dan_ackme 29:b6af04b77a56 230 * @defgroup api_socket_examples Examples
dan_ackme 29:b6af04b77a56 231 * @brief Socket examples
dan_ackme 29:b6af04b77a56 232 * * @ref http_get/example.cpp
dan_ackme 29:b6af04b77a56 233 * * @ref tcp_server/example.cpp
dan_ackme 29:b6af04b77a56 234 *
dan_ackme 29:b6af04b77a56 235 */
dan_ackme 29:b6af04b77a56 236
dan_ackme 29:b6af04b77a56 237 // @}
dan_ackme 29:b6af04b77a56 238
dan_ackme 29:b6af04b77a56 239
dan_ackme 29:b6af04b77a56 240 // ----------------------------------------------------------------------------
dan_ackme 29:b6af04b77a56 241
dan_ackme 29:b6af04b77a56 242 /**
dan_ackme 29:b6af04b77a56 243 * @defgroup api_file File
dan_ackme 29:b6af04b77a56 244 * @brief This contains all file related operations
dan_ackme 29:b6af04b77a56 245 *
dan_ackme 29:b6af04b77a56 246 * @{
dan_ackme 29:b6af04b77a56 247 */
dan_ackme 29:b6af04b77a56 248
dan_ackme 29:b6af04b77a56 249 /**
dan_ackme 29:b6af04b77a56 250 * @defgroup api_file_methods Methods
dan_ackme 29:b6af04b77a56 251 * @brief File methods
dan_ackme 29:b6af04b77a56 252 */
dan_ackme 29:b6af04b77a56 253
dan_ackme 29:b6af04b77a56 254 /**
dan_ackme 29:b6af04b77a56 255 * @defgroup api_file_types Types
dan_ackme 29:b6af04b77a56 256 * @brief File types
dan_ackme 29:b6af04b77a56 257 */
dan_ackme 29:b6af04b77a56 258
dan_ackme 29:b6af04b77a56 259 /**
dan_ackme 29:b6af04b77a56 260 * @defgroup api_file_macro Macros
dan_ackme 29:b6af04b77a56 261 * @brief API specific macros
dan_ackme 29:b6af04b77a56 262 */
dan_ackme 29:b6af04b77a56 263
dan_ackme 29:b6af04b77a56 264 /**
dan_ackme 29:b6af04b77a56 265 * @defgroup api_file_examples Examples
dan_ackme 29:b6af04b77a56 266 * @brief File examples
dan_ackme 29:b6af04b77a56 267 */
dan_ackme 29:b6af04b77a56 268
dan_ackme 29:b6af04b77a56 269 // @}
dan_ackme 29:b6af04b77a56 270
dan_ackme 29:b6af04b77a56 271 // ----------------------------------------------------------------------------
dan_ackme 29:b6af04b77a56 272
dan_ackme 29:b6af04b77a56 273 /**
dan_ackme 29:b6af04b77a56 274 * @defgroup api_ghm goHACK.me
dan_ackme 29:b6af04b77a56 275 * @brief This contains all goHACK.me related operations
dan_ackme 29:b6af04b77a56 276 *
dan_ackme 29:b6af04b77a56 277 * @{
dan_ackme 29:b6af04b77a56 278 */
dan_ackme 29:b6af04b77a56 279
dan_ackme 29:b6af04b77a56 280 /**
dan_ackme 29:b6af04b77a56 281 * @defgroup api_ghm_activate Activation
dan_ackme 29:b6af04b77a56 282 * @brief Methods for activating/deactivating the module with http://goHACK.me
dan_ackme 29:b6af04b77a56 283 */
dan_ackme 29:b6af04b77a56 284
dan_ackme 29:b6af04b77a56 285 /**
dan_ackme 29:b6af04b77a56 286 * @defgroup api_ghm_com Read/Write
dan_ackme 29:b6af04b77a56 287 * @brief Methods for reading & writing data from/to http://goHACK.me
dan_ackme 29:b6af04b77a56 288 */
dan_ackme 29:b6af04b77a56 289
dan_ackme 29:b6af04b77a56 290 /**
dan_ackme 29:b6af04b77a56 291 * @defgroup api_ghm_msg Message
dan_ackme 29:b6af04b77a56 292 * @brief Methods for getting, posting, listing, deleting messages wtih http://goHACK.me
dan_ackme 29:b6af04b77a56 293 */
dan_ackme 29:b6af04b77a56 294
dan_ackme 29:b6af04b77a56 295 /**
dan_ackme 29:b6af04b77a56 296 * @defgroup api_ghm_types Types
dan_ackme 29:b6af04b77a56 297 * @brief goHACK.me Types
dan_ackme 29:b6af04b77a56 298 */
dan_ackme 29:b6af04b77a56 299
dan_ackme 29:b6af04b77a56 300 /**
dan_ackme 29:b6af04b77a56 301 * @defgroup api_ghm_macro Macros
dan_ackme 29:b6af04b77a56 302 * @brief API specific macros
dan_ackme 29:b6af04b77a56 303 */
dan_ackme 29:b6af04b77a56 304
dan_ackme 29:b6af04b77a56 305 /**
dan_ackme 29:b6af04b77a56 306 * @defgroup api_ghm_examples Examples
dan_ackme 29:b6af04b77a56 307 * @brief goHACK.me examples
dan_ackme 29:b6af04b77a56 308 */
dan_ackme 29:b6af04b77a56 309
dan_ackme 29:b6af04b77a56 310 // @}
dan_ackme 29:b6af04b77a56 311
dan_ackme 29:b6af04b77a56 312 // ----------------------------------------------------------------------------
dan_ackme 29:b6af04b77a56 313
dan_ackme 29:b6af04b77a56 314 /**
dan_ackme 29:b6af04b77a56 315 * @defgroup conversion_util Conversion Utilities
dan_ackme 29:b6af04b77a56 316 * @brief This contains all the conversion utility static functions.
dan_ackme 29:b6af04b77a56 317 *
dan_ackme 29:b6af04b77a56 318 */
dan_ackme 29:b6af04b77a56 319
dan_ackme 29:b6af04b77a56 320