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
Diff: SocketInterface.h
- Revision:
- 13:2b51f5267c92
- Parent:
- 11:ea484e1b7fc4
- Child:
- 16:7f1d6d359787
diff -r 3dfec824715a -r 2b51f5267c92 SocketInterface.h --- a/SocketInterface.h Tue Aug 12 02:44:34 2014 -0700 +++ b/SocketInterface.h Wed Aug 13 03:14:30 2014 -0700 @@ -22,11 +22,13 @@ /** - * @ingroup types_socket + * @ingroup api_socket_types * * @brief The provides an interface for creating TCP/UDP/TLS/HTTP client sockets. * A client socket connects to a remote server. * + * @note This class is an interface to the Wiconnect class. It should never be + * independently instantiated or the parent of another class. */ class SocketInterface { @@ -35,6 +37,12 @@ * @ingroup api_socket_misc * * @brief Close all opened sockets. + * + * @note This closes all open sockets on the MODULE side. + * Socket objects on the HOST side will be still open until + * issuing a read/write command to the module using the socket handle. + * + * @return Result of method. See @ref WiconnectResult */ WiconnectResult closeAllSockets(); @@ -43,6 +51,26 @@ * * @brief Register a host pin as an external interrupt. When the external interrupt is * triggered, the supplied callback is executed. + * + * This should be called before calling one of the connect methods below + * with an irqPin parameter. + * + * Basically how this works is: + * 1. The supplied irqPin is configured as an external interrupt pin. + * 2. A connection is opened and configured with the same irqPin. This + * irqPin physically connected to a GPIO on the WiFi module. + * 3. When the WiFi module has data to send to the HOST it asserts the irqPin. + * 4. The irqPin interrupt executes and calls the supplied handler. + * 5. The handler should notify the HOST that the given irqPin has triggered + * and have the associated socket read data from the module. + * + * @note arg1 of the handler contains the irqPin + * + * + * @param[in] irqPin The HOST pin to configure as an external interrupt. + * This pin should be physically connected to a module GPIO. + * @param[in] handler Callback to be executed with the external irqPin interrupt triggers + * @return Result of method. See @ref WiconnectResult */ WiconnectResult registerSocketIrqHandler(Pin irqPin, const Callback &handler); @@ -50,6 +78,12 @@ * @ingroup api_socket_misc * * @brief Unregister a previously registered IRQ pin. + * + * This disables the given irqPin as an external interrupt. + * Refer to registerSocketIrqHandler() for more information. + * + * @param[in] irqPin The HOST pin to unregister + * @return Result of method. See @ref WiconnectResult */ WiconnectResult unregisterSocketIrqHandler(Pin irqPin); @@ -58,6 +92,17 @@ * @ingroup api_socket_misc * * @brief Connect to remote server. + * + * This is the base method used by all the other connect methods. + * + * @param[out] socket @ref Socket object of opened connection. + * @param[in] type The @ref SocketType of connection to open + * @param[in] host The host/IP address of the remote server + * @param[in] remortPort The port of the remote server + * @param[in] localPort The port of the module's side of the connection + * @param[in] args Depedent on the connection type + * @param[in] irqPin Data available external interrupt pin. See registerSocketIrqHandler() for more info + * @return Result of method. See @ref WiconnectResult */ WiconnectResult connect(Socket &socket, SocketType type, const char *host, uint16_t remortPort, uint16_t localPort, const void *args, Pin irqPin); @@ -68,6 +113,12 @@ * @ingroup api_socket_tcp * * @brief Connect to remote TCP server. + * + * @param[out] socket TCP @ref Socket object of opened connection. + * @param[in] host The host/IP address of the remote TCP server + * @param[in] remortPort The port of the remote server + * @param[in] irqPin Optional, Data available external interrupt pin. See registerSocketIrqHandler() for more info + * @return Result of method. See @ref WiconnectResult */ WiconnectResult tcpConnect(Socket &socket, const char *host, uint16_t remortPort, Pin irqPin = NC); @@ -78,6 +129,13 @@ * @ingroup api_socket_tls * * @brief Connect to remote TLS server. + * + * @param[out] socket TLS @ref Socket object of opened connection. + * @param[in] host The host/IP address of the remote TLS server + * @param[in] remortPort The port of the remote server + * @param[in] certFilename Optional, filename of certificate on module's file system + * @param[in] irqPin Optional, Data available external interrupt pin. See registerSocketIrqHandler() for more info + * @return Result of method. See @ref WiconnectResult */ WiconnectResult tlsConnect(Socket &socket, const char *host, uint16_t remortPort, const char *certFilename = NULL, Pin irqPin = NC); @@ -88,6 +146,13 @@ * @ingroup api_socket_udp * * @brief Connect to remote UDP server. + * + * @param[out] socket UDP @ref Socket object of opened connection. + * @param[in] host The host/IP address of the remote UDP server + * @param[in] remortPort The port of the remote server + * @param[in] localPort Optional, port of module's side of the connection + * @param[in] irqPin Optional, Data available external interrupt pin. See registerSocketIrqHandler() for more info + * @return Result of method. See @ref WiconnectResult */ WiconnectResult udpConnect(Socket &socket, const char *host, uint16_t remortPort, uint16_t localPort = SOCKET_ANY_PORT, Pin irqPin = NC); @@ -98,6 +163,23 @@ * @ingroup api_socket_http * * @brief Connect to remote HTTP server. + * + * This is the base method for the other HTTP methods. + * + * @section secure_http_connection Secure HTTP + * Each HTTP method is able to connect to a secure HTTP server. To do this, + * the URL string parameter must start with 'https://' + * To connect to a secure HTTP server a TLS certificate is needed. The certificate + * is specified in the certFilename parameter of the method (or @ref HttpSocketArgs parameter). + * This is the filename of an existing certificate on the module file system. + * + * @note If the URL starts with 'https://' and no certificate filename is specified, + * the module's default certificate is used. + * + * @param[out] socket HTTP @ref Socket object of opened connection. + * @param[in] url URL of HTTP request + * @param[in] args Configuration @ref HttpSocketArgs for HTTP connection + * @return Result of method. See @ref WiconnectResult */ WiconnectResult httpConnect(Socket &socket, const char *url, const HttpSocketArgs *args); @@ -105,6 +187,18 @@ * @ingroup api_socket_http * * @brief Issue HTTP GET Request + * + * This method has the open to only 'open' the connection (disabled by default). This means a connection + * to the remote HTTP server is opened, but the HTTP request isn't issued. This + * allow for addition data to be added to the request. For instance, use httpAddHeader() to add + * additional headers to the request. + * Use httpGetStatus() to issue the HTTP request and receive the HTTP response. + * + * @param[out] socket HTTP @ref Socket object of opened connection. + * @param[in] url URL of HTTP GET request + * @param[in] openOnly Optional, if TRUE this will only open a connection to the server (it won't issue the request) + * @param[in] certFilename Optional, filename of existing TLS certificate on module's file system. See @ref secure_http_connection + * @return Result of method. See @ref WiconnectResult */ WiconnectResult httpGet(Socket &socket, const char *url, bool openOnly = false, const char *certFilename = NULL); @@ -112,6 +206,19 @@ * @ingroup api_socket_http * * @brief Issue HTTP POST Request + * + * This method has the open to only 'open' the connection which enabled by default. This means a connection + * to the remote HTTP server is opened, but the HTTP request isn't issued. This + * allow for addition data to be added to the request. Use the returned @ref Socket object's 'write' methods + * to add POST data to the request. + * When all POST data has been written, use httpGetStatus() to issue the HTTP request and receive the HTTP response. + * + * @param[out] socket HTTP @ref Socket object of opened connection. + * @param[in] url URL of HTTP POST request + * @param[in] contextType The value to go into the 'content-type' HTTP header (e.g. 'application/json') + * @param[in] openOnly Optional, if FALSE this will immediately issue the POST request. + * @param[in] certFilename Optional, filename of existing TLS certificate on module's file system. See @ref secure_http_connection + * @return Result of method. See @ref WiconnectResult */ WiconnectResult httpPost(Socket &socket, const char *url, const char *contextType, bool openOnly = true, const char *certFilename = NULL); @@ -119,6 +226,11 @@ * @ingroup api_socket_http * * @brief Issue HTTP HEAD Request + * + * @param[out] socket HTTP @ref Socket object of opened connection. + * @param[in] url URL of HTTP HEAD request + * @param[in] certFilename Optional, filename of existing TLS certificate on module's file system. See @ref secure_http_connection + * @return Result of method. See @ref WiconnectResult */ WiconnectResult httpHead(Socket &socket, const char *url, const char *certFilename = NULL); @@ -126,6 +238,18 @@ * @ingroup api_socket_http * * @brief Add HTTP header key/value pair to opened HTTP request. + * + * To use this function, the supplied @ref Socket parameter must have been created + * using either httpGet() or httpPost() and the 'openOnly' parameter TRUE. + * + * This will add additional header to the HTTP request. + * + * Use httpGetStatus() to issue the request. + * + * @param[in] socket Opened socket to add additonal HTTP header + * @param[in] key Header key (e.g. 'content-type') + * @param[in] value Header value (e.g. 'application/json') + * @return Result of method. See @ref WiconnectResult */ WiconnectResult httpAddHeader(Socket &socket, const char *key, const char *value); @@ -133,6 +257,13 @@ * @ingroup api_socket_http * * @brief Get the HTTP status code from HTTP request. + * + * This may be used to either issue an HTTP request of an opened HTTP connection + * or return the status code of a request already issued. + * + * @param[in] socket Opened socket to get http response status code + * @param[out] statusCodePtr Pointer to uint32 to hold http status code + * @return Result of method. See @ref WiconnectResult */ WiconnectResult httpGetStatus(Socket &socket, uint32_t *statusCodePtr);