Diff: WiconnectTypes.h

Revision:

11:ea484e1b7fc4

Parent:

1:6ec9998427ad

Child:

13:2b51f5267c92

--- a/WiconnectTypes.h	Mon Aug 11 21:59:00 2014 -0700
+++ b/WiconnectTypes.h	Tue Aug 12 02:34:46 2014 -0700
@@ -15,85 +15,203 @@
 
 #include "sdk.h"
 
+/**
+ * @namespace wiconnect
+ *
+ * @brief The entire Wiconnect Library is contained within the 'wiconnect' namespace
+ */
 namespace wiconnect {
 
 
 #ifndef MIN
+/**
+ * @ingroup api_core_macro
+ * @def MIN(x,y)
+ * @brief Computes the minimum of \a x and \a y.
+ */
 #define MIN(x,y) ((x) < (y) ? (x) : (y))
 #endif
 #ifndef MAX
+/**
+ * @ingroup api_core_macro
+ * @def MAX(x,y)
+ * @brief Computes the maximum of \a x and \a y.
+ */
 #define MAX(x,y)  ((x) > (y) ? (x) : (y))
 #endif
+/**
+ * @ingroup api_core_macro
+ * @def ALIGN_n(x, n)
+ * @brief Align \a x to \a n bytes (\a n must be power of 2)
+ */
 #define ALIGN_n(x, n) ((((uint32_t)x) + ((n)-1)) & ~((n)-1))
+/**
+ * @ingroup api_core_macro
+ * @def ALIGN_8(x)
+ * @brief Align \a x to 8 bytes
+ */
 #define ALIGN_8(x) ALIGN_n(x, 8)
+/**
+ * @ingroup api_core_macro
+ * @def ALIGN_4(x)
+ * @brief Align \a x to 4 bytes
+ */
 #define ALIGN_4(x) ALIGN_n(x, 4)
-
-#ifndef OFFSETOF
-#define    OFFSETOF(type, member)    ((uintptr_t)&((type *)0)->member)
-#endif
-
+/**
+ * @ingroup api_core_macro
+ * @def ARRAY_COUNT(x)
+ * @brief Return number of elements in static array \a x
+ */
 #define ARRAY_COUNT(x) (sizeof (x) / sizeof *(x))
 
 
+/**
+ * @ingroup api_core_macro
+ * @def WICONNECT_FAILED(result, func)
+ * @brief Populates \a result with return value from \a func, returns TRUE if return value contains error.
+ */
 #define WICONNECT_FAILED(result, func) ((int)(result = (func)) < (int)wiconnect::WICONNECT_SUCCESS)
+
+/**
+ * @ingroup api_core_macro
+ * @def WICONNECT_SUCCEEDED(result, func)
+ * @brief Populates \a result with return value from \a func, returns TRUE if return value is WICONNECT_SUCCESS.
+ */
 #define WICONNECT_SUCCEEDED(result, func) ((result = (func)) == wiconnect::WICONNECT_SUCCESS)
 
-#define WICONNECT_NULL_RESPONSE_HANDLER WiconnectAsyncCallback()
-
 
+/**
+ * @ingroup api_core_macro
+ * @brief The maximum command size that may be sent to the WiConnect WiFi module
+ */
 #define WICONNECT_MAX_CMD_SIZE 128
+/**
+ * @ingroup api_core_macro
+ * @brief The maximum WiConnect WiFi module version string size
+ */
 #define WICONNECT_MAX_VERSION_SIZE 96
+/**
+ * @ingroup api_core_macro
+ * @brief The maximum number of simulanteous opened sockets
+ */
 #define WICONNECT_MAX_SOCKETS 8
+/**
+ * @ingroup api_core_macro
+ * @brief The maximum server string length
+ */
+#define WICONNECT_MAX_HOST_SIZE 64
+/**
+ * @ingroup api_core_macro
+ * @brief The maximum Wiconnect Module flash filesystem filename length
+ */
+#define WICONNECT_MAX_FILENAME_SIZE 96
 
 
+
+/**
+ * @ingroup api_socket_macro
+ * @brief Default which indicates to use the most optimal port
+ */
+#define SOCKET_ANY_PORT (uint16_t)0
+/**
+ * @ingroup api_socket_macro
+ * @brief Default which indicates to use the most optimal port
+ */
 #define SOCKET_INVALID_HANDLE ((uint8_t)0xFF)
 
 
+/**
+ * @ingroup types_core
+ * @brief API Result code
+ */
 typedef enum
 {
-    WICONNECT_ABORTED               = 3,
-    WICONNECT_IDLE                  = 2,
-    WICONNECT_PROCESSING            = 1,
-    WICONNECT_SUCCESS               = 0,
-    WICONNECT_ERROR                 = -1,
-    WICONNECT_CMD_RESPONSE_ERROR    = -2,
-    WICONNECT_NULL_BUFFER           = -3,
-    WICONNECT_NOT_INITIALIZED       = -4,
-    WICONNECT_OVERFLOW              = -5,
-    WICONNECT_TIMEOUT               = -6,
-    WICONNECT_RESPONSE_HANDLER_NULL = -7,
-    WICONNECT_RESPONSE_PARSE_ERROR  = -8,
-    WICONNECT_ANOTHER_CMD_EXECUTING = -9,
-    WICONNECT_BAD_ARG               = -10,
-    WICONNECT_UNSUPPORTED           = -11,
-    WICONNECT_PINNAME_TO_GPIO_MAPPER_NULL = -12,
-    WICONNECT_DUPLICATE             = -13,
-    WICONNECT_NOT_FOUND             = -14,
-    WICONNECT_PINNAME_TO_GPIO_NO_MAPPING = -15,
-    WICONNECT_NOT_CONNECTED         = -16,
-    WICONNECT_UNDERFLOW             = -17,
-    WICONNECT_MONITOR_NOT_AVAILABLE = -18,
-    WICONNECT_NOT_OPENED_FOR_READING = -19,
+    // Status Codes
+    WICONNECT_ABORTED               = 3,    ///< Command was aborted
+    WICONNECT_IDLE                  = 2,    ///< Library not processing any commands
+    WICONNECT_PROCESSING            = 1,    ///< Library processing current command
+    WICONNECT_SUCCESS               = 0,    ///< Command successfully completed
+
+    // Error codes
+    WICONNECT_ERROR                 = -1,   ///< Generic error
+    WICONNECT_CMD_RESPONSE_ERROR    = -2,   ///< Module returned error code
+    WICONNECT_NULL_BUFFER           = -3,   ///< Null buffer supplied
+    WICONNECT_NOT_INITIALIZED       = -4,   ///< Library not initialed
+    WICONNECT_OVERFLOW              = -5,   ///< Buffer overflowed
+    WICONNECT_TIMEOUT               = -6,   ///< Command timed out
+//    WICONNECT_RESPONSE_HANDLER_NULL = -7,   ///<
+    WICONNECT_RESPONSE_PARSE_ERROR  = -8,   ///< Failed to parse module response
+    WICONNECT_ANOTHER_CMD_EXECUTING = -9,   ///< Currently executing another command
+    WICONNECT_BAD_ARG               = -10,  ///< Bad argument supplied
+    WICONNECT_UNSUPPORTED           = -11,  ///< Command / parameter not supported
+    WICONNECT_PINNAME_TO_GPIO_MAPPER_NULL = -12,    ///< The pinToGpioMapper hasn't been set
+    WICONNECT_DUPLICATE             = -13,  ///< Duplicate value
+    WICONNECT_NOT_FOUND             = -14,  ///< Not found
+    WICONNECT_PINNAME_TO_GPIO_NO_MAPPING = -15, ///< No mapping found for given pin
+    WICONNECT_NOT_CONNECTED         = -16,  ///< Not connected
+    WICONNECT_UNDERFLOW             = -17,  ///< Data underflow
+    WICONNECT_MONITOR_NOT_AVAILABLE = -18,  ///< Background processing monitor is not available (i.e in use)
+    WICONNECT_NOT_OPENED_FOR_READING = -19, ///< The file is not open for reading
 } WiconnectResult;
 
 
+/**
+ * @ingroup types_core
+ * @brief Function pointer for mapping from a host pin to a WiConnect Module GPIO.
+ *
+ * @param[in] pin A host pin
+ * @return The corresponding WiConnect Module GPIO (which the given pin is physically connected).
+ *         Return -1 if no mapping is available.
+ */
+typedef int8_t (*PinToGpioMapper)(Pin pin);
+
+/**
+ * @ingroup types_core
+ * @brief Generic buffer type
+ */
+typedef struct
+{
+    int size;
+    uint8_t *buffer;
+    uint8_t *ptr;
+    int bytesPending;
+    bool allocated;
+} Buffer;
+
+
+// ----------------------------------------------------------------------------
+
+
+
+/**
+ * @ingroup types_network
+ * @brief Network connection status
+ */
 typedef enum
 {
-    NETWORK_STATUS_DOWN,
-    NETWORK_STATUS_WIFI_ONLY,
-    NETWORK_STATUS_UP
+    NETWORK_STATUS_DOWN,            ///< Not connected to network
+    NETWORK_STATUS_WIFI_ONLY,       ///< Connected to network but don't have IP address
+    NETWORK_STATUS_UP               ///< Conntected to network and have IP address
 } NetworkStatus;
 
+/**
+ * @ingroup types_network
+ * @brief Network RSSI signal level
+ */
 typedef enum
 {
-    NETWORK_RSSI_EXCELLENT              = 0,    ///< > -20 dBm
-    NETWORK_RSSI_VERY_GOOD              = 1,    ///< > -35 dBm
-    NETWORK_RSSI_GOOD                   = 2,    ///< > -50 dBm
-    NETWORK_RSSI_POOR                   = 3,    ///< > -70 dBm
+    NETWORK_RSSI_EXCELLENT              = 0,    ///< \> -20 dBm
+    NETWORK_RSSI_VERY_GOOD              = 1,    ///< \> -35 dBm
+    NETWORK_RSSI_GOOD                   = 2,    ///< \> -50 dBm
+    NETWORK_RSSI_POOR                   = 3,    ///< \> -70 dBm
     NETWORK_RSSI_VERY_POOR              = 4,    ///< < -71 dBm
     NETWORK_RSSI_UNKNOWN                = 5     ///< Not available
 } NetworkSignalStrength;
 
+/**
+ * @ingroup types_network
+ * @brief Network security type
+ */
 typedef enum
 {
     NETWORK_SECURITY_OPEN,
@@ -106,101 +224,135 @@
     NETWORK_SECURITY_UNKNOWN
 } NetworkSecurity;
 
+/**
+ * @ingroup types_network
+ * @brief Network SSID type
+ */
 typedef struct
 {
-    uint8_t val[32];
-    uint8_t len;
+    uint8_t val[32];        ///< The raw data of the SSID (not necessarily a string)
+    uint8_t len;            ///< The length in bytes of the SSID raw data
 } Ssid;
 
+/**
+ * @ingroup types_network
+ * @brief Network MAC Address type
+ */
 typedef struct
 {
     uint8_t octet[6];
 } MacAddress;
+
+/**
+ * @ingroup types_network
+ * @brief Buffer to hold a MAC address string
+ */
 typedef char MacAddressStrBuffer[18];
+
+/**
+ * @ingroup types_network
+ * @brief Buffer to hold a SSID string
+ */
 typedef char SsidStrBuffer[129];
+
+/**
+ * @ingroup types_network
+ * @brief Buffer to hold an IP address string
+ */
 typedef char IpStrBuffer[18];
 
 
-typedef enum
-{
-    SOCKET_TYPE_UNKNOWN,
-    SOCKET_TYPE_TCP,
-    SOCKET_TYPE_TLS,
-    SOCKET_TYPE_UDP,
-    SOCKET_TYPE_HTTP,
-} SocketType;
+// ----------------------------------------------------------------------------
+
 
+/**
+ * @ingroup types_socket
+ * @brief Socket type
+ */
 typedef enum
 {
-    SOCKET_HTTP_GET,
-    SOCKET_HTTP_POST,
-    SOCKET_HTTP_HEAD,
-} HttpSocketType;
+    SOCKET_TYPE_UNKNOWN,    ///< Socket type not known
+    SOCKET_TYPE_TCP,        ///< TCP Socket type
+    SOCKET_TYPE_TLS,        ///< TLS Socket type
+    SOCKET_TYPE_UDP,        ///< UDP Socket type
+    SOCKET_TYPE_HTTP,       ///< HTTP Socket type
+} SocketType;
 
-typedef struct
-{
-    const char *contextType;
-    const char *certName;
-    bool openOnly;
-    HttpSocketType type;
-} HttpSocketArgs;
-
-typedef int8_t (*PinToGpioMapper)(Pin pin);
-
-
+/**
+ * @ingroup types_socket
+ * @brief HTTP Socket sub-type
+ */
 typedef enum
 {
-    FILE_FLAG_NONE          = 0,
+    SOCKET_HTTP_GET,        ///< HTTP GET Request socket type
+    SOCKET_HTTP_POST,       ///< HTTP POST Request socket type
+    SOCKET_HTTP_HEAD,       ///< HTTP HEAD Request socket type
+} HttpSocketType;
 
-    FILE_FLAG_VALID         = (1 << 0),
-    FILE_FLAG_EXECUTABLE    = (1 << 1),
-    FILE_FLAG_ENCRYPTED     = (1 << 2),
-    FILE_FLAG_INTERNAL      = (1 << 3),
-    FILE_FLAG_BOOTABLE      = (1 << 4),
-    FILE_FLAG_USER          = (1 << 5),
-    FILE_FLAG_ESSENTIAL     = (1 << 6),
-    FILE_FLAG_BACKUP        = (1 << 7),
+/**
+ * @ingroup types_socket
+ * @brief Struct for hold HTTP socket configuration
+ */
+typedef struct
+{
+    const char *contextType;    ///< A POST Request 'context-type' value
+    const char *certName;       ///< TLS certificate filename on module flash file system
+    bool openOnly;              ///< Only open the connection, don't issue the request yet
+    HttpSocketType type;        ///< The type of HTTP connection
+} HttpSocketArgs;
 
-    FILE_FLAG_FORCE_COPY    = (1 << 15),
+
+// ----------------------------------------------------------------------------
+
 
-    FILE_FLAG_INVALID       = 0xFFFF
-} FileFlags;
-
+/**
+ * @ingroup types_file
+ * @brief File flags type
+ */
 typedef enum
 {
-    FILE_TYPE_UPGRADE_APP   = 0x00,
-    FILE_TYPE_WIFI_FW       = 0x01,
-    FILE_TYPE_SHARED_LIB    = 0x02,
-    FILE_TYPE_TLS_CERT      = 0x03,
-    FILE_TYPE_TXT_LOG       = 0x04,
-    FILE_TYPE_DCT           = 0x05,
+    FILE_FLAG_NONE          = 0,            ///< No flags
 
-    FILE_TYPE_MISC_APP      = 0x80,
-    FILE_TYPE_REGULAR_APP   = 0x81,
+    FILE_FLAG_VALID         = (1 << 0),     ///< File valid
+    FILE_FLAG_EXECUTABLE    = (1 << 1),     ///< File executable
+    FILE_FLAG_ENCRYPTED     = (1 << 2),     ///< File encrypted
+    FILE_FLAG_INTERNAL      = (1 << 3),     ///< File on internal module flash
+    FILE_FLAG_BOOTABLE      = (1 << 4),     ///< File bootable
+    FILE_FLAG_USER          = (1 << 5),     ///< File created by user
+    FILE_FLAG_ESSENTIAL     = (1 << 6),     ///< File is essential
+
+    FILE_FLAG_INVALID       = 0xFFFF        ///< File flags invalid
+} FileFlags;
 
-    FILE_TYPE_USER_RANGE_START = 150,
-    FILE_TYPE_USER_RANGE_END = 199,
+/**
+ * @ingroup types_file
+ * @brief File type type
+ */
+typedef enum
+{
+    FILE_TYPE_UPGRADE_APP   = 0x00,         ///< Internal upgrade application
+    FILE_TYPE_WIFI_FW       = 0x01,         ///< Wifi firmware binary
+
+    FILE_TYPE_REGULAR_APP   = 0x81,         ///< Regular application
 
-    FILE_TYPE_TEMPORY       = 0xF9,
-    FILE_TYPE_GPIO_CONFIG   = 0xFA,
-    FILE_TYPE_COMMAND_HELP  = 0xFB,
-    FILE_TYPE_SDC_CAPS      = 0xFC,
-    FILE_TYPE_SETUP_SCRIPT  = 0xFD,
-    FILE_TYPE_MISC_FIX_LEN  = 0xFE,
-    FILE_TYPE_UNKNOWN       = 0xFF,
+    FILE_TYPE_USER_RANGE_START = 150,       ///< User type start index
+    FILE_TYPE_USER_RANGE_END = 199,         ///< User type end index
+
+    FILE_TYPE_TEMPORY       = 0xF9,         ///< Temporary file
+    FILE_TYPE_GPIO_CONFIG   = 0xFA,         ///< GPIO configuration file
+    FILE_TYPE_COMMAND_HELP  = 0xFB,         ///< WiConnect command help file
+    FILE_TYPE_SDC_CAPS      = 0xFC,         ///< SDC / goHACK.me file
+    FILE_TYPE_SETUP_SCRIPT  = 0xFD,         ///< Setup script file
+    FILE_TYPE_MISC_FIX_LEN  = 0xFE,         ///< Miscellaneous fixed length file
+    FILE_TYPE_UNKNOWN       = 0xFF,         ///< Unknown file type
     FILE_TYPE_ANY           = FILE_TYPE_UNKNOWN
 } FileType;
 
-typedef struct
-{
-    int size;
-    uint8_t *buffer;
-    uint8_t *ptr;
-    int bytesPending;
-    bool allocated;
-} Buffer;
+
 
 
+// Forward declarations
+
 class Wiconnect;
 class TimeoutTimer;
 class PeriodicTimer;