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: api/WiconnectTypes.h
- Revision:
- 29:b6af04b77a56
- Child:
- 34:2616445d0823
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/api/WiconnectTypes.h Mon Oct 27 13:42:26 2014 -0700 @@ -0,0 +1,507 @@ +/** + * ACKme WiConnect Host Library is licensed under the BSD licence: + * + * Copyright (c)2014 ACKme Networks. + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without modification, + * are permitted provided that the following conditions are met: + * + * 1. Redistributions of source code must retain the above copyright notice, + * this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright notice, + * this list of conditions and the following disclaimer in the documentation + * and/or other materials provided with the distribution. + * 3. The name of the author may not be used to endorse or promote products + * derived from this software without specific prior written permission. + * + * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS AND ANY EXPRESS OR IMPLIED + * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF + * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT + * SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, + * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT + * OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING + * IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY + * OF SUCH DAMAGE. + */ +#pragma once + +#include <stdint.h> +#include <stdarg.h> +#include <stddef.h> + +#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) +/** + * @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) + +/** + * @ingroup api_core_macro + * @def WICONNECT_IS_PROCESSING(result, func) + * @brief Populates \a result with return value from \a func, returns TRUE if return value is WICONNECT_PROCESSING. + */ +#define WICONNECT_IS_PROCESSING(result, func) ((result = (func)) == wiconnect::WICONNECT_PROCESSING) + +/** + * @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_core_macro + * @brief Never timeout + */ +#define WICONNECT_WAIT_FOREVER 0xFFFFFFFFUL +/** + * @ingroup api_core_macro + * @brief Timeout immediately + */ +#define WICONNECT_NO_WAIT 0 +/** + * @ingroup api_core_macro + * @brief Default firmware update timeout in ms + */ +#define WICONNECT_FIRMWARE_UPDATE_TIMEOUT 90000UL + +/** + * @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 api_core_types + * @brief API Result code + */ +typedef enum +{ + // 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 Timeout type + */ +typedef unsigned long TimerTimeout; + + +/** + * @brief Generic buffer type + * + * @note Internal use only + */ +typedef struct +{ + int size; + uint8_t *buffer; + uint8_t *ptr; + int bytesPending; + bool allocated; +} Buffer; + + +// ---------------------------------------------------------------------------- + + + +/** + * @ingroup api_network_types + * @brief Network connection status + */ +typedef enum +{ + 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 + NETWORK_STATUS_JOINING ///< Joining a network +} NetworkStatus; + +/** + * @ingroup api_network_types + * @brief Network connection status + */ +typedef enum +{ + NETWORK_JOIN_RESULT_NONE, ///< Haven't attempted to join + NETWORK_JOIN_RESULT_SUCCESS, ///< Successfully joined the network + NETWORK_JOIN_RESULT_JOINING, ///< Currently attempting to join + NETWORK_JOIN_RESULT_NO_SSID, ///< The SSID has not be configured + NETWORK_JOIN_RESULT_NO_PASSWORD, ///< The network requires a password and none has been set + NETWORK_JOIN_RESULT_BAD_SECURITY, ///< The specified security type is not supported by the network + NETWORK_JOIN_RESULT_NOT_FOUND, ///< The network with the configured SSID was not found + NETWORK_JOIN_RESULT_FAILED, ///< Failed to join the network + NETWORK_JOIN_RESULT_ABORTED, ///< Joining was aborted (via command) +} NetworkJoinResult; + +/** + * @ingroup api_network_types + * @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_VERY_POOR = 4, ///< < -71 dBm + NETWORK_RSSI_UNKNOWN = 5 ///< Not available +} NetworkSignalStrength; + +/** + * @ingroup api_network_types + * @brief Network security type + */ +typedef enum +{ + NETWORK_SECURITY_OPEN, + NETWORK_SECURITY_WEP_PSK, + NETWORK_SECURITY_WPA_AES_PSK, + NETWORK_SECURITY_WPA_TKIP_PSK, + NETWORK_SECURITY_WPA2_AES_PSK, + NETWORK_SECURITY_WPA2_MIXED_PSK, + NETWORK_SECURITY_WPA2_TKIP_PSK, + NETWORK_SECURITY_UNKNOWN +} NetworkSecurity; + +/** + * @ingroup api_network_types + * @brief Network SSID type + */ +typedef struct +{ + 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 api_network_types + * @brief Network MAC Address type + */ +typedef struct +{ + uint8_t octet[6]; +} MacAddress; + +/** + * @ingroup api_network_types + * @brief Buffer to hold a MAC address string + */ +typedef char MacAddressStrBuffer[18]; + +/** + * @ingroup api_network_types + * @brief Buffer to hold a SSID string + */ +typedef char SsidStrBuffer[129]; + +/** + * @ingroup api_network_types + * @brief Buffer to hold an IP address string + */ +typedef char IpStrBuffer[18]; + + +// ---------------------------------------------------------------------------- + + +/** + * @ingroup api_socket_types + * @brief Socket type + */ +typedef enum +{ + 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, + SOCKET_TYPE_UDPS, ///< UDP Server Socket type + SOCKET_TYPE_GHM, ///< goHACK.me message type +} SocketType; + +/** + * @ingroup api_socket_types + * @brief HTTP Socket sub-type + */ +typedef enum +{ + 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; + +/** + * @ingroup api_socket_types + * @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; + + +// ---------------------------------------------------------------------------- + + +/** + * @ingroup api_file_types + * @brief File flags type + */ +typedef enum +{ + FILE_FLAG_NONE = 0, ///< No flags + + 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; + +/** + * @ingroup api_file_types + * @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_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; + + +// ---------------------------------------------------------------------------- + +/** + * @ingroup api_ghm_types + * @brief goHACK.me stream or control value type + */ +typedef enum +{ + GHM_VALUE_INT, + GHM_VALUE_STR +} GhmElementValueType; + +/** + * @ingroup api_ghm_types + * @brief goHACK.me stream or control value + */ +typedef struct +{ + const char *elementName; + GhmElementValueType type; + union + { + const char *strValue; + uint32_t intValue; + } u; +} GhmElement; + +/** + * @ingroup api_ghm_types + * @brief Array of goHACK.me stream or control values + */ +typedef struct +{ + uint16_t count; + GhmElement elements[1]; +} GhmElementArray; + +/** + * @ingroup api_ghm_types + * @brief goHACK.me sychronization type + */ +typedef enum +{ + GHM_SYNC_ALL, ///< Push and pull all streams and controls + GHM_SYNC_PUSH_ONLY, ///< Only push streams and controls to remote server + GHM_SYNC_PULL_ONLY ///< Only pull controls from remote server +} GhmSyncType; + +/** + * @ingroup api_ghm_types + * @brief goHACK.me message GET type + */ +typedef enum +{ + GHM_MSG_GET_DATA_ONLY, ///< Only GET the message data + GHM_MSG_GET_BODY, ///< Get the message body. This is JSON formatted. + GHM_MSG_GET_ALL ///< Get entire message. This includes headers. Is JSON formatted. +} GhmMessageGetType; + + + +// ---------------------------------------------------------------------------- + + +// Forward declarations + +class Wiconnect; +class TimeoutTimer; +class PeriodicTimer; +class QueuedCommand; +class CommandQueue; +class LogFunc; +class ReaderFunc; +class ReaderFuncCallback; +class Callback; +class ScanResult; +class ScanResultList; +class WiconnectSocket; +class WiconnectSerial; +class WiconnectFile; +class FileList; +class Gpio; +class SocketIrqHandlerMap; +class WiconnectUdpServer; +class GhmMessageList; +class GhmMessage; + +}