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

Embed: (wiki syntax)

« Back to documentation index

Show/hide line numbers SocketInterface.h Source File

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 }