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: NetworkInterface.h
- Revision:
- 13:2b51f5267c92
- Parent:
- 11:ea484e1b7fc4
- Child:
- 16:7f1d6d359787
diff -r 3dfec824715a -r 2b51f5267c92 NetworkInterface.h --- 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);