File content as of revision 13:2b51f5267c92:

/*
 * Copyright 2014, ACKme Networks
 * All Rights Reserved.
 *
 * This is UNPUBLISHED PROPRIETARY SOURCE CODE of ACKme Networks;
 * the contents of this file may not be disclosed to third parties, copied
 * or duplicated in any form, in whole or in part, without the prior
 * written permission of ACKme Networks.
 */

#pragma once

#include "Wiconnect.h"
#include "types/Socket.h"
#include "types/SocketIrqHandlerMap.h"


/**
 * @namespace wiconnect
 */
namespace wiconnect {


/**
 * @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
{
public:
    /**
     * @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();

    /**
     * @ingroup api_socket_misc
     *
     * @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);

    /**
     * @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);


    /**
     * @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);


    // ------------------------------------------------------------------------

    /**
     * @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);


    // ------------------------------------------------------------------------

    /**
     * @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);


    // ------------------------------------------------------------------------

    /**
     * @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);


    // ------------------------------------------------------------------------

    /**
     * @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);

    /**
     * @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);

    /**
     * @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);

    /**
     * @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);

    /**
     * @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);

    /**
     * @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);

protected:
    SocketInterface(Wiconnect *wiconnect);

    SocketIrqHandlerMap irqHandlers;

private:
    Wiconnect *wiconnect;
};

}