Diff: WiconnectInterface.h

Revision:

13:2b51f5267c92

Parent:

11:ea484e1b7fc4

Child:

16:7f1d6d359787

--- a/WiconnectInterface.h	Tue Aug 12 02:44:34 2014 -0700
+++ b/WiconnectInterface.h	Wed Aug 13 03:14:30 2014 -0700
@@ -43,7 +43,7 @@
 
 
 /**
- * @ingroup types_core
+ * @ingroup api_core_types
  *
  * @brief The root WiConnect library class. This class
  * inheriets all WiConnect functionality.
@@ -60,8 +60,6 @@
 public:
 
     /**
-     * @ingroup types_core
-     *
      * @brief WiConnect class constructor
      *
      * @note This should only be called once within a program as the WiConnect
@@ -79,8 +77,6 @@
     Wiconnect(const SerialConfig &serialConfig, Pin reset = PIN_NC, Pin wake = PIN_NC, bool nonBlocking = WICONNECT_DEFAULT_NONBLOCKING WICONNECT_MALLOC_ARGS);
 
     /**
-     * @ingroup types_core
-     *
      * @brief WiConnect class constructor
      *
      * @note This should only be called once within a program as the WiConnect
@@ -90,13 +86,13 @@
      *       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] internalBufferSize The size of the internal buffer. If internalBuffer is NULL, then this size will be dynamically allocated. See @ref setting_alloc
      * @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(const SerialConfig &serialConfig, int internalBufferSize, void *internalBuffer = NULL, Pin reset = PIN_NC, Pin wake = PIN_NC, bool nonBlocking = WICONNECT_DEFAULT_NONBLOCKING WICONNECT_MALLOC_ARGS);
     ~Wiconnect();
 
 
@@ -172,6 +168,12 @@
      * @ingroup api_core_misc
      *
      * @brief Flush any received data in serial RX buffer and terminate any commands on WiConnect WiFi module.
+     *
+     * The delayMs parameter is used as the delay between terminating commands on the module and flushing
+     * the serial RX buffer. This is needed because after terminating commands on the module, the module will
+     * returns a response. These responses are invalid at this point and should be flushed from the serial RX buffer.
+     *
+     * @param[in] delayMs Optional, if not specificed this only flushes the serial RX buffer.
      */
     void flush(int delayMs = 500);
 
@@ -179,6 +181,11 @@
      * @ingroup api_core_misc
      *
      * @brief Return current version of WiConnect WiFi module.
+     * @param[in] versionBuffer Optional, Buffer to hold received version string
+     * @param[in] versionBufferSize Optional, required if versionBuffer specified.
+     * @param[in] completeCallback Optional, callback when version is received. arg1 of callback contains version buffer pointer.
+     *
+     * @return Result of method. See @ref WiconnectResult
      */
     WiconnectResult getVersion(char *versionBuffer = NULL, int versionBufferSize = 0, const Callback &completeCallback = Callback());
 
@@ -190,7 +197,18 @@
      * @ingroup api_core_send_command
      *
      * @brief Send command to WiConnect WiFi module
-     * Refer to @ref send_command_desc for more info
+     *
+     * @note Refer to @ref send_command_desc for more info
+     *
+     * @param[in] completeCallback Callback when command completes. arg1 of callback contains responseBuffer pointer, arg2 contains the response length
+     * @param[in] responseBuffer Buffer to hold command response
+     * @param[in] responseBufferLen Length of responseBuffer
+     * @param[in] timeoutMs Maximum time in milliseconds this command should execute
+     * @param[in] reader Callback for reading data to be read from host and send to module during command
+     * @param[in] user User data struct used during read Callback. Library doesn't use this. Set NULL if not used.
+     * @param[in] cmd WiConnect command to send to module
+     * @param[in] vaList Varaible list of arguments
+     * @return Result of method. See @ref WiconnectResult
      */
     WiconnectResult sendCommand(const Callback &completeCallback, char *responseBuffer, int responseBufferLen,
                                 int timeoutMs, const ReaderFunc &reader, void *user, const char *cmd, va_list vaList);
@@ -198,7 +216,17 @@
      * @ingroup api_core_send_command
      *
      * @brief Send command to WiConnect WiFi module
-     * Refer to @ref send_command_desc for more info
+     *
+     * @note Refer to @ref send_command_desc for more info
+     *
+     * @param[in] responseBuffer Buffer to hold command response
+     * @param[in] responseBufferLen Length of responseBuffer
+     * @param[in] timeoutMs Maximum time in milliseconds this command should execute
+     * @param[in] reader Callback for reading data to be read from host and send to module during command
+     * @param[in] user User data struct used during read Callback. Library doesn't use this. Set NULL if not used.
+     * @param[in] cmd WiConnect command to send to module
+     * @param[in] vaList Varaible list of arguments
+     * @return Result of method. See @ref WiconnectResult
      */
     WiconnectResult sendCommand(char *responseBuffer, int responseBufferLen, int timeoutMs, const ReaderFunc &reader,
                                 void *user, const char *cmd, va_list vaList);
@@ -207,10 +235,17 @@
      * @ingroup api_core_send_command
      *
      * @brief Send command to WiConnect WiFi module
-     * Refer to @ref send_command_desc for more info
      *
+     * @note Refer to @ref send_command_desc for more info
      * @note This method supports variable arguments
      *
+     * @param[in] responseBuffer Buffer to hold command response
+     * @param[in] responseBufferLen Length of responseBuffer
+     * @param[in] timeoutMs Maximum time in milliseconds this command should execute
+     * @param[in] reader Callback for reading data to be read from host and send to module during command
+     * @param[in] user User data struct used during read Callback. Library doesn't use this. Set NULL if not used.
+     * @param[in] cmd WiConnect command to send to module
+     * @return Result of method. See @ref WiconnectResult
      */
     WiconnectResult sendCommand(char *responseBuffer, int responseBufferLen, int timeoutMs, const ReaderFunc &reader,
                                 void *user, const char *cmd, ...);
@@ -219,10 +254,17 @@
      * @ingroup api_core_send_command
      *
      * @brief Send command to WiConnect WiFi module
-     * Refer to @ref send_command_desc for more info
      *
+     * This method uses the library internal buffer.
+     *
+     * @note Refer to @ref send_command_desc for more info
      * @note This method supports variable arguments
      *
+     * @param[in] timeoutMs Maximum time in milliseconds this command should execute
+     * @param[in] reader Callback for reading data to be read from host and send to module during command
+     * @param[in] user User data struct used during read Callback. Library doesn't use this. Set NULL if not used.
+     * @param[in] cmd WiConnect command to send to module
+     * @return Result of method. See @ref WiconnectResult
      */
     WiconnectResult sendCommand( int timeoutMs, const ReaderFunc &reader, void *user, const char *cmd, ...);
 
@@ -230,10 +272,17 @@
      * @ingroup api_core_send_command
      *
      * @brief Send command to WiConnect WiFi module
-     * Refer to @ref send_command_desc for more info
      *
+     * - This method uses the library internal buffer and
+     * - default timeout. See setCommandDefaultTimeout()
+     *
+     * @note Refer to @ref send_command_desc for more info
      * @note This method supports variable arguments
      *
+     * @param[in] reader Callback for reading data to be read from host and send to module during command
+     * @param[in] user User data struct used during read Callback. Library doesn't use this. Set NULL if not used.
+     * @param[in] cmd WiConnect command to send to module
+     * @return Result of method. See @ref WiconnectResult
      */
     WiconnectResult sendCommand(const ReaderFunc &reader, void *user, const char *cmd, ...);
 
@@ -241,10 +290,15 @@
      * @ingroup api_core_send_command
      *
      * @brief Send command to WiConnect WiFi module
-     * Refer to @ref send_command_desc for more info
      *
+     * @note Refer to @ref send_command_desc for more info
      * @note This method supports variable arguments
      *
+     * @param[in] responseBuffer Buffer to hold command response
+     * @param[in] responseBufferLen Length of responseBuffer
+     * @param[in] timeoutMs Maximum time in milliseconds this command should execute
+     * @param[in] cmd WiConnect command to send to module
+     * @return Result of method. See @ref WiconnectResult
      */
     WiconnectResult sendCommand(char *responseBuffer, int responseBufferLen,  int timeoutMs, const char *cmd, ...);
 
@@ -252,10 +306,15 @@
      * @ingroup api_core_send_command
      *
      * @brief Send command to WiConnect WiFi module
-     * Refer to @ref send_command_desc for more info
      *
+     * @note Refer to @ref send_command_desc for more info
      * @note This method supports variable arguments
      *
+     * @param[in] completeCallback Callback when command completes. arg1 of callback contains responseBuffer pointer, arg2 contains the response length
+     * @param[in] responseBuffer Buffer to hold command response
+     * @param[in] responseBufferLen Length of responseBuffer
+     * @param[in] cmd WiConnect command to send to module
+     * @return Result of method. See @ref WiconnectResult
      */
     WiconnectResult sendCommand(const Callback &completeCallback, char *responseBuffer, int responseBufferLen, const char *cmd, ...);
 
@@ -263,10 +322,14 @@
      * @ingroup api_core_send_command
      *
      * @brief Send command to WiConnect WiFi module
-     * Refer to @ref send_command_desc for more info
      *
+     * @note Refer to @ref send_command_desc for more info
      * @note This method supports variable arguments
      *
+     * @param[in] responseBuffer Buffer to hold command response
+     * @param[in] responseBufferLen Length of responseBuffer
+     * @param[in] cmd WiConnect command to send to module
+     * @return Result of method. See @ref WiconnectResult
      */
     WiconnectResult sendCommand(char *responseBuffer, int responseBufferLen, const char *cmd, ...);
 
@@ -274,10 +337,16 @@
      * @ingroup api_core_send_command
      *
      * @brief Send command to WiConnect WiFi module
-     * Refer to @ref send_command_desc for more info
      *
+     * - This method uses the library internal buffer and
+     * - default timeout. See setCommandDefaultTimeout()
+     *
+     * @note Refer to @ref send_command_desc for more info
      * @note This method supports variable arguments
      *
+     * @param[in] completeCallback Callback when command completes. arg1 of callback contains responseBuffer pointer, arg2 contains the response length
+     * @param[in] cmd WiConnect command to send to module
+     * @return Result of method. See @ref WiconnectResult
      */
     WiconnectResult sendCommand(const Callback &completeCallback, const char *cmd, ...);
 
@@ -285,21 +354,30 @@
      * @ingroup api_core_send_command
      *
      * @brief Send command to WiConnect WiFi module
-     * Refer to @ref send_command_desc for more info
      *
+     * - This method uses the library internal buffer and
+     * - default timeout. See setCommandDefaultTimeout()
+     *
+     * @note Refer to @ref send_command_desc for more info
      * @note This method supports variable arguments
      *
+     * @param[in] cmd WiConnect command to send to module
+     * @return Result of method. See @ref WiconnectResult
      */
     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
+     * This method uses the library internal buffer
      *
+     * @note Refer to @ref send_command_desc for more info
      * @note This method supports variable arguments
      *
+     * @param[in] completeCallback Callback when command completes. arg1 of callback contains responseBuffer pointer, arg2 contains the response length
+     * @param[in] timeoutMs Maximum time in milliseconds this command should execute
+     * @param[in] cmd WiConnect command to send to module
+     * @return Result of method. See @ref WiconnectResult
      */
     WiconnectResult sendCommand(const Callback &completeCallback, int timeoutMs, const char *cmd, ...);
 
@@ -307,19 +385,29 @@
      * @ingroup api_core_send_command
      *
      * @brief Send command to WiConnect WiFi module
-     * Refer to @ref send_command_desc for more info
      *
+     * This method uses the library internal buffer
+     *
+     * @note Refer to @ref send_command_desc for more info
      * @note This method supports variable arguments
      *
+     * @param[in] timeoutMs Maximum time in milliseconds this command should execute
+     * @param[in] cmd WiConnect command to send to module
+     * @return Result of method. See @ref WiconnectResult
      */
     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
+     * - This method uses the library internal buffer and
+     * - default timeout. See setCommandDefaultTimeout()
      *
+     * @note Refer to @ref send_command_desc for more info
+     *
+     * @param[in] cmd WiConnect command to send to module
+     * @param[in] vaList Varaible list of arguments
+     * @return Result of method. See @ref WiconnectResult
      */
     WiconnectResult sendCommand(const char *cmd, va_list vaList);
 
@@ -331,6 +419,8 @@
      * 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.
+     *
+     * @return Result of method. See @ref WiconnectResult
      */
     WiconnectResult checkCurrentCommand();
 
@@ -354,6 +444,8 @@
      * @brief 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.
+     *
+     * @return string representation of module response code
      */
     const char* getLastCommandResponseCodeStr();
 
@@ -361,6 +453,8 @@
      * @ingroup api_core_misc
      *
      * @brief Return the length in bytes of the previous response.
+     *
+     * @return length of previous response
      */
     uint16_t getLastCommandResponseLength();
 
@@ -368,6 +462,8 @@
      * @ingroup api_core_misc
      *
      * @brief Return pointer to internal response buffer.
+     *
+     * @return pointer to internal response buffer
      */
     char* getResponseBuffer();
 
@@ -375,6 +471,11 @@
      * @ingroup api_core_misc
      *
      * @brief Helper method to convert previous response to uint32
+     *
+     * @note This uses the internal response buffer.
+     *
+     * @param[out] uint32Ptr Pointer to hold result of conversion.
+     * @return Result of conversion. See @ref WiconnectResult
      */
     WiconnectResult responseToUint32(uint32_t *uint32Ptr);
 
@@ -382,6 +483,11 @@
      * @ingroup api_core_misc
      *
      * @brief Helper method to convert previous response to int32
+     *
+     * @note This uses the internal response buffer.
+     *
+     * @param[out] int32Ptr Pointer to hold result of conversion.
+     * @return Result of conversion. See @ref WiconnectResult
      */
     WiconnectResult responseToInt32(int32_t *int32Ptr);
 
@@ -395,7 +501,9 @@
      * @brief 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.
+     * @note All API methods (execpt some sendCommand()) use this default value.
+     *
+     * @param[in] timeoutMs Default command timeout in milliseconds
      */
     void setCommandDefaultTimeout(int timeoutMs);
 
@@ -403,6 +511,8 @@
      * @ingroup api_core_settings
      *
      * @brief Returns the current default maximum API execution time.
+     *
+     * @return Default command timeout in milliseconds
      */
     int getCommandDefaultTimeout();
 
@@ -410,6 +520,8 @@
      * @ingroup api_core_settings
      *
      * @brief Sets a mapping function used to convert from a host Pin to WiConnect WiFi module GPIO.
+     *
+     * @param[in] mapper Pin to GPIO mapper function pointer
      */
     void setPinToGpioMapper(PinToGpioMapper mapper);
 
@@ -417,6 +529,8 @@
      * @ingroup api_core_settings
      *
      * @brief Sets callback function used to debug WiConnect WiFi module RX/TX serial data.
+     *
+     * @param[in] logFunc Logging function pointer
      */
     void setDebugLogger(LogFunc logFunc);
 
@@ -426,6 +540,8 @@
      * @brief 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.
+     *
+     * @param[in] assertLogFunc Logging function pointer
      */
     void setAssertLogger(LogFunc assertLogFunc);
 
@@ -439,6 +555,11 @@
      *
      * @brief Add user command to be executed asynchronously.
      *
+     * Refer to @ref setting_async_processing for more info.
+     *
+     * @param[in] command Pointer to QueuedCommand to be executed asynchronously
+     * @param[in] commandCompleteHandler Callback to be executed when processing is complete.
+     * @return Result of method. See @ref WiconnectResult
      */
     WiconnectResult enqueueCommand(QueuedCommand *command, const Callback &commandCompleteHandler = Callback());
 
@@ -446,6 +567,10 @@
      * @ingroup api_core_settings
      *
      * @brief Set the period at which an asynchronous command should be processed.
+     *
+     * Refer to @ref setting_async_processing for more info.
+     *
+     * @param[in] periodMs Processing period in milliseconds
      */
     void setCommandProcessingPeriod(uint32_t periodMs);
 #endif
@@ -455,6 +580,9 @@
      * @ingroup conversion_util
      *
      * @brief Converts a @ref WiconnectResult to string representation.
+     *
+     * @param[in] wiconnectResult Result code
+     * @return String representaion of result code
      */
     static const char* getWiconnectResultStr(WiconnectResult wiconnectResult);