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/SocketInterface.h@29:b6af04b77a56, 2014-10-27 (annotated)
- Committer:
- dan_ackme
- Date:
- Mon Oct 27 13:42:26 2014 -0700
- Revision:
- 29:b6af04b77a56
- Child:
- 39:a963f69cb2de
refactored library layout
Who changed what in which revision?
User | Revision | Line number | New contents of line |
---|---|---|---|
dan_ackme | 29:b6af04b77a56 | 1 | /** |
dan_ackme | 29:b6af04b77a56 | 2 | * ACKme WiConnect Host Library is licensed under the BSD licence: |
dan_ackme | 29:b6af04b77a56 | 3 | * |
dan_ackme | 29:b6af04b77a56 | 4 | * Copyright (c)2014 ACKme Networks. |
dan_ackme | 29:b6af04b77a56 | 5 | * All rights reserved. |
dan_ackme | 29:b6af04b77a56 | 6 | * |
dan_ackme | 29:b6af04b77a56 | 7 | * Redistribution and use in source and binary forms, with or without modification, |
dan_ackme | 29:b6af04b77a56 | 8 | * are permitted provided that the following conditions are met: |
dan_ackme | 29:b6af04b77a56 | 9 | * |
dan_ackme | 29:b6af04b77a56 | 10 | * 1. Redistributions of source code must retain the above copyright notice, |
dan_ackme | 29:b6af04b77a56 | 11 | * this list of conditions and the following disclaimer. |
dan_ackme | 29:b6af04b77a56 | 12 | * 2. Redistributions in binary form must reproduce the above copyright notice, |
dan_ackme | 29:b6af04b77a56 | 13 | * this list of conditions and the following disclaimer in the documentation |
dan_ackme | 29:b6af04b77a56 | 14 | * and/or other materials provided with the distribution. |
dan_ackme | 29:b6af04b77a56 | 15 | * 3. The name of the author may not be used to endorse or promote products |
dan_ackme | 29:b6af04b77a56 | 16 | * derived from this software without specific prior written permission. |
dan_ackme | 29:b6af04b77a56 | 17 | * |
dan_ackme | 29:b6af04b77a56 | 18 | * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS AND ANY EXPRESS OR IMPLIED |
dan_ackme | 29:b6af04b77a56 | 19 | * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF |
dan_ackme | 29:b6af04b77a56 | 20 | * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT |
dan_ackme | 29:b6af04b77a56 | 21 | * SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, |
dan_ackme | 29:b6af04b77a56 | 22 | * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT |
dan_ackme | 29:b6af04b77a56 | 23 | * OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS |
dan_ackme | 29:b6af04b77a56 | 24 | * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN |
dan_ackme | 29:b6af04b77a56 | 25 | * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING |
dan_ackme | 29:b6af04b77a56 | 26 | * IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY |
dan_ackme | 29:b6af04b77a56 | 27 | * OF SUCH DAMAGE. |
dan_ackme | 29:b6af04b77a56 | 28 | */ |
dan_ackme | 29:b6af04b77a56 | 29 | #pragma once |
dan_ackme | 29:b6af04b77a56 | 30 | |
dan_ackme | 29:b6af04b77a56 | 31 | #include "Wiconnect.h" |
dan_ackme | 29:b6af04b77a56 | 32 | #include "types/WiconnectSocket.h" |
dan_ackme | 29:b6af04b77a56 | 33 | #include "types/WiconnectUdpServer.h" |
dan_ackme | 29:b6af04b77a56 | 34 | |
dan_ackme | 29:b6af04b77a56 | 35 | #ifdef WICONNECT_GPIO_IRQ_ENABLED |
dan_ackme | 29:b6af04b77a56 | 36 | #include "types/SocketIrqHandlerMap.h" |
dan_ackme | 29:b6af04b77a56 | 37 | #endif |
dan_ackme | 29:b6af04b77a56 | 38 | |
dan_ackme | 29:b6af04b77a56 | 39 | /** |
dan_ackme | 29:b6af04b77a56 | 40 | * @namespace wiconnect |
dan_ackme | 29:b6af04b77a56 | 41 | */ |
dan_ackme | 29:b6af04b77a56 | 42 | namespace wiconnect { |
dan_ackme | 29:b6af04b77a56 | 43 | |
dan_ackme | 29:b6af04b77a56 | 44 | #ifdef WICONNECT_GPIO_IRQ_ENABLED |
dan_ackme | 29:b6af04b77a56 | 45 | #define GPIO_IRQ_ARG_NC ,Pin irqPin = PIN_NC |
dan_ackme | 29:b6af04b77a56 | 46 | #define GPIO_IRQ_ARG ,Pin irqPin |
dan_ackme | 29:b6af04b77a56 | 47 | #define GPIO_IRQ_PARAM ,irqPin |
dan_ackme | 29:b6af04b77a56 | 48 | #else |
dan_ackme | 29:b6af04b77a56 | 49 | #define GPIO_IRQ_ARG_NC |
dan_ackme | 29:b6af04b77a56 | 50 | #define GPIO_IRQ_ARG |
dan_ackme | 29:b6af04b77a56 | 51 | #define GPIO_IRQ_PARAM |
dan_ackme | 29:b6af04b77a56 | 52 | #endif |
dan_ackme | 29:b6af04b77a56 | 53 | |
dan_ackme | 29:b6af04b77a56 | 54 | /** |
dan_ackme | 29:b6af04b77a56 | 55 | * @ingroup api_socket_types |
dan_ackme | 29:b6af04b77a56 | 56 | * |
dan_ackme | 29:b6af04b77a56 | 57 | * @brief The provides an interface for creating TCP/UDP/TLS/HTTP client sockets. |
dan_ackme | 29:b6af04b77a56 | 58 | * A client socket connects to a remote server. |
dan_ackme | 29:b6af04b77a56 | 59 | * |
dan_ackme | 29:b6af04b77a56 | 60 | * @note This class is an interface to the Wiconnect class. It should never be |
dan_ackme | 29:b6af04b77a56 | 61 | * independently instantiated or the parent of another class. |
dan_ackme | 29:b6af04b77a56 | 62 | */ |
dan_ackme | 29:b6af04b77a56 | 63 | class SocketInterface |
dan_ackme | 29:b6af04b77a56 | 64 | { |
dan_ackme | 29:b6af04b77a56 | 65 | public: |
dan_ackme | 29:b6af04b77a56 | 66 | /** |
dan_ackme | 29:b6af04b77a56 | 67 | * @ingroup api_socket_misc |
dan_ackme | 29:b6af04b77a56 | 68 | * |
dan_ackme | 29:b6af04b77a56 | 69 | * @brief Close all opened sockets. |
dan_ackme | 29:b6af04b77a56 | 70 | * |
dan_ackme | 29:b6af04b77a56 | 71 | * @note This closes all open sockets on the MODULE side. |
dan_ackme | 29:b6af04b77a56 | 72 | * Socket objects on the HOST side will be still open until |
dan_ackme | 29:b6af04b77a56 | 73 | * issuing a read/write command to the module using the socket handle. |
dan_ackme | 29:b6af04b77a56 | 74 | * |
dan_ackme | 29:b6af04b77a56 | 75 | * @return Result of method. See @ref WiconnectResult |
dan_ackme | 29:b6af04b77a56 | 76 | */ |
dan_ackme | 29:b6af04b77a56 | 77 | WiconnectResult closeAllSockets(); |
dan_ackme | 29:b6af04b77a56 | 78 | |
dan_ackme | 29:b6af04b77a56 | 79 | #ifdef WICONNECT_GPIO_IRQ_ENABLED |
dan_ackme | 29:b6af04b77a56 | 80 | /** |
dan_ackme | 29:b6af04b77a56 | 81 | * @ingroup api_socket_misc |
dan_ackme | 29:b6af04b77a56 | 82 | * |
dan_ackme | 29:b6af04b77a56 | 83 | * @brief Register a host pin as an external interrupt. When the external interrupt is |
dan_ackme | 29:b6af04b77a56 | 84 | * triggered, the supplied callback is executed. |
dan_ackme | 29:b6af04b77a56 | 85 | * |
dan_ackme | 29:b6af04b77a56 | 86 | * @note WICONNECT_GPIO_IRQ_ENABLED must be defined to use this feature |
dan_ackme | 29:b6af04b77a56 | 87 | * |
dan_ackme | 29:b6af04b77a56 | 88 | * This should be called before calling one of the connect methods below |
dan_ackme | 29:b6af04b77a56 | 89 | * with an irqPin parameter. |
dan_ackme | 29:b6af04b77a56 | 90 | * |
dan_ackme | 29:b6af04b77a56 | 91 | * Basically how this works is: |
dan_ackme | 29:b6af04b77a56 | 92 | * 1. The supplied irqPin is configured as an external interrupt pin. |
dan_ackme | 29:b6af04b77a56 | 93 | * 2. A connection is opened and configured with the same irqPin. This |
dan_ackme | 29:b6af04b77a56 | 94 | * irqPin physically connected to a GPIO on the WiFi module. |
dan_ackme | 29:b6af04b77a56 | 95 | * 3. When the WiFi module has data to send to the HOST it asserts the irqPin. |
dan_ackme | 29:b6af04b77a56 | 96 | * 4. The irqPin interrupt executes and calls the supplied handler. |
dan_ackme | 29:b6af04b77a56 | 97 | * 5. The handler should notify the HOST that the given irqPin has triggered |
dan_ackme | 29:b6af04b77a56 | 98 | * and have the associated socket read data from the module. |
dan_ackme | 29:b6af04b77a56 | 99 | * |
dan_ackme | 29:b6af04b77a56 | 100 | * @note arg1 of the handler contains the irqPin |
dan_ackme | 29:b6af04b77a56 | 101 | * |
dan_ackme | 29:b6af04b77a56 | 102 | * |
dan_ackme | 29:b6af04b77a56 | 103 | * @param[in] irqPin The HOST pin to configure as an external interrupt. |
dan_ackme | 29:b6af04b77a56 | 104 | * This pin should be physically connected to a module GPIO. |
dan_ackme | 29:b6af04b77a56 | 105 | * @param[in] handler Callback to be executed with the external irqPin interrupt triggers |
dan_ackme | 29:b6af04b77a56 | 106 | * @return Result of method. See @ref WiconnectResult |
dan_ackme | 29:b6af04b77a56 | 107 | */ |
dan_ackme | 29:b6af04b77a56 | 108 | WiconnectResult registerSocketIrqHandler(Pin irqPin, const Callback &handler); |
dan_ackme | 29:b6af04b77a56 | 109 | |
dan_ackme | 29:b6af04b77a56 | 110 | /** |
dan_ackme | 29:b6af04b77a56 | 111 | * @ingroup api_socket_misc |
dan_ackme | 29:b6af04b77a56 | 112 | * |
dan_ackme | 29:b6af04b77a56 | 113 | * @brief Unregister a previously registered IRQ pin. |
dan_ackme | 29:b6af04b77a56 | 114 | * |
dan_ackme | 29:b6af04b77a56 | 115 | * This disables the given irqPin as an external interrupt. |
dan_ackme | 29:b6af04b77a56 | 116 | * Refer to registerSocketIrqHandler() for more information. |
dan_ackme | 29:b6af04b77a56 | 117 | * |
dan_ackme | 29:b6af04b77a56 | 118 | * @param[in] irqPin The HOST pin to unregister |
dan_ackme | 29:b6af04b77a56 | 119 | * @return Result of method. See @ref WiconnectResult |
dan_ackme | 29:b6af04b77a56 | 120 | */ |
dan_ackme | 29:b6af04b77a56 | 121 | WiconnectResult unregisterSocketIrqHandler(Pin irqPin); |
dan_ackme | 29:b6af04b77a56 | 122 | #endif |
dan_ackme | 29:b6af04b77a56 | 123 | |
dan_ackme | 29:b6af04b77a56 | 124 | /** |
dan_ackme | 29:b6af04b77a56 | 125 | * @ingroup api_socket_misc |
dan_ackme | 29:b6af04b77a56 | 126 | * |
dan_ackme | 29:b6af04b77a56 | 127 | * @brief Connect to remote server. |
dan_ackme | 29:b6af04b77a56 | 128 | * |
dan_ackme | 29:b6af04b77a56 | 129 | * This is the base method used by all the other connect methods. |
dan_ackme | 29:b6af04b77a56 | 130 | * |
dan_ackme | 29:b6af04b77a56 | 131 | * @param[out] socket @ref WiconnectSocket object of opened connection. |
dan_ackme | 29:b6af04b77a56 | 132 | * @param[in] type The @ref SocketType of connection to open |
dan_ackme | 29:b6af04b77a56 | 133 | * @param[in] host The host/IP address of the remote server |
dan_ackme | 29:b6af04b77a56 | 134 | * @param[in] remortPort The port of the remote server |
dan_ackme | 29:b6af04b77a56 | 135 | * @param[in] localPort The port of the module's side of the connection |
dan_ackme | 29:b6af04b77a56 | 136 | * @param[in] args Depedent on the connection type |
dan_ackme | 29:b6af04b77a56 | 137 | * @param[in] irqPin Data available external interrupt pin. See registerSocketIrqHandler() for more info |
dan_ackme | 29:b6af04b77a56 | 138 | * @return Result of method. See @ref WiconnectResult |
dan_ackme | 29:b6af04b77a56 | 139 | */ |
dan_ackme | 29:b6af04b77a56 | 140 | WiconnectResult connect(WiconnectSocket &socket, SocketType type, const char *host, uint16_t remortPort, uint16_t localPort, const void *args GPIO_IRQ_ARG); |
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 | * @ingroup api_socket_tcp |
dan_ackme | 29:b6af04b77a56 | 147 | * |
dan_ackme | 29:b6af04b77a56 | 148 | * @brief Connect to remote TCP server. |
dan_ackme | 29:b6af04b77a56 | 149 | * |
dan_ackme | 29:b6af04b77a56 | 150 | * @param[out] socket TCP @ref WiconnectSocket object of opened connection. |
dan_ackme | 29:b6af04b77a56 | 151 | * @param[in] host The host/IP address of the remote TCP server |
dan_ackme | 29:b6af04b77a56 | 152 | * @param[in] remortPort The port of the remote server |
dan_ackme | 29:b6af04b77a56 | 153 | * @param[in] irqPin Optional, Data available external interrupt pin. See registerSocketIrqHandler() for more info |
dan_ackme | 29:b6af04b77a56 | 154 | * @return Result of method. See @ref WiconnectResult |
dan_ackme | 29:b6af04b77a56 | 155 | */ |
dan_ackme | 29:b6af04b77a56 | 156 | WiconnectResult tcpConnect(WiconnectSocket &socket, const char *host, uint16_t remortPort GPIO_IRQ_ARG_NC); |
dan_ackme | 29:b6af04b77a56 | 157 | |
dan_ackme | 29:b6af04b77a56 | 158 | |
dan_ackme | 29:b6af04b77a56 | 159 | // ------------------------------------------------------------------------ |
dan_ackme | 29:b6af04b77a56 | 160 | |
dan_ackme | 29:b6af04b77a56 | 161 | /** |
dan_ackme | 29:b6af04b77a56 | 162 | * @ingroup api_socket_tcp |
dan_ackme | 29:b6af04b77a56 | 163 | * |
dan_ackme | 29:b6af04b77a56 | 164 | * @brief Start internal TCP server and listen on specified port. |
dan_ackme | 29:b6af04b77a56 | 165 | * |
dan_ackme | 29:b6af04b77a56 | 166 | * @param[in] listeningPort The local port the server should listen on |
dan_ackme | 29:b6af04b77a56 | 167 | * @param[in] maxClients Optional, the maximum simultaneous connected clients, 0 is default, 1-8 valid range |
dan_ackme | 29:b6af04b77a56 | 168 | * @param[in] irqPin Optional, Data available external interrupt pin. See registerSocketIrqHandler() for more info |
dan_ackme | 29:b6af04b77a56 | 169 | * @return Result of method. See @ref WiconnectResult |
dan_ackme | 29:b6af04b77a56 | 170 | */ |
dan_ackme | 29:b6af04b77a56 | 171 | WiconnectResult tcpListen(uint16_t listeningPort, int maxClients = 0 GPIO_IRQ_ARG_NC); |
dan_ackme | 29:b6af04b77a56 | 172 | |
dan_ackme | 29:b6af04b77a56 | 173 | |
dan_ackme | 29:b6af04b77a56 | 174 | // ------------------------------------------------------------------------ |
dan_ackme | 29:b6af04b77a56 | 175 | |
dan_ackme | 29:b6af04b77a56 | 176 | /** |
dan_ackme | 29:b6af04b77a56 | 177 | * @ingroup api_socket_tcp |
dan_ackme | 29:b6af04b77a56 | 178 | * |
dan_ackme | 29:b6af04b77a56 | 179 | * @brief Wait for next client to connect to TCP server. |
dan_ackme | 29:b6af04b77a56 | 180 | * |
dan_ackme | 29:b6af04b77a56 | 181 | * @param[in] socket Socket to connected client |
dan_ackme | 29:b6af04b77a56 | 182 | * @param[in] timeoutMs Optional, specifiy maximum amount of time in ms to wait for a client |
dan_ackme | 29:b6af04b77a56 | 183 | * @return Result of method. See @ref WiconnectResult |
dan_ackme | 29:b6af04b77a56 | 184 | */ |
dan_ackme | 29:b6af04b77a56 | 185 | WiconnectResult tcpAccept(WiconnectSocket &socket, uint32_t timeoutMs = WICONNECT_WAIT_FOREVER); |
dan_ackme | 29:b6af04b77a56 | 186 | |
dan_ackme | 29:b6af04b77a56 | 187 | |
dan_ackme | 29:b6af04b77a56 | 188 | // ------------------------------------------------------------------------ |
dan_ackme | 29:b6af04b77a56 | 189 | |
dan_ackme | 29:b6af04b77a56 | 190 | /** |
dan_ackme | 29:b6af04b77a56 | 191 | * @ingroup api_socket_tcp |
dan_ackme | 29:b6af04b77a56 | 192 | * |
dan_ackme | 29:b6af04b77a56 | 193 | * @brief Stop TCP server from listening on port. Close all connected clients. |
dan_ackme | 29:b6af04b77a56 | 194 | * |
dan_ackme | 29:b6af04b77a56 | 195 | * @return Result of method. See @ref WiconnectResult |
dan_ackme | 29:b6af04b77a56 | 196 | */ |
dan_ackme | 29:b6af04b77a56 | 197 | WiconnectResult tcpServerStop(void); |
dan_ackme | 29:b6af04b77a56 | 198 | |
dan_ackme | 29:b6af04b77a56 | 199 | |
dan_ackme | 29:b6af04b77a56 | 200 | // ------------------------------------------------------------------------ |
dan_ackme | 29:b6af04b77a56 | 201 | |
dan_ackme | 29:b6af04b77a56 | 202 | /** |
dan_ackme | 29:b6af04b77a56 | 203 | * @ingroup api_socket_tls |
dan_ackme | 29:b6af04b77a56 | 204 | * |
dan_ackme | 29:b6af04b77a56 | 205 | * @brief Connect to remote TLS server. |
dan_ackme | 29:b6af04b77a56 | 206 | * |
dan_ackme | 29:b6af04b77a56 | 207 | * @param[out] socket TLS @ref WiconnectSocket object of opened connection. |
dan_ackme | 29:b6af04b77a56 | 208 | * @param[in] host The host/IP address of the remote TLS server |
dan_ackme | 29:b6af04b77a56 | 209 | * @param[in] remortPort The port of the remote server |
dan_ackme | 29:b6af04b77a56 | 210 | * @param[in] certFilename Optional, filename of certificate on module's file system |
dan_ackme | 29:b6af04b77a56 | 211 | * @param[in] irqPin Optional, Data available external interrupt pin. See registerSocketIrqHandler() for more info |
dan_ackme | 29:b6af04b77a56 | 212 | * @return Result of method. See @ref WiconnectResult |
dan_ackme | 29:b6af04b77a56 | 213 | */ |
dan_ackme | 29:b6af04b77a56 | 214 | WiconnectResult tlsConnect(WiconnectSocket &socket, const char *host, uint16_t remortPort, const char *certFilename = NULL GPIO_IRQ_ARG_NC); |
dan_ackme | 29:b6af04b77a56 | 215 | |
dan_ackme | 29:b6af04b77a56 | 216 | |
dan_ackme | 29:b6af04b77a56 | 217 | // ------------------------------------------------------------------------ |
dan_ackme | 29:b6af04b77a56 | 218 | |
dan_ackme | 29:b6af04b77a56 | 219 | /** |
dan_ackme | 29:b6af04b77a56 | 220 | * @ingroup api_socket_udp |
dan_ackme | 29:b6af04b77a56 | 221 | * |
dan_ackme | 29:b6af04b77a56 | 222 | * @brief Connect to remote UDP server. |
dan_ackme | 29:b6af04b77a56 | 223 | * |
dan_ackme | 29:b6af04b77a56 | 224 | * @param[out] socket UDP @ref WiconnectSocket object of opened connection. |
dan_ackme | 29:b6af04b77a56 | 225 | * @param[in] host The host/IP address of the remote UDP server |
dan_ackme | 29:b6af04b77a56 | 226 | * @param[in] remortPort The port of the remote server |
dan_ackme | 29:b6af04b77a56 | 227 | * @param[in] localPort Optional, port of module's side of the connection |
dan_ackme | 29:b6af04b77a56 | 228 | * @param[in] irqPin Optional, Data available external interrupt pin. See registerSocketIrqHandler() for more info |
dan_ackme | 29:b6af04b77a56 | 229 | * @return Result of method. See @ref WiconnectResult |
dan_ackme | 29:b6af04b77a56 | 230 | */ |
dan_ackme | 29:b6af04b77a56 | 231 | WiconnectResult udpConnect(WiconnectSocket &socket, const char *host, uint16_t remortPort, uint16_t localPort = SOCKET_ANY_PORT GPIO_IRQ_ARG_NC); |
dan_ackme | 29:b6af04b77a56 | 232 | |
dan_ackme | 29:b6af04b77a56 | 233 | /** |
dan_ackme | 29:b6af04b77a56 | 234 | * @ingroup api_socket_udp |
dan_ackme | 29:b6af04b77a56 | 235 | * |
dan_ackme | 29:b6af04b77a56 | 236 | * @brief Start a UDP server listening on the given port |
dan_ackme | 29:b6af04b77a56 | 237 | * |
dan_ackme | 29:b6af04b77a56 | 238 | * @param[out] udpServer UDP @ref WiconnectUdpServer object listening server |
dan_ackme | 29:b6af04b77a56 | 239 | * @param[in] listeningPort The port the UDP server listens on |
dan_ackme | 29:b6af04b77a56 | 240 | * @return Result of method. See @ref WiconnectResult |
dan_ackme | 29:b6af04b77a56 | 241 | */ |
dan_ackme | 29:b6af04b77a56 | 242 | WiconnectResult udpListen(WiconnectUdpServer &udpServer, uint16_t listeningPort); |
dan_ackme | 29:b6af04b77a56 | 243 | |
dan_ackme | 29:b6af04b77a56 | 244 | |
dan_ackme | 29:b6af04b77a56 | 245 | // ------------------------------------------------------------------------ |
dan_ackme | 29:b6af04b77a56 | 246 | |
dan_ackme | 29:b6af04b77a56 | 247 | /** |
dan_ackme | 29:b6af04b77a56 | 248 | * @ingroup api_socket_http |
dan_ackme | 29:b6af04b77a56 | 249 | * |
dan_ackme | 29:b6af04b77a56 | 250 | * @brief Connect to remote HTTP server. |
dan_ackme | 29:b6af04b77a56 | 251 | * |
dan_ackme | 29:b6af04b77a56 | 252 | * This is the base method for the other HTTP methods. |
dan_ackme | 29:b6af04b77a56 | 253 | * |
dan_ackme | 29:b6af04b77a56 | 254 | * @section secure_http_connection Secure HTTP |
dan_ackme | 29:b6af04b77a56 | 255 | * Each HTTP method is able to connect to a secure HTTP server. To do this, |
dan_ackme | 29:b6af04b77a56 | 256 | * the URL string parameter must start with 'https://' |
dan_ackme | 29:b6af04b77a56 | 257 | * To connect to a secure HTTP server a TLS certificate is needed. The certificate |
dan_ackme | 29:b6af04b77a56 | 258 | * is specified in the certFilename parameter of the method (or @ref HttpSocketArgs parameter). |
dan_ackme | 29:b6af04b77a56 | 259 | * This is the filename of an existing certificate on the module file system. |
dan_ackme | 29:b6af04b77a56 | 260 | * |
dan_ackme | 29:b6af04b77a56 | 261 | * @note If the URL starts with 'https://' and no certificate filename is specified, |
dan_ackme | 29:b6af04b77a56 | 262 | * the module's default certificate is used. |
dan_ackme | 29:b6af04b77a56 | 263 | * |
dan_ackme | 29:b6af04b77a56 | 264 | * @param[out] socket HTTP @ref WiconnectSocket object of opened connection. |
dan_ackme | 29:b6af04b77a56 | 265 | * @param[in] url URL of HTTP request |
dan_ackme | 29:b6af04b77a56 | 266 | * @param[in] args Configuration @ref HttpSocketArgs for HTTP connection |
dan_ackme | 29:b6af04b77a56 | 267 | * @return Result of method. See @ref WiconnectResult |
dan_ackme | 29:b6af04b77a56 | 268 | */ |
dan_ackme | 29:b6af04b77a56 | 269 | WiconnectResult httpConnect(WiconnectSocket &socket, const char *url, const HttpSocketArgs *args); |
dan_ackme | 29:b6af04b77a56 | 270 | |
dan_ackme | 29:b6af04b77a56 | 271 | /** |
dan_ackme | 29:b6af04b77a56 | 272 | * @ingroup api_socket_http |
dan_ackme | 29:b6af04b77a56 | 273 | * |
dan_ackme | 29:b6af04b77a56 | 274 | * @brief Issue HTTP GET Request |
dan_ackme | 29:b6af04b77a56 | 275 | * |
dan_ackme | 29:b6af04b77a56 | 276 | * This method has the open to only 'open' the connection (disabled by default). This means a connection |
dan_ackme | 29:b6af04b77a56 | 277 | * to the remote HTTP server is opened, but the HTTP request isn't issued. This |
dan_ackme | 29:b6af04b77a56 | 278 | * allow for addition data to be added to the request. For instance, use httpAddHeader() to add |
dan_ackme | 29:b6af04b77a56 | 279 | * additional headers to the request. |
dan_ackme | 29:b6af04b77a56 | 280 | * Use httpGetStatus() to issue the HTTP request and receive the HTTP response. |
dan_ackme | 29:b6af04b77a56 | 281 | * |
dan_ackme | 29:b6af04b77a56 | 282 | * @param[out] socket HTTP @ref WiconnectSocket object of opened connection. |
dan_ackme | 29:b6af04b77a56 | 283 | * @param[in] url URL of HTTP GET request |
dan_ackme | 29:b6af04b77a56 | 284 | * @param[in] openOnly Optional, if TRUE this will only open a connection to the server (it won't issue the request) |
dan_ackme | 29:b6af04b77a56 | 285 | * @param[in] certFilename Optional, filename of existing TLS certificate on module's file system. See @ref secure_http_connection |
dan_ackme | 29:b6af04b77a56 | 286 | * @return Result of method. See @ref WiconnectResult |
dan_ackme | 29:b6af04b77a56 | 287 | */ |
dan_ackme | 29:b6af04b77a56 | 288 | WiconnectResult httpGet(WiconnectSocket &socket, const char *url, bool openOnly = false, const char *certFilename = NULL); |
dan_ackme | 29:b6af04b77a56 | 289 | |
dan_ackme | 29:b6af04b77a56 | 290 | /** |
dan_ackme | 29:b6af04b77a56 | 291 | * @ingroup api_socket_http |
dan_ackme | 29:b6af04b77a56 | 292 | * |
dan_ackme | 29:b6af04b77a56 | 293 | * @brief Issue HTTP POST Request |
dan_ackme | 29:b6af04b77a56 | 294 | * |
dan_ackme | 29:b6af04b77a56 | 295 | * This method has the open to only 'open' the connection which enabled by default. This means a connection |
dan_ackme | 29:b6af04b77a56 | 296 | * to the remote HTTP server is opened, but the HTTP request isn't issued. This |
dan_ackme | 29:b6af04b77a56 | 297 | * allow for addition data to be added to the request. Use the returned @ref WiconnectSocket object's 'write' methods |
dan_ackme | 29:b6af04b77a56 | 298 | * to add POST data to the request. |
dan_ackme | 29:b6af04b77a56 | 299 | * When all POST data has been written, use httpGetStatus() to issue the HTTP request and receive the HTTP response. |
dan_ackme | 29:b6af04b77a56 | 300 | * |
dan_ackme | 29:b6af04b77a56 | 301 | * @param[out] socket HTTP @ref WiconnectSocket object of opened connection. |
dan_ackme | 29:b6af04b77a56 | 302 | * @param[in] url URL of HTTP POST request |
dan_ackme | 29:b6af04b77a56 | 303 | * @param[in] contextType The value to go into the 'content-type' HTTP header (e.g. 'application/json') |
dan_ackme | 29:b6af04b77a56 | 304 | * @param[in] openOnly Optional, if FALSE this will immediately issue the POST request. |
dan_ackme | 29:b6af04b77a56 | 305 | * @param[in] certFilename Optional, filename of existing TLS certificate on module's file system. See @ref secure_http_connection |
dan_ackme | 29:b6af04b77a56 | 306 | * @return Result of method. See @ref WiconnectResult |
dan_ackme | 29:b6af04b77a56 | 307 | */ |
dan_ackme | 29:b6af04b77a56 | 308 | WiconnectResult httpPost(WiconnectSocket &socket, const char *url, const char *contextType, bool openOnly = true, const char *certFilename = NULL); |
dan_ackme | 29:b6af04b77a56 | 309 | |
dan_ackme | 29:b6af04b77a56 | 310 | /** |
dan_ackme | 29:b6af04b77a56 | 311 | * @ingroup api_socket_http |
dan_ackme | 29:b6af04b77a56 | 312 | * |
dan_ackme | 29:b6af04b77a56 | 313 | * @brief Issue HTTP HEAD Request |
dan_ackme | 29:b6af04b77a56 | 314 | * |
dan_ackme | 29:b6af04b77a56 | 315 | * @param[out] socket HTTP @ref WiconnectSocket object of opened connection. |
dan_ackme | 29:b6af04b77a56 | 316 | * @param[in] url URL of HTTP HEAD request |
dan_ackme | 29:b6af04b77a56 | 317 | * @param[in] certFilename Optional, filename of existing TLS certificate on module's file system. See @ref secure_http_connection |
dan_ackme | 29:b6af04b77a56 | 318 | * @return Result of method. See @ref WiconnectResult |
dan_ackme | 29:b6af04b77a56 | 319 | */ |
dan_ackme | 29:b6af04b77a56 | 320 | WiconnectResult httpHead(WiconnectSocket &socket, const char *url, const char *certFilename = NULL); |
dan_ackme | 29:b6af04b77a56 | 321 | |
dan_ackme | 29:b6af04b77a56 | 322 | /** |
dan_ackme | 29:b6af04b77a56 | 323 | * @ingroup api_socket_http |
dan_ackme | 29:b6af04b77a56 | 324 | * |
dan_ackme | 29:b6af04b77a56 | 325 | * @brief Add HTTP header key/value pair to opened HTTP request. |
dan_ackme | 29:b6af04b77a56 | 326 | * |
dan_ackme | 29:b6af04b77a56 | 327 | * To use this function, the supplied @ref WiconnectSocket parameter must have been created |
dan_ackme | 29:b6af04b77a56 | 328 | * using either httpGet() or httpPost() and the 'openOnly' parameter TRUE. |
dan_ackme | 29:b6af04b77a56 | 329 | * |
dan_ackme | 29:b6af04b77a56 | 330 | * This will add additional header to the HTTP request. |
dan_ackme | 29:b6af04b77a56 | 331 | * |
dan_ackme | 29:b6af04b77a56 | 332 | * Use httpGetStatus() to issue the request. |
dan_ackme | 29:b6af04b77a56 | 333 | * |
dan_ackme | 29:b6af04b77a56 | 334 | * @param[in] socket Opened socket to add additonal HTTP header |
dan_ackme | 29:b6af04b77a56 | 335 | * @param[in] key Header key (e.g. 'content-type') |
dan_ackme | 29:b6af04b77a56 | 336 | * @param[in] value Header value (e.g. 'application/json') |
dan_ackme | 29:b6af04b77a56 | 337 | * @return Result of method. See @ref WiconnectResult |
dan_ackme | 29:b6af04b77a56 | 338 | */ |
dan_ackme | 29:b6af04b77a56 | 339 | WiconnectResult httpAddHeader(WiconnectSocket &socket, const char *key, const char *value); |
dan_ackme | 29:b6af04b77a56 | 340 | |
dan_ackme | 29:b6af04b77a56 | 341 | /** |
dan_ackme | 29:b6af04b77a56 | 342 | * @ingroup api_socket_http |
dan_ackme | 29:b6af04b77a56 | 343 | * |
dan_ackme | 29:b6af04b77a56 | 344 | * @brief Get the HTTP status code from HTTP request. |
dan_ackme | 29:b6af04b77a56 | 345 | * |
dan_ackme | 29:b6af04b77a56 | 346 | * This may be used to either issue an HTTP request of an opened HTTP connection |
dan_ackme | 29:b6af04b77a56 | 347 | * or return the status code of a request already issued. |
dan_ackme | 29:b6af04b77a56 | 348 | * |
dan_ackme | 29:b6af04b77a56 | 349 | * @param[in] socket Opened socket to get http response status code |
dan_ackme | 29:b6af04b77a56 | 350 | * @param[out] statusCodePtr Pointer to uint32 to hold http status code |
dan_ackme | 29:b6af04b77a56 | 351 | * @return Result of method. See @ref WiconnectResult |
dan_ackme | 29:b6af04b77a56 | 352 | */ |
dan_ackme | 29:b6af04b77a56 | 353 | WiconnectResult httpGetStatus(WiconnectSocket &socket, uint32_t *statusCodePtr); |
dan_ackme | 29:b6af04b77a56 | 354 | |
dan_ackme | 29:b6af04b77a56 | 355 | protected: |
dan_ackme | 29:b6af04b77a56 | 356 | SocketInterface(Wiconnect *wiconnect); |
dan_ackme | 29:b6af04b77a56 | 357 | ~SocketInterface(); |
dan_ackme | 29:b6af04b77a56 | 358 | |
dan_ackme | 29:b6af04b77a56 | 359 | #ifdef WICONNECT_GPIO_IRQ_ENABLED |
dan_ackme | 29:b6af04b77a56 | 360 | SocketIrqHandlerMap irqHandlers; |
dan_ackme | 29:b6af04b77a56 | 361 | #endif |
dan_ackme | 29:b6af04b77a56 | 362 | |
dan_ackme | 29:b6af04b77a56 | 363 | uint32_t serverConnectedClientList; |
dan_ackme | 29:b6af04b77a56 | 364 | |
dan_ackme | 29:b6af04b77a56 | 365 | WiconnectResult pollForServerClient(uint8_t *handle = NULL, uint16_t *localPort = NULL, uint16_t *remotePort = NULL, uint32_t *ipAddress = NULL); |
dan_ackme | 29:b6af04b77a56 | 366 | |
dan_ackme | 29:b6af04b77a56 | 367 | void socketClosedCallback(const WiconnectSocket *socket); |
dan_ackme | 29:b6af04b77a56 | 368 | |
dan_ackme | 29:b6af04b77a56 | 369 | friend class GhmInterface; |
dan_ackme | 29:b6af04b77a56 | 370 | |
dan_ackme | 29:b6af04b77a56 | 371 | private: |
dan_ackme | 29:b6af04b77a56 | 372 | Wiconnect *wiconnect; |
dan_ackme | 29:b6af04b77a56 | 373 | }; |
dan_ackme | 29:b6af04b77a56 | 374 | |
dan_ackme | 29:b6af04b77a56 | 375 | } |