Diff: WiconnectInterface.h

Revision:

9:b6218dc218ad

Parent:

6:8a87a59d0d21

Child:

11:ea484e1b7fc4

--- a/WiconnectInterface.h	Mon Aug 11 16:30:38 2014 -0700
+++ b/WiconnectInterface.h	Mon Aug 11 21:25:37 2014 -0700
@@ -29,6 +29,7 @@
 
 
 #ifdef WICONNECT_ENABLE_MALLOC
+/// These are optional arguments for host specific malloc/free
 #define WICONNECT_MALLOC_ARGS , void* (*malloc_)(size_t) = WICONNECT_DEFAULT_MALLOC, void (*free_)(void*) = WICONNECT_DEFAULT_FREE
 #else
 #define WICONNECT_MALLOC_ARGS
@@ -38,65 +39,401 @@
 namespace wiconnect {
 
 
+/**
+ *
+ *
+ * The root WiConnect library class. This class
+ * inheriets all WiConnect functionality.
+ *
+ * This class is implemented as a 'singleton'. This means it
+ * only needs to be instantiated once. Subsequent class may either
+ * use the class instance or the static function: @ref Wiconnect::getInstance()
+ *
+ */
 class Wiconnect : public NetworkInterface,
                   public SocketInterface,
                   public FileInterface
 {
 public:
+
+    /**
+     *
+     *
+     * WiConnect class constructor
+     *
+     * @note This should only be called once within a program as the WiConnect
+     *       library is implemented as a singleton.
+     *
+     * @note If this constructor is used, then all commands must be supplied with an external response buffer.
+     *       This means most the API functions will not work as they use the internal buffer.
+     *       It's recommended to use the other constructor that supplies an internal buffer. See @ref setting_alloc
+     *
+     * @param[in] serialConfig The serial (i.e. UART) configuration connected to a WiConnect module.
+     * @param[in] reset Optional, The pin connected to the WiConnect module reset signal. Default: No connection
+     * @param[in] wake Optional, The pin connected to the WiConnect module wake signal. Default: No connection
+     * @param[in] nonBlocking Optional, indicates if the API blocking mode. See @ref setting_blocking_modes
+     */
     Wiconnect(const SerialConfig &serialConfig, Pin reset = PIN_NC, Pin wake = PIN_NC, bool nonBlocking = WICONNECT_DEFAULT_NONBLOCKING WICONNECT_MALLOC_ARGS);
+
+    /**
+     *
+     *
+     * WiConnect class constructor
+     *
+     * @note This should only be called once within a program as the WiConnect
+     *       library is implemented as a singleton.
+     *
+     * @note This is the recommended construstor as it supplies the WiConnect library with an
+     *       internal buffer. Most API calls require the internal buffer.
+     *
+     * @param[in] serialConfig The serial (i.e. UART) configuration connected to a WiConnect module.
+     * @param[in] internalBuffer Optional, a user allocated buffer. See @ref setting_alloc
+     * @param[in] internalBufferSize The size of the internal buffer. If internalBuffer is NULL, then this size will be dynamically allocated. See @ref setting_alloc
+     * @param[in] reset Optional, The pin connected to the WiConnect module reset signal. Default: No connection
+     * @param[in] wake Optional, The pin connected to the WiConnect module wake signal. Default: No connection
+     * @param[in] nonBlocking Optional, indicates if the API blocking mode. See @ref setting_blocking_modes
+     */
     Wiconnect(const SerialConfig &serialConfig, void *internalBuffer, int internalBufferSize, Pin reset = PIN_NC, Pin wake = PIN_NC, bool nonBlocking = WICONNECT_DEFAULT_NONBLOCKING WICONNECT_MALLOC_ARGS);
     ~Wiconnect();
 
+    /**
+     * @ingroup  api_core_misc
+     *
+     * Get instance of previously instantiated Wiconnect Library
+     *
+     * @return Pointer to instance of @ref Wiconnect Library.
+     */
     static Wiconnect* getInstance();
 
+    /**
+     * @ingroup  api_core_misc
+     *
+     * Initialize library and communication link with WiConnect WiFi module.
+     *
+     * @note This function is always blocking regardless of configured mode.
+     *
+     * @param[in] bringNetworkUp Flag indicating if the module should try to bring the network up upon initialization.
+     * @return Result of initialization. See @ref WiconnectResult
+     */
     WiconnectResult init(bool bringNetworkUp);
+
+    /**
+     * @ingroup  api_core_misc
+     *
+     * De-initialize library.
+     */
     void deinit();
+
+    /**
+     * @ingroup api_core_misc
+     *
+     * Return TRUE if library is able to communicated with WiConnect WiFi module.
+     * FALSE else.
+     *
+     * @return TRUE if library can communicate with WiFi module, FALSE else.
+     */
     bool isInitialized();
+
+    /**
+     * @ingroup api_core_misc
+     *
+     * Toggle the WiConnect WiFi module reset signal.
+     *
+     * @note This only resets the module if the library was instantiated with the 'reset' pin
+     *       parameter in the Wiconnect::Wiconnect constructor.
+     * @note This method is always blocking. A small (1s) delay is added to ensure the module
+     *       has returned from reset and ready.
+     *
+     * @return Result of method. See @ref WiconnectResult
+     */
     WiconnectResult reset();
+
+    /**
+     * @ingroup api_core_misc
+     *
+     * Toggle the WiConnect WiFi moduel wakeup signal.
+     *
+     * @note This only wakes the module if the library was instantiated with the 'wake' pin
+     *       parameter in the Wiconnect::Wiconnect constructor.
+     * @note This method is always blocking.
+     *
+     * @return Result of method. See @ref WiconnectResult
+     */
     WiconnectResult wakeup();
+
+    /**
+     * @ingroup api_core_misc
+     *
+     * Flush any received data in serial RX buffer and terminate any commands on WiConnect WiFi module.
+     */
     void flush(int delayMs = 500);
 
+    /**
+     * @ingroup api_core_misc
+     *
+     * Return current version of WiConnect WiFi module.
+     */
     WiconnectResult getVersion(char *versionBuffer = NULL, int versionBufferSize = 0, const Callback &completeCallback = Callback());
 
+    /**
+     * @ingroup api_core_send_command
+     *
+     * @brief Send command to WiConnect WiFi module
+     * Refer to @ref send_command_desc for more info
+     */
     WiconnectResult sendCommand(const Callback &completeCallback, char *responseBuffer, int responseBufferLen,
                                 int timeoutMs, const ReaderFunc &reader, void *user, const char *cmd, va_list vaList);
+    /**
+     * @ingroup api_core_send_command
+     *
+     * @brief Send command to WiConnect WiFi module
+     * Refer to @ref send_command_desc for more info
+     */
     WiconnectResult sendCommand(char *responseBuffer, int responseBufferLen, int timeoutMs, const ReaderFunc &reader,
                                 void *user, const char *cmd, va_list vaList);
+
+    /**
+     * @ingroup api_core_send_command
+     *
+     * @brief Send command to WiConnect WiFi module
+     * Refer to @ref send_command_desc for more info
+     *
+     * @note This method supports variable arguments
+     *
+     */
     WiconnectResult sendCommand(char *responseBuffer, int responseBufferLen, int timeoutMs, const ReaderFunc &reader,
                                 void *user, const char *cmd, ...);
+
+    /**
+     * @ingroup api_core_send_command
+     *
+     * @brief Send command to WiConnect WiFi module
+     * Refer to @ref send_command_desc for more info
+     *
+     * @note This method supports variable arguments
+     *
+     */
     WiconnectResult sendCommand( int timeoutMs, const ReaderFunc &reader, void *user, const char *cmd, ...);
+
+    /**
+     * @ingroup api_core_send_command
+     *
+     * @brief Send command to WiConnect WiFi module
+     * Refer to @ref send_command_desc for more info
+     *
+     * @note This method supports variable arguments
+     *
+     */
     WiconnectResult sendCommand(const ReaderFunc &reader, void *user, const char *cmd, ...);
+
+    /**
+     * @ingroup api_core_send_command
+     *
+     * @brief Send command to WiConnect WiFi module
+     * Refer to @ref send_command_desc for more info
+     *
+     * @note This method supports variable arguments
+     *
+     */
     WiconnectResult sendCommand(char *responseBuffer, int responseBufferLen,  int timeoutMs, const char *cmd, ...);
+
+    /**
+     * @ingroup api_core_send_command
+     *
+     * @brief Send command to WiConnect WiFi module
+     * Refer to @ref send_command_desc for more info
+     *
+     * @note This method supports variable arguments
+     *
+     */
     WiconnectResult sendCommand(const Callback &completeCallback, char *responseBuffer, int responseBufferLen, const char *cmd, ...);
+
+    /**
+     * @ingroup api_core_send_command
+     *
+     * @brief Send command to WiConnect WiFi module
+     * Refer to @ref send_command_desc for more info
+     *
+     * @note This method supports variable arguments
+     *
+     */
     WiconnectResult sendCommand(char *responseBuffer, int responseBufferLen, const char *cmd, ...);
+
+    /**
+     * @ingroup api_core_send_command
+     *
+     * @brief Send command to WiConnect WiFi module
+     * Refer to @ref send_command_desc for more info
+     *
+     * @note This method supports variable arguments
+     *
+     */
     WiconnectResult sendCommand(const Callback &completeCallback, const char *cmd, ...);
+
+    /**
+     * @ingroup api_core_send_command
+     *
+     * @brief Send command to WiConnect WiFi module
+     * Refer to @ref send_command_desc for more info
+     *
+     * @note This method supports variable arguments
+     *
+     */
     WiconnectResult sendCommand(const char *cmd, ...);
+
+    /**
+     * @ingroup api_core_send_command
+     *
+     * @brief Send command to WiConnect WiFi module
+     * Refer to @ref send_command_desc for more info
+     *
+     * @note This method supports variable arguments
+     *
+     */
     WiconnectResult sendCommand(const Callback &completeCallback, int timeoutMs, const char *cmd, ...);
+
+    /**
+     * @ingroup api_core_send_command
+     *
+     * @brief Send command to WiConnect WiFi module
+     * Refer to @ref send_command_desc for more info
+     *
+     * @note This method supports variable arguments
+     *
+     */
     WiconnectResult sendCommand(int timeoutMs, const char *cmd, ...);
+
+    /**
+     * @ingroup api_core_send_command
+     *
+     * @brief Send command to WiConnect WiFi module
+     * Refer to @ref send_command_desc for more info
+     *
+     */
     WiconnectResult sendCommand(const char *cmd, va_list vaList);
 
+    /**
+     * @ingroup api_core_misc
+     *
+     * When the WiConnect WiFi module returns a response, it contains a
+     * response code in the header. This function converts the previous response code
+     * to a readable string.
+     */
     const char* getLastCommandResponseCodeStr();
+
+    /**
+     * @ingroup api_core_misc
+     *
+     * Return the length in bytes of the previous response.
+     */
     uint16_t getLastCommandResponseLength();
+
+    /**
+     * @ingroup api_core_misc
+     *
+     * Return pointer to internal response buffer.
+     */
     char* getResponseBuffer();
+
+    /**
+     * @ingroup api_core_misc
+     *
+     * Helper method to convert previous response to uint32
+     */
     WiconnectResult responseToUint32(uint32_t *uint32Ptr);
+
+    /**
+     * @ingroup api_core_misc
+     *
+     * Helper method to convert previous response to int32
+     */
     WiconnectResult responseToInt32(int32_t *int32Ptr);
 
+    /**
+     * @ingroup api_core_send_command
+     *
+     * Check the status of the currently executing command.
+     *
+     * Refer to @ref WiconnectResult for more information about the return code.
+     *
+     * @note This command is only applicable for non-blocking mode. Refer to @ref setting_blocking_modes.
+     */
     WiconnectResult checkCurrentCommand();
+
+    /**
+     * @ingroup api_core_send_command
+     *
+     * Stop the currently executing command.
+     *
+     * @note This command is only applicable for non-blocking mode. Refer to @ref setting_blocking_modes.
+     */
     void stopCurrentCommand();
+
+    /**
+     * @ingroup api_core_settings
+     *
+     * Sets the default maximum time an API method may execute before
+     * terminating and return a timeout error code.
+     *
+     * @note All API method (execpt some sendCommand()) use this default value.
+     */
     void setCommandDefaultTimeout(int timeoutMs);
+
+    /**
+     * @ingroup api_core_settings
+     *
+     * Returns the current default maximum API execution time.
+     */
     int getCommandDefaultTimeout();
 
+    /**
+     * @ingroup api_core_settings
+     *
+     * Sets a mapping function used to convert from a host Pin to WiConnect WiFi module GPIO.
+     */
     void setPinToGpioMapper(PinToGpioMapper mapper);
 
-    static const char* getWiconnectResultStr(WiconnectResult wiconnectResult);
+    /**
+     * @ingroup api_core_settings
+     *
+     * Sets callback function used to debug WiConnect WiFi module RX/TX serial data.
+     */
     void setDebugLogger(LogFunc logFunc);
+
+    /**
+     * @ingroup api_core_settings
+     *
+     * Sets callback used when Wiconnect Library hits and internal assertion.
+     *
+     * @note This is mainly for debugging. There's nothing the callback can do to fix the assertion.
+     */
     void setAssertLogger(LogFunc assertLogFunc);
 
 #ifdef WICONNECT_ASYNC_TIMER_ENABLED
+    /**
+     * @ingroup api_core_send_command
+     *
+     * Add user command to be executed asynchronously.
+     *
+     */
     WiconnectResult enqueueCommand(QueuedCommand *command, const Callback &commandCompleteHandler = Callback());
+
+    /**
+     * @ingroup api_core_settings
+     *
+     * Set the period at which an asynchronous command should be processed.
+     */
     void setCommandProcessingPeriod(uint32_t periodMs);
 #endif
 
+
+    /**
+     * @ingroup conversion_util
+     *
+     * Converts a @ref WiconnectResult to string representation.
+     */
+    static const char* getWiconnectResultStr(WiconnectResult wiconnectResult);
+
 protected:
 
 #ifdef WICONNECT_ENABLE_MALLOC