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
SocketInterface.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 #include "types/WiconnectSocket.h" 00033 #include "types/WiconnectUdpServer.h" 00034 00035 #ifdef WICONNECT_GPIO_IRQ_ENABLED 00036 #include "types/SocketIrqHandlerMap.h" 00037 #endif 00038 00039 /** 00040 * @namespace wiconnect 00041 */ 00042 namespace wiconnect { 00043 00044 #ifdef WICONNECT_GPIO_IRQ_ENABLED 00045 #define GPIO_IRQ_ARG_NC ,Pin irqPin = PIN_NC 00046 #define GPIO_IRQ_ARG ,Pin irqPin 00047 #define GPIO_IRQ_PARAM ,irqPin 00048 #else 00049 #define GPIO_IRQ_ARG_NC 00050 #define GPIO_IRQ_ARG 00051 #define GPIO_IRQ_PARAM 00052 #endif 00053 00054 /** 00055 * @ingroup api_socket_types 00056 * 00057 * @brief The provides an interface for creating TCP/UDP/TLS/HTTP client sockets. 00058 * A client socket connects to a remote server. 00059 * 00060 * @note This class is an interface to the Wiconnect class. It should never be 00061 * independently instantiated or the parent of another class. 00062 */ 00063 class SocketInterface 00064 { 00065 public: 00066 /** 00067 * @ingroup api_socket_misc 00068 * 00069 * @brief Close all opened sockets. 00070 * 00071 * @note This closes all open sockets on the MODULE side. 00072 * Socket objects on the HOST side will be still open until 00073 * issuing a read/write command to the module using the socket handle. 00074 * 00075 * @return Result of method. See @ref WiconnectResult 00076 */ 00077 WiconnectResult closeAllSockets(); 00078 00079 #ifdef WICONNECT_GPIO_IRQ_ENABLED 00080 /** 00081 * @ingroup api_socket_misc 00082 * 00083 * @brief Register a host pin as an external interrupt. When the external interrupt is 00084 * triggered, the supplied callback is executed. 00085 * 00086 * @note WICONNECT_GPIO_IRQ_ENABLED must be defined to use this feature 00087 * 00088 * This should be called before calling one of the connect methods below 00089 * with an irqPin parameter. 00090 * 00091 * Basically how this works is: 00092 * 1. The supplied irqPin is configured as an external interrupt pin. 00093 * 2. A connection is opened and configured with the same irqPin. This 00094 * irqPin physically connected to a GPIO on the WiFi module. 00095 * 3. When the WiFi module has data to send to the HOST it asserts the irqPin. 00096 * 4. The irqPin interrupt executes and calls the supplied handler. 00097 * 5. The handler should notify the HOST that the given irqPin has triggered 00098 * and have the associated socket read data from the module. 00099 * 00100 * @note arg1 of the handler contains the irqPin 00101 * 00102 * 00103 * @param[in] irqPin The HOST pin to configure as an external interrupt. 00104 * This pin should be physically connected to a module GPIO. 00105 * @param[in] handler Callback to be executed with the external irqPin interrupt triggers 00106 * @return Result of method. See @ref WiconnectResult 00107 */ 00108 WiconnectResult registerSocketIrqHandler(Pin irqPin, const Callback &handler); 00109 00110 /** 00111 * @ingroup api_socket_misc 00112 * 00113 * @brief Unregister a previously registered IRQ pin. 00114 * 00115 * This disables the given irqPin as an external interrupt. 00116 * Refer to registerSocketIrqHandler() for more information. 00117 * 00118 * @param[in] irqPin The HOST pin to unregister 00119 * @return Result of method. See @ref WiconnectResult 00120 */ 00121 WiconnectResult unregisterSocketIrqHandler(Pin irqPin); 00122 #endif 00123 00124 /** 00125 * @ingroup api_socket_misc 00126 * 00127 * @brief Connect to remote server. 00128 * 00129 * This is the base method used by all the other connect methods. 00130 * 00131 * @param[out] socket @ref WiconnectSocket object of opened connection. 00132 * @param[in] type The @ref SocketType of connection to open 00133 * @param[in] host The host/IP address of the remote server 00134 * @param[in] remortPort The port of the remote server 00135 * @param[in] localPort The port of the module's side of the connection 00136 * @param[in] args Depedent on the connection type 00137 * @param[in] irqPin Data available external interrupt pin. See registerSocketIrqHandler() for more info 00138 * @return Result of method. See @ref WiconnectResult 00139 */ 00140 WiconnectResult connect(WiconnectSocket &socket, SocketType type, const char *host, uint16_t remortPort, uint16_t localPort, const void *args GPIO_IRQ_ARG); 00141 00142 00143 // ------------------------------------------------------------------------ 00144 00145 /** 00146 * @ingroup api_socket_tcp 00147 * 00148 * @brief Connect to remote TCP server. 00149 * 00150 * @param[out] socket TCP @ref WiconnectSocket object of opened connection. 00151 * @param[in] host The host/IP address of the remote TCP server 00152 * @param[in] remortPort The port of the remote server 00153 * @param[in] irqPin Optional, Data available external interrupt pin. See registerSocketIrqHandler() for more info 00154 * @return Result of method. See @ref WiconnectResult 00155 */ 00156 WiconnectResult tcpConnect(WiconnectSocket &socket, const char *host, uint16_t remortPort GPIO_IRQ_ARG_NC); 00157 00158 00159 // ------------------------------------------------------------------------ 00160 00161 /** 00162 * @ingroup api_socket_tcp 00163 * 00164 * @brief Start internal TCP server and listen on specified port. 00165 * 00166 * @param[in] listeningPort The local port the server should listen on 00167 * @param[in] maxClients Optional, the maximum simultaneous connected clients, 0 is default, 1-8 valid range 00168 * @param[in] irqPin Optional, Data available external interrupt pin. See registerSocketIrqHandler() for more info 00169 * @return Result of method. See @ref WiconnectResult 00170 */ 00171 WiconnectResult tcpListen(uint16_t listeningPort, int maxClients = 0 GPIO_IRQ_ARG_NC); 00172 00173 00174 // ------------------------------------------------------------------------ 00175 00176 /** 00177 * @ingroup api_socket_tcp 00178 * 00179 * @brief Wait for next client to connect to TCP server. 00180 * 00181 * @param[in] socket Socket to connected client 00182 * @param[in] timeoutMs Optional, specifiy maximum amount of time in ms to wait for a client 00183 * @return Result of method. See @ref WiconnectResult 00184 */ 00185 WiconnectResult tcpAccept(WiconnectSocket &socket, uint32_t timeoutMs = WICONNECT_WAIT_FOREVER); 00186 00187 00188 // ------------------------------------------------------------------------ 00189 00190 /** 00191 * @ingroup api_socket_tcp 00192 * 00193 * @brief Stop TCP server from listening on port. Close all connected clients. 00194 * 00195 * @return Result of method. See @ref WiconnectResult 00196 */ 00197 WiconnectResult tcpServerStop(void); 00198 00199 00200 // ------------------------------------------------------------------------ 00201 00202 /** 00203 * @ingroup api_socket_tls 00204 * 00205 * @brief Connect to remote TLS server. 00206 * 00207 * @param[out] socket TLS @ref WiconnectSocket object of opened connection. 00208 * @param[in] host The host/IP address of the remote TLS server 00209 * @param[in] remortPort The port of the remote server 00210 * @param[in] certFilename Optional, filename of certificate on module's file system 00211 * @param[in] irqPin Optional, Data available external interrupt pin. See registerSocketIrqHandler() for more info 00212 * @return Result of method. See @ref WiconnectResult 00213 */ 00214 WiconnectResult tlsConnect(WiconnectSocket &socket, const char *host, uint16_t remortPort, const char *certFilename = NULL GPIO_IRQ_ARG_NC); 00215 00216 00217 // ------------------------------------------------------------------------ 00218 00219 /** 00220 * @ingroup api_socket_udp 00221 * 00222 * @brief Connect to remote UDP server. 00223 * 00224 * @param[out] socket UDP @ref WiconnectSocket object of opened connection. 00225 * @param[in] host The host/IP address of the remote UDP server 00226 * @param[in] remortPort The port of the remote server 00227 * @param[in] localPort Optional, port of module's side of the connection 00228 * @param[in] irqPin Optional, Data available external interrupt pin. See registerSocketIrqHandler() for more info 00229 * @return Result of method. See @ref WiconnectResult 00230 */ 00231 WiconnectResult udpConnect(WiconnectSocket &socket, const char *host, uint16_t remortPort, uint16_t localPort = SOCKET_ANY_PORT GPIO_IRQ_ARG_NC); 00232 00233 /** 00234 * @ingroup api_socket_udp 00235 * 00236 * @brief Start a UDP server listening on the given port 00237 * 00238 * @param[out] udpServer UDP @ref WiconnectUdpServer object listening server 00239 * @param[in] listeningPort The port the UDP server listens on 00240 * @return Result of method. See @ref WiconnectResult 00241 */ 00242 WiconnectResult udpListen(WiconnectUdpServer &udpServer, uint16_t listeningPort); 00243 00244 00245 // ------------------------------------------------------------------------ 00246 00247 /** 00248 * @ingroup api_socket_http 00249 * 00250 * @brief Connect to remote HTTP server. 00251 * 00252 * This is the base method for the other HTTP methods. 00253 * 00254 * @section secure_http_connection Secure HTTP 00255 * Each HTTP method is able to connect to a secure HTTP server. To do this, 00256 * the URL string parameter must start with 'https://' 00257 * To connect to a secure HTTP server a TLS certificate is needed. The certificate 00258 * is specified in the certFilename parameter of the method (or @ref HttpSocketArgs parameter). 00259 * This is the filename of an existing certificate on the module file system. 00260 * 00261 * @note If the URL starts with 'https://' and no certificate filename is specified, 00262 * the module's default certificate is used. 00263 * 00264 * @param[out] socket HTTP @ref WiconnectSocket object of opened connection. 00265 * @param[in] url URL of HTTP request 00266 * @param[in] args Configuration @ref HttpSocketArgs for HTTP connection 00267 * @return Result of method. See @ref WiconnectResult 00268 */ 00269 WiconnectResult httpConnect(WiconnectSocket &socket, const char *url, const HttpSocketArgs *args); 00270 00271 /** 00272 * @ingroup api_socket_http 00273 * 00274 * @brief Issue HTTP GET Request 00275 * 00276 * This method has the open to only 'open' the connection (disabled by default). This means a connection 00277 * to the remote HTTP server is opened, but the HTTP request isn't issued. This 00278 * allow for addition data to be added to the request. For instance, use httpAddHeader() to add 00279 * additional headers to the request. 00280 * Use httpGetStatus() to issue the HTTP request and receive the HTTP response. 00281 * 00282 * @param[out] socket HTTP @ref WiconnectSocket object of opened connection. 00283 * @param[in] url URL of HTTP GET request 00284 * @param[in] openOnly Optional, if TRUE this will only open a connection to the server (it won't issue the request) 00285 * @param[in] certFilename Optional, filename of existing TLS certificate on module's file system. See @ref secure_http_connection 00286 * @return Result of method. See @ref WiconnectResult 00287 */ 00288 WiconnectResult httpGet(WiconnectSocket &socket, const char *url, bool openOnly = false, const char *certFilename = NULL); 00289 00290 /** 00291 * @ingroup api_socket_http 00292 * 00293 * @brief Issue HTTP POST Request 00294 * 00295 * This method has the open to only 'open' the connection which enabled by default. This means a connection 00296 * to the remote HTTP server is opened, but the HTTP request isn't issued. This 00297 * allow for addition data to be added to the request. Use the returned @ref WiconnectSocket object's 'write' methods 00298 * to add POST data to the request. 00299 * When all POST data has been written, use httpGetStatus() to issue the HTTP request and receive the HTTP response. 00300 * 00301 * @param[out] socket HTTP @ref WiconnectSocket object of opened connection. 00302 * @param[in] url URL of HTTP POST request 00303 * @param[in] contextType The value to go into the 'content-type' HTTP header (e.g. 'application/json') 00304 * @param[in] openOnly Optional, if FALSE this will immediately issue the POST request. 00305 * @param[in] certFilename Optional, filename of existing TLS certificate on module's file system. See @ref secure_http_connection 00306 * @return Result of method. See @ref WiconnectResult 00307 */ 00308 WiconnectResult httpPost(WiconnectSocket &socket, const char *url, const char *contextType, bool openOnly = true, const char *certFilename = NULL); 00309 00310 /** 00311 * @ingroup api_socket_http 00312 * 00313 * @brief Issue HTTP HEAD Request 00314 * 00315 * @param[out] socket HTTP @ref WiconnectSocket object of opened connection. 00316 * @param[in] url URL of HTTP HEAD request 00317 * @param[in] certFilename Optional, filename of existing TLS certificate on module's file system. See @ref secure_http_connection 00318 * @return Result of method. See @ref WiconnectResult 00319 */ 00320 WiconnectResult httpHead(WiconnectSocket &socket, const char *url, const char *certFilename = NULL); 00321 00322 /** 00323 * @ingroup api_socket_http 00324 * 00325 * @brief Add HTTP header key/value pair to opened HTTP request. 00326 * 00327 * To use this function, the supplied @ref WiconnectSocket parameter must have been created 00328 * using either httpGet() or httpPost() and the 'openOnly' parameter TRUE. 00329 * 00330 * This will add additional header to the HTTP request. 00331 * 00332 * Use httpGetStatus() to issue the request. 00333 * 00334 * @param[in] socket Opened socket to add additonal HTTP header 00335 * @param[in] key Header key (e.g. 'content-type') 00336 * @param[in] value Header value (e.g. 'application/json') 00337 * @return Result of method. See @ref WiconnectResult 00338 */ 00339 WiconnectResult httpAddHeader(WiconnectSocket &socket, const char *key, const char *value); 00340 00341 /** 00342 * @ingroup api_socket_http 00343 * 00344 * @brief Get the HTTP status code from HTTP request. 00345 * 00346 * This may be used to either issue an HTTP request of an opened HTTP connection 00347 * or return the status code of a request already issued. 00348 * 00349 * @param[in] socket Opened socket to get http response status code 00350 * @param[out] statusCodePtr Pointer to uint32 to hold http status code 00351 * @return Result of method. See @ref WiconnectResult 00352 */ 00353 WiconnectResult httpGetStatus(WiconnectSocket &socket, uint32_t *statusCodePtr); 00354 00355 protected: 00356 SocketInterface(Wiconnect *wiconnect); 00357 ~SocketInterface(); 00358 00359 #ifdef WICONNECT_GPIO_IRQ_ENABLED 00360 SocketIrqHandlerMap irqHandlers; 00361 #endif 00362 00363 uint32_t serverConnectedClientList; 00364 00365 WiconnectResult pollForServerClient(uint8_t *handle = NULL, uint16_t *localPort = NULL, uint16_t *remotePort = NULL, uint32_t *ipAddress = NULL); 00366 00367 void socketClosedCallback(const WiconnectSocket *socket); 00368 00369 friend class GhmInterface; 00370 00371 private: 00372 Wiconnect *wiconnect; 00373 }; 00374 00375 }
Generated on Tue Jul 12 2022 17:35:58 by 1.7.2