Diff: SocketInterface.h

Revision:

11:ea484e1b7fc4

Parent:

1:6ec9998427ad

Child:

13:2b51f5267c92

--- a/SocketInterface.h	Mon Aug 11 21:59:00 2014 -0700
+++ b/SocketInterface.h	Tue Aug 12 02:34:46 2014 -0700
@@ -15,29 +15,125 @@
 #include "types/SocketIrqHandlerMap.h"
 
 
+/**
+ * @namespace wiconnect
+ */
 namespace wiconnect {
 
 
-#define SOCKET_ANY_PORT (uint16_t)0
-
-
-
+/**
+ * @ingroup types_socket
+ *
+ * @brief The provides an interface for creating TCP/UDP/TLS/HTTP client sockets.
+ * A client socket connects to a remote server.
+ *
+ */
 class SocketInterface
 {
 public:
+    /**
+     * @ingroup api_socket_misc
+     *
+     * @brief Close all opened sockets.
+     */
     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.
+     */
     WiconnectResult registerSocketIrqHandler(Pin irqPin, const Callback &handler);
+
+    /**
+     * @ingroup api_socket_misc
+     *
+     * @brief Unregister a previously registered IRQ pin.
+     */
     WiconnectResult unregisterSocketIrqHandler(Pin irqPin);
 
+
+    /**
+     * @ingroup api_socket_misc
+     *
+     * @brief Connect to remote server.
+     */
     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.
+     */
     WiconnectResult tcpConnect(Socket &socket, const char *host, uint16_t remortPort, Pin irqPin = NC);
+
+
+    // ------------------------------------------------------------------------
+
+    /**
+     * @ingroup api_socket_tls
+     *
+     * @brief Connect to remote TLS server.
+     */
     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.
+     */
     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.
+     */
     WiconnectResult httpConnect(Socket &socket, const char *url, const HttpSocketArgs *args);
+
+    /**
+     * @ingroup api_socket_http
+     *
+     * @brief Issue HTTP GET Request
+     */
     WiconnectResult httpGet(Socket &socket, const char *url, bool openOnly = false, const char *certFilename = NULL);
+
+    /**
+     * @ingroup api_socket_http
+     *
+     * @brief Issue HTTP POST Request
+     */
     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
+     */
     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.
+     */
     WiconnectResult httpAddHeader(Socket &socket, const char *key, const char *value);
+
+    /**
+     * @ingroup api_socket_http
+     *
+     * @brief Get the HTTP status code from HTTP request.
+     */
     WiconnectResult httpGetStatus(Socket &socket, uint32_t *statusCodePtr);
 
 protected: