Diff: NetworkInterface.h

Revision:

13:2b51f5267c92

Parent:

11:ea484e1b7fc4

Child:

16:7f1d6d359787

--- a/NetworkInterface.h	Tue Aug 12 02:44:34 2014 -0700
+++ b/NetworkInterface.h	Wed Aug 13 03:14:30 2014 -0700
@@ -15,19 +15,18 @@
 #include "types/ScanResultList.h"
 
 
-/**
- * @namespace wiconnect
- */
 namespace wiconnect {
 
 
 /**
- * @ingroup types_network
+ * @ingroup api_network_types
  *
  * @brief The provides an interface for joining and/or creating a network.
  * It provides other utilities such as scanning for networks, pinging a network,
  * resolving a domain name to IP address.
  *
+ * @note This class is an interface to the Wiconnect class. It should never be
+ *       independently instantiated or the parent of another class.
  */
 class NetworkInterface
 {
@@ -36,6 +35,24 @@
      * @ingroup api_network_setup
      *
      * @brief Start the WiConnect WiFi module 'web setup' feature.
+     *
+     * This command has an optional background processing feature.
+     * Background processing is enabled if the completeHandler parameter
+     * is specified. If enabled, the library will poll the module every second
+     * for the web setup status (essentially it'll call isWebSetupRunning() every
+     * second in the background). When the web setup is no longer running the
+     * callback will be executed. The background processing is disabled when stopWebSetup()
+     * is called.
+     *
+     * @note only the 'result' parameter of the callback handler is valid.
+     *
+     * Refer to @ref setting_async_processing for more info.
+     *
+     * @param[in] ssid Optional, optionally set the SSID of module's softAp
+     * @param[in] password Optional, optionally set the WPA2-PSK password for the module'S softap
+     *                     Note: make an OPEN softAp, set this parameter to a null string (i.e. "")
+     * @param[in] completeHandler Optional, callback to be executed when module web setup completes.
+     * @return Result of method. See @ref WiconnectResult
      */
     WiconnectResult startWebSetup(const char *ssid = NULL, const char *password = NULL, const Callback &completeHandler = Callback());
 
@@ -43,6 +60,12 @@
      * @ingroup api_network_setup
      *
      * @brief Stop the WiConnect WiFi module 'web setup' feature.
+     *
+     * This method should be called AFTER startWebSetup() to prematurely terminate
+     * web setup. Note that this is not needed if web setup completes by itself
+     * (i.e. if the user exits web setup from the webpage).
+     *
+     *  @return Result of method. See @ref WiconnectResult
      */
     WiconnectResult stopWebSetup();
 
@@ -50,6 +73,11 @@
      * @ingroup api_network_setup
      *
      * @brief Return status of WiConnect WiFi module 'web setup' feature.
+     *
+     * This may be called at any time (whether web setpu has been stared or not).
+     *
+     * @param[out] isRunningPtr Pointer to bool to contain TRUE if web setup is running, FALSE else
+     * @return Result of method. See @ref WiconnectResult
      */
     WiconnectResult isWebSetupRunning(bool *isRunningPtr);
 
@@ -61,6 +89,27 @@
      * @ingroup api_network_wlan
      *
      * @brief Join a WiFi network.
+     *
+     * @note This command is returns when the join sequence has STARTED.
+     *       To determine if the module has successfully join the network either
+     *       specify the completeHandler or periodically call getNetworkStatus()
+     *
+     * This command has an optional background processing feature.
+     * Background processing is enabled if the completeHandler parameter
+     * is specified. If enabled, the library will poll the module every second
+     * for the join status (essentially it'll call getNetworkStatus() every
+     * second in the background). When the module join sequence complete the callback will be executed.
+     * The background processing is disabled when leave() is called.
+     *
+     * @note only the 'result' parameter of the callback handler is valid.
+     *
+     * Refer to @ref setting_async_processing for more info.
+     *
+     * @param[in] ssid Optional, optionally set the SSID of the network to join
+     * @param[in] password Optional, optionally set the passkey of the network to join
+     *                     Note: to join an OPEN network, set this parameter to a null string (i.e. "")
+     * @param[in] completeHandler Optional, callback to be executed when the join sequence completes.
+     * @return Result of method. See @ref WiconnectResult
      */
     WiconnectResult join(const char* ssid = NULL, const char *password = NULL, const Callback &completeHandler = Callback());
 
@@ -68,6 +117,11 @@
      * @ingroup api_network_wlan
      *
      * @brief Leave a WiFi network.
+     *
+     * This method may be called to either terminate a join sequence or
+     * leave a previously connected networked.
+     *
+     * @return Result of method. See @ref WiconnectResult
      */
     WiconnectResult leave();
 
@@ -75,6 +129,11 @@
      * @ingroup api_network_wlan
      *
      * @brief Get connection status to WiFi network.
+     *
+     * Refer to @ref NetworkStatus for more info.
+     *
+     * @param[out] statusPtr Point to a @ref NetworkStatus which will hold current network status of module
+     * @return Result of method. See @ref WiconnectResult
      */
     WiconnectResult getNetworkStatus(NetworkStatus *statusPtr);
 
@@ -93,6 +152,19 @@
      * @ingroup api_network_util
      *
      * @brief Scan for available WiFi networks.
+     *
+     * The populate the supplied @ref ScanResultList with @ref ScanResult of each found network.
+     *
+     * Optionally only scan of specific channels by supplying a null terminated list of channels.
+     * Example:
+     * @code
+     * const uint8_t channelsToScan[] = {1, 6, 11, 0};
+     * @endcode
+     *
+     * @param[out] resultList List to populate with scan results.
+     * @param[in] channelList Optional, null terminated list of channels to scan.
+     * @param[in] ssid Optional, specific network name to scan for.
+     * @return Result of method. See @ref WiconnectResult
      */
     WiconnectResult scan(ScanResultList &resultList, const uint8_t *channelList = NULL, const char* ssid = NULL);
 
@@ -100,6 +172,14 @@
      * @ingroup api_network_util
      *
      * @brief Ping a WiFi network.
+     *
+     * Optionally ping a specific server and return the time in milliseconds it took
+     * for the network to response. If no domain is supplied, the module pings to gateway
+     * (i.e router it's connected to).
+     *
+     * @param[in] domain Optional, the domain name to ping
+     * @param[out] timeMsPtr Optional, pointer to uint32 to hold time in milliseconds the ping took
+     * @return Result of method. See @ref WiconnectResult
      */
     WiconnectResult ping(const char *domain = NULL, uint32_t *timeMsPtr = NULL);
 
@@ -107,6 +187,10 @@
      * @ingroup api_network_util
      *
      * @brief Resolve domain name into IP address.
+     *
+     * @param[in] domain The domain name to resolve
+     * @param[out] ipAddressPtr pointer to uint32 to hold resolved IP address. Note, the IP address is in network-byte-order.
+     * @return Result of method. See @ref WiconnectResult
      */
     WiconnectResult lookup(const char *domain, uint32_t *ipAddressPtr);
 
@@ -118,6 +202,8 @@
      * @ingroup api_network_settings
      *
      * @brief Set DHCP enabled.
+     *
+     * @return Result of method. See @ref WiconnectResult
      */
     WiconnectResult setDhcpEnabled(bool enabled);