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

SocketInterface.h@13:2b51f5267c92, 2014-08-13 (annotated)

Committer:
dan_ackme
Date:
Wed Aug 13 03:14:30 2014 -0700
Revision:
13:2b51f5267c92
Parent:
11:ea484e1b7fc4
Child:
16:7f1d6d359787
doc updates

Who changed what in which revision?

UserRevisionLine numberNew contents of line
dan_ackme 0:ea85c4bb5e1f 1 /*
dan_ackme 0:ea85c4bb5e1f 2 * Copyright 2014, ACKme Networks
dan_ackme 0:ea85c4bb5e1f 3 * All Rights Reserved.
dan_ackme 0:ea85c4bb5e1f 4 *
dan_ackme 0:ea85c4bb5e1f 5 * This is UNPUBLISHED PROPRIETARY SOURCE CODE of ACKme Networks;
dan_ackme 0:ea85c4bb5e1f 6 * the contents of this file may not be disclosed to third parties, copied
dan_ackme 0:ea85c4bb5e1f 7 * or duplicated in any form, in whole or in part, without the prior
dan_ackme 0:ea85c4bb5e1f 8 * written permission of ACKme Networks.
dan_ackme 0:ea85c4bb5e1f 9 */
dan_ackme 0:ea85c4bb5e1f 10
dan_ackme 0:ea85c4bb5e1f 11 #pragma once
dan_ackme 0:ea85c4bb5e1f 12
dan_ackme 0:ea85c4bb5e1f 13 #include "Wiconnect.h"
dan_ackme 0:ea85c4bb5e1f 14 #include "types/Socket.h"
dan_ackme 0:ea85c4bb5e1f 15 #include "types/SocketIrqHandlerMap.h"
dan_ackme 0:ea85c4bb5e1f 16
dan_ackme 0:ea85c4bb5e1f 17
dan_ackme 11:ea484e1b7fc4 18 /**
dan_ackme 11:ea484e1b7fc4 19 * @namespace wiconnect
dan_ackme 11:ea484e1b7fc4 20 */
dan_ackme 0:ea85c4bb5e1f 21 namespace wiconnect {
dan_ackme 0:ea85c4bb5e1f 22
dan_ackme 0:ea85c4bb5e1f 23
dan_ackme 11:ea484e1b7fc4 24 /**
dan_ackme 13:2b51f5267c92 25 * @ingroup api_socket_types
dan_ackme 11:ea484e1b7fc4 26 *
dan_ackme 11:ea484e1b7fc4 27 * @brief The provides an interface for creating TCP/UDP/TLS/HTTP client sockets.
dan_ackme 11:ea484e1b7fc4 28 * A client socket connects to a remote server.
dan_ackme 11:ea484e1b7fc4 29 *
dan_ackme 13:2b51f5267c92 30 * @note This class is an interface to the Wiconnect class. It should never be
dan_ackme 13:2b51f5267c92 31 * independently instantiated or the parent of another class.
dan_ackme 11:ea484e1b7fc4 32 */
dan_ackme 0:ea85c4bb5e1f 33 class SocketInterface
dan_ackme 0:ea85c4bb5e1f 34 {
dan_ackme 0:ea85c4bb5e1f 35 public:
dan_ackme 11:ea484e1b7fc4 36 /**
dan_ackme 11:ea484e1b7fc4 37 * @ingroup api_socket_misc
dan_ackme 11:ea484e1b7fc4 38 *
dan_ackme 11:ea484e1b7fc4 39 * @brief Close all opened sockets.
dan_ackme 13:2b51f5267c92 40 *
dan_ackme 13:2b51f5267c92 41 * @note This closes all open sockets on the MODULE side.
dan_ackme 13:2b51f5267c92 42 * Socket objects on the HOST side will be still open until
dan_ackme 13:2b51f5267c92 43 * issuing a read/write command to the module using the socket handle.
dan_ackme 13:2b51f5267c92 44 *
dan_ackme 13:2b51f5267c92 45 * @return Result of method. See @ref WiconnectResult
dan_ackme 11:ea484e1b7fc4 46 */
dan_ackme 0:ea85c4bb5e1f 47 WiconnectResult closeAllSockets();
dan_ackme 11:ea484e1b7fc4 48
dan_ackme 11:ea484e1b7fc4 49 /**
dan_ackme 11:ea484e1b7fc4 50 * @ingroup api_socket_misc
dan_ackme 11:ea484e1b7fc4 51 *
dan_ackme 11:ea484e1b7fc4 52 * @brief Register a host pin as an external interrupt. When the external interrupt is
dan_ackme 11:ea484e1b7fc4 53 * triggered, the supplied callback is executed.
dan_ackme 13:2b51f5267c92 54 *
dan_ackme 13:2b51f5267c92 55 * This should be called before calling one of the connect methods below
dan_ackme 13:2b51f5267c92 56 * with an irqPin parameter.
dan_ackme 13:2b51f5267c92 57 *
dan_ackme 13:2b51f5267c92 58 * Basically how this works is:
dan_ackme 13:2b51f5267c92 59 * 1. The supplied irqPin is configured as an external interrupt pin.
dan_ackme 13:2b51f5267c92 60 * 2. A connection is opened and configured with the same irqPin. This
dan_ackme 13:2b51f5267c92 61 * irqPin physically connected to a GPIO on the WiFi module.
dan_ackme 13:2b51f5267c92 62 * 3. When the WiFi module has data to send to the HOST it asserts the irqPin.
dan_ackme 13:2b51f5267c92 63 * 4. The irqPin interrupt executes and calls the supplied handler.
dan_ackme 13:2b51f5267c92 64 * 5. The handler should notify the HOST that the given irqPin has triggered
dan_ackme 13:2b51f5267c92 65 * and have the associated socket read data from the module.
dan_ackme 13:2b51f5267c92 66 *
dan_ackme 13:2b51f5267c92 67 * @note arg1 of the handler contains the irqPin
dan_ackme 13:2b51f5267c92 68 *
dan_ackme 13:2b51f5267c92 69 *
dan_ackme 13:2b51f5267c92 70 * @param[in] irqPin The HOST pin to configure as an external interrupt.
dan_ackme 13:2b51f5267c92 71 * This pin should be physically connected to a module GPIO.
dan_ackme 13:2b51f5267c92 72 * @param[in] handler Callback to be executed with the external irqPin interrupt triggers
dan_ackme 13:2b51f5267c92 73 * @return Result of method. See @ref WiconnectResult
dan_ackme 11:ea484e1b7fc4 74 */
dan_ackme 0:ea85c4bb5e1f 75 WiconnectResult registerSocketIrqHandler(Pin irqPin, const Callback &handler);
dan_ackme 11:ea484e1b7fc4 76
dan_ackme 11:ea484e1b7fc4 77 /**
dan_ackme 11:ea484e1b7fc4 78 * @ingroup api_socket_misc
dan_ackme 11:ea484e1b7fc4 79 *
dan_ackme 11:ea484e1b7fc4 80 * @brief Unregister a previously registered IRQ pin.
dan_ackme 13:2b51f5267c92 81 *
dan_ackme 13:2b51f5267c92 82 * This disables the given irqPin as an external interrupt.
dan_ackme 13:2b51f5267c92 83 * Refer to registerSocketIrqHandler() for more information.
dan_ackme 13:2b51f5267c92 84 *
dan_ackme 13:2b51f5267c92 85 * @param[in] irqPin The HOST pin to unregister
dan_ackme 13:2b51f5267c92 86 * @return Result of method. See @ref WiconnectResult
dan_ackme 11:ea484e1b7fc4 87 */
dan_ackme 0:ea85c4bb5e1f 88 WiconnectResult unregisterSocketIrqHandler(Pin irqPin);
dan_ackme 0:ea85c4bb5e1f 89
dan_ackme 11:ea484e1b7fc4 90
dan_ackme 11:ea484e1b7fc4 91 /**
dan_ackme 11:ea484e1b7fc4 92 * @ingroup api_socket_misc
dan_ackme 11:ea484e1b7fc4 93 *
dan_ackme 11:ea484e1b7fc4 94 * @brief Connect to remote server.
dan_ackme 13:2b51f5267c92 95 *
dan_ackme 13:2b51f5267c92 96 * This is the base method used by all the other connect methods.
dan_ackme 13:2b51f5267c92 97 *
dan_ackme 13:2b51f5267c92 98 * @param[out] socket @ref Socket object of opened connection.
dan_ackme 13:2b51f5267c92 99 * @param[in] type The @ref SocketType of connection to open
dan_ackme 13:2b51f5267c92 100 * @param[in] host The host/IP address of the remote server
dan_ackme 13:2b51f5267c92 101 * @param[in] remortPort The port of the remote server
dan_ackme 13:2b51f5267c92 102 * @param[in] localPort The port of the module's side of the connection
dan_ackme 13:2b51f5267c92 103 * @param[in] args Depedent on the connection type
dan_ackme 13:2b51f5267c92 104 * @param[in] irqPin Data available external interrupt pin. See registerSocketIrqHandler() for more info
dan_ackme 13:2b51f5267c92 105 * @return Result of method. See @ref WiconnectResult
dan_ackme 11:ea484e1b7fc4 106 */
dan_ackme 0:ea85c4bb5e1f 107 WiconnectResult connect(Socket &socket, SocketType type, const char *host, uint16_t remortPort, uint16_t localPort, const void *args, Pin irqPin);
dan_ackme 11:ea484e1b7fc4 108
dan_ackme 11:ea484e1b7fc4 109
dan_ackme 11:ea484e1b7fc4 110 // ------------------------------------------------------------------------
dan_ackme 11:ea484e1b7fc4 111
dan_ackme 11:ea484e1b7fc4 112 /**
dan_ackme 11:ea484e1b7fc4 113 * @ingroup api_socket_tcp
dan_ackme 11:ea484e1b7fc4 114 *
dan_ackme 11:ea484e1b7fc4 115 * @brief Connect to remote TCP server.
dan_ackme 13:2b51f5267c92 116 *
dan_ackme 13:2b51f5267c92 117 * @param[out] socket TCP @ref Socket object of opened connection.
dan_ackme 13:2b51f5267c92 118 * @param[in] host The host/IP address of the remote TCP server
dan_ackme 13:2b51f5267c92 119 * @param[in] remortPort The port of the remote server
dan_ackme 13:2b51f5267c92 120 * @param[in] irqPin Optional, Data available external interrupt pin. See registerSocketIrqHandler() for more info
dan_ackme 13:2b51f5267c92 121 * @return Result of method. See @ref WiconnectResult
dan_ackme 11:ea484e1b7fc4 122 */
dan_ackme 0:ea85c4bb5e1f 123 WiconnectResult tcpConnect(Socket &socket, const char *host, uint16_t remortPort, Pin irqPin = NC);
dan_ackme 11:ea484e1b7fc4 124
dan_ackme 11:ea484e1b7fc4 125
dan_ackme 11:ea484e1b7fc4 126 // ------------------------------------------------------------------------
dan_ackme 11:ea484e1b7fc4 127
dan_ackme 11:ea484e1b7fc4 128 /**
dan_ackme 11:ea484e1b7fc4 129 * @ingroup api_socket_tls
dan_ackme 11:ea484e1b7fc4 130 *
dan_ackme 11:ea484e1b7fc4 131 * @brief Connect to remote TLS server.
dan_ackme 13:2b51f5267c92 132 *
dan_ackme 13:2b51f5267c92 133 * @param[out] socket TLS @ref Socket object of opened connection.
dan_ackme 13:2b51f5267c92 134 * @param[in] host The host/IP address of the remote TLS server
dan_ackme 13:2b51f5267c92 135 * @param[in] remortPort The port of the remote server
dan_ackme 13:2b51f5267c92 136 * @param[in] certFilename Optional, filename of certificate on module's file system
dan_ackme 13:2b51f5267c92 137 * @param[in] irqPin Optional, Data available external interrupt pin. See registerSocketIrqHandler() for more info
dan_ackme 13:2b51f5267c92 138 * @return Result of method. See @ref WiconnectResult
dan_ackme 11:ea484e1b7fc4 139 */
dan_ackme 0:ea85c4bb5e1f 140 WiconnectResult tlsConnect(Socket &socket, const char *host, uint16_t remortPort, const char *certFilename = NULL, Pin irqPin = NC);
dan_ackme 11:ea484e1b7fc4 141
dan_ackme 11:ea484e1b7fc4 142
dan_ackme 11:ea484e1b7fc4 143 // ------------------------------------------------------------------------
dan_ackme 11:ea484e1b7fc4 144
dan_ackme 11:ea484e1b7fc4 145 /**
dan_ackme 11:ea484e1b7fc4 146 * @ingroup api_socket_udp
dan_ackme 11:ea484e1b7fc4 147 *
dan_ackme 11:ea484e1b7fc4 148 * @brief Connect to remote UDP server.
dan_ackme 13:2b51f5267c92 149 *
dan_ackme 13:2b51f5267c92 150 * @param[out] socket UDP @ref Socket object of opened connection.
dan_ackme 13:2b51f5267c92 151 * @param[in] host The host/IP address of the remote UDP server
dan_ackme 13:2b51f5267c92 152 * @param[in] remortPort The port of the remote server
dan_ackme 13:2b51f5267c92 153 * @param[in] localPort Optional, port of module's side of the connection
dan_ackme 13:2b51f5267c92 154 * @param[in] irqPin Optional, Data available external interrupt pin. See registerSocketIrqHandler() for more info
dan_ackme 13:2b51f5267c92 155 * @return Result of method. See @ref WiconnectResult
dan_ackme 11:ea484e1b7fc4 156 */
dan_ackme 0:ea85c4bb5e1f 157 WiconnectResult udpConnect(Socket &socket, const char *host, uint16_t remortPort, uint16_t localPort = SOCKET_ANY_PORT, Pin irqPin = NC);
dan_ackme 11:ea484e1b7fc4 158
dan_ackme 11:ea484e1b7fc4 159
dan_ackme 11:ea484e1b7fc4 160 // ------------------------------------------------------------------------
dan_ackme 11:ea484e1b7fc4 161
dan_ackme 11:ea484e1b7fc4 162 /**
dan_ackme 11:ea484e1b7fc4 163 * @ingroup api_socket_http
dan_ackme 11:ea484e1b7fc4 164 *
dan_ackme 11:ea484e1b7fc4 165 * @brief Connect to remote HTTP server.
dan_ackme 13:2b51f5267c92 166 *
dan_ackme 13:2b51f5267c92 167 * This is the base method for the other HTTP methods.
dan_ackme 13:2b51f5267c92 168 *
dan_ackme 13:2b51f5267c92 169 * @section secure_http_connection Secure HTTP
dan_ackme 13:2b51f5267c92 170 * Each HTTP method is able to connect to a secure HTTP server. To do this,
dan_ackme 13:2b51f5267c92 171 * the URL string parameter must start with 'https://'
dan_ackme 13:2b51f5267c92 172 * To connect to a secure HTTP server a TLS certificate is needed. The certificate
dan_ackme 13:2b51f5267c92 173 * is specified in the certFilename parameter of the method (or @ref HttpSocketArgs parameter).
dan_ackme 13:2b51f5267c92 174 * This is the filename of an existing certificate on the module file system.
dan_ackme 13:2b51f5267c92 175 *
dan_ackme 13:2b51f5267c92 176 * @note If the URL starts with 'https://' and no certificate filename is specified,
dan_ackme 13:2b51f5267c92 177 * the module's default certificate is used.
dan_ackme 13:2b51f5267c92 178 *
dan_ackme 13:2b51f5267c92 179 * @param[out] socket HTTP @ref Socket object of opened connection.
dan_ackme 13:2b51f5267c92 180 * @param[in] url URL of HTTP request
dan_ackme 13:2b51f5267c92 181 * @param[in] args Configuration @ref HttpSocketArgs for HTTP connection
dan_ackme 13:2b51f5267c92 182 * @return Result of method. See @ref WiconnectResult
dan_ackme 11:ea484e1b7fc4 183 */
dan_ackme 0:ea85c4bb5e1f 184 WiconnectResult httpConnect(Socket &socket, const char *url, const HttpSocketArgs *args);
dan_ackme 11:ea484e1b7fc4 185
dan_ackme 11:ea484e1b7fc4 186 /**
dan_ackme 11:ea484e1b7fc4 187 * @ingroup api_socket_http
dan_ackme 11:ea484e1b7fc4 188 *
dan_ackme 11:ea484e1b7fc4 189 * @brief Issue HTTP GET Request
dan_ackme 13:2b51f5267c92 190 *
dan_ackme 13:2b51f5267c92 191 * This method has the open to only 'open' the connection (disabled by default). This means a connection
dan_ackme 13:2b51f5267c92 192 * to the remote HTTP server is opened, but the HTTP request isn't issued. This
dan_ackme 13:2b51f5267c92 193 * allow for addition data to be added to the request. For instance, use httpAddHeader() to add
dan_ackme 13:2b51f5267c92 194 * additional headers to the request.
dan_ackme 13:2b51f5267c92 195 * Use httpGetStatus() to issue the HTTP request and receive the HTTP response.
dan_ackme 13:2b51f5267c92 196 *
dan_ackme 13:2b51f5267c92 197 * @param[out] socket HTTP @ref Socket object of opened connection.
dan_ackme 13:2b51f5267c92 198 * @param[in] url URL of HTTP GET request
dan_ackme 13:2b51f5267c92 199 * @param[in] openOnly Optional, if TRUE this will only open a connection to the server (it won't issue the request)
dan_ackme 13:2b51f5267c92 200 * @param[in] certFilename Optional, filename of existing TLS certificate on module's file system. See @ref secure_http_connection
dan_ackme 13:2b51f5267c92 201 * @return Result of method. See @ref WiconnectResult
dan_ackme 11:ea484e1b7fc4 202 */
dan_ackme 0:ea85c4bb5e1f 203 WiconnectResult httpGet(Socket &socket, const char *url, bool openOnly = false, const char *certFilename = NULL);
dan_ackme 11:ea484e1b7fc4 204
dan_ackme 11:ea484e1b7fc4 205 /**
dan_ackme 11:ea484e1b7fc4 206 * @ingroup api_socket_http
dan_ackme 11:ea484e1b7fc4 207 *
dan_ackme 11:ea484e1b7fc4 208 * @brief Issue HTTP POST Request
dan_ackme 13:2b51f5267c92 209 *
dan_ackme 13:2b51f5267c92 210 * This method has the open to only 'open' the connection which enabled by default. This means a connection
dan_ackme 13:2b51f5267c92 211 * to the remote HTTP server is opened, but the HTTP request isn't issued. This
dan_ackme 13:2b51f5267c92 212 * allow for addition data to be added to the request. Use the returned @ref Socket object's 'write' methods
dan_ackme 13:2b51f5267c92 213 * to add POST data to the request.
dan_ackme 13:2b51f5267c92 214 * When all POST data has been written, use httpGetStatus() to issue the HTTP request and receive the HTTP response.
dan_ackme 13:2b51f5267c92 215 *
dan_ackme 13:2b51f5267c92 216 * @param[out] socket HTTP @ref Socket object of opened connection.
dan_ackme 13:2b51f5267c92 217 * @param[in] url URL of HTTP POST request
dan_ackme 13:2b51f5267c92 218 * @param[in] contextType The value to go into the 'content-type' HTTP header (e.g. 'application/json')
dan_ackme 13:2b51f5267c92 219 * @param[in] openOnly Optional, if FALSE this will immediately issue the POST request.
dan_ackme 13:2b51f5267c92 220 * @param[in] certFilename Optional, filename of existing TLS certificate on module's file system. See @ref secure_http_connection
dan_ackme 13:2b51f5267c92 221 * @return Result of method. See @ref WiconnectResult
dan_ackme 11:ea484e1b7fc4 222 */
dan_ackme 0:ea85c4bb5e1f 223 WiconnectResult httpPost(Socket &socket, const char *url, const char *contextType, bool openOnly = true, const char *certFilename = NULL);
dan_ackme 11:ea484e1b7fc4 224
dan_ackme 11:ea484e1b7fc4 225 /**
dan_ackme 11:ea484e1b7fc4 226 * @ingroup api_socket_http
dan_ackme 11:ea484e1b7fc4 227 *
dan_ackme 11:ea484e1b7fc4 228 * @brief Issue HTTP HEAD Request
dan_ackme 13:2b51f5267c92 229 *
dan_ackme 13:2b51f5267c92 230 * @param[out] socket HTTP @ref Socket object of opened connection.
dan_ackme 13:2b51f5267c92 231 * @param[in] url URL of HTTP HEAD request
dan_ackme 13:2b51f5267c92 232 * @param[in] certFilename Optional, filename of existing TLS certificate on module's file system. See @ref secure_http_connection
dan_ackme 13:2b51f5267c92 233 * @return Result of method. See @ref WiconnectResult
dan_ackme 11:ea484e1b7fc4 234 */
dan_ackme 0:ea85c4bb5e1f 235 WiconnectResult httpHead(Socket &socket, const char *url, const char *certFilename = NULL);
dan_ackme 11:ea484e1b7fc4 236
dan_ackme 11:ea484e1b7fc4 237 /**
dan_ackme 11:ea484e1b7fc4 238 * @ingroup api_socket_http
dan_ackme 11:ea484e1b7fc4 239 *
dan_ackme 11:ea484e1b7fc4 240 * @brief Add HTTP header key/value pair to opened HTTP request.
dan_ackme 13:2b51f5267c92 241 *
dan_ackme 13:2b51f5267c92 242 * To use this function, the supplied @ref Socket parameter must have been created
dan_ackme 13:2b51f5267c92 243 * using either httpGet() or httpPost() and the 'openOnly' parameter TRUE.
dan_ackme 13:2b51f5267c92 244 *
dan_ackme 13:2b51f5267c92 245 * This will add additional header to the HTTP request.
dan_ackme 13:2b51f5267c92 246 *
dan_ackme 13:2b51f5267c92 247 * Use httpGetStatus() to issue the request.
dan_ackme 13:2b51f5267c92 248 *
dan_ackme 13:2b51f5267c92 249 * @param[in] socket Opened socket to add additonal HTTP header
dan_ackme 13:2b51f5267c92 250 * @param[in] key Header key (e.g. 'content-type')
dan_ackme 13:2b51f5267c92 251 * @param[in] value Header value (e.g. 'application/json')
dan_ackme 13:2b51f5267c92 252 * @return Result of method. See @ref WiconnectResult
dan_ackme 11:ea484e1b7fc4 253 */
dan_ackme 0:ea85c4bb5e1f 254 WiconnectResult httpAddHeader(Socket &socket, const char *key, const char *value);
dan_ackme 11:ea484e1b7fc4 255
dan_ackme 11:ea484e1b7fc4 256 /**
dan_ackme 11:ea484e1b7fc4 257 * @ingroup api_socket_http
dan_ackme 11:ea484e1b7fc4 258 *
dan_ackme 11:ea484e1b7fc4 259 * @brief Get the HTTP status code from HTTP request.
dan_ackme 13:2b51f5267c92 260 *
dan_ackme 13:2b51f5267c92 261 * This may be used to either issue an HTTP request of an opened HTTP connection
dan_ackme 13:2b51f5267c92 262 * or return the status code of a request already issued.
dan_ackme 13:2b51f5267c92 263 *
dan_ackme 13:2b51f5267c92 264 * @param[in] socket Opened socket to get http response status code
dan_ackme 13:2b51f5267c92 265 * @param[out] statusCodePtr Pointer to uint32 to hold http status code
dan_ackme 13:2b51f5267c92 266 * @return Result of method. See @ref WiconnectResult
dan_ackme 11:ea484e1b7fc4 267 */
dan_ackme 0:ea85c4bb5e1f 268 WiconnectResult httpGetStatus(Socket &socket, uint32_t *statusCodePtr);
dan_ackme 0:ea85c4bb5e1f 269
dan_ackme 0:ea85c4bb5e1f 270 protected:
dan_ackme 1:6ec9998427ad 271 SocketInterface(Wiconnect *wiconnect);
dan_ackme 1:6ec9998427ad 272
dan_ackme 0:ea85c4bb5e1f 273 SocketIrqHandlerMap irqHandlers;
dan_ackme 0:ea85c4bb5e1f 274
dan_ackme 0:ea85c4bb5e1f 275 private:
dan_ackme 0:ea85c4bb5e1f 276 Wiconnect *wiconnect;
dan_ackme 0:ea85c4bb5e1f 277 };
dan_ackme 0:ea85c4bb5e1f 278
dan_ackme 0:ea85c4bb5e1f 279 }