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
NetworkInterface.h
- Committer:
- dan_ackme
- Date:
- 2014-08-13
- Revision:
- 13:2b51f5267c92
- Parent:
- 11:ea484e1b7fc4
- Child:
- 16:7f1d6d359787
File content as of revision 13:2b51f5267c92:
/* * Copyright 2014, ACKme Networks * All Rights Reserved. * * This is UNPUBLISHED PROPRIETARY SOURCE CODE of ACKme Networks; * the contents of this file may not be disclosed to third parties, copied * or duplicated in any form, in whole or in part, without the prior * written permission of ACKme Networks. */ #pragma once #include "WiconnectTypes.h" #include "types/ScanResultList.h" namespace wiconnect { /** * @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 { public: /** * @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()); /** * @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(); /** * @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); // ------------------------------------------------------------------------ /** * @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()); /** * @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(); /** * @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); // ------------------------------------------------------------------------ // WiconnectResult startSoftAp(const char* ssid = NULL, const char *password = NULL, const Callback &clientConnectedCallback = Callback()); // WiconnectResult stopSoftAp(); // WiconnectResult getSoftApClientList(); // ------------------------------------------------------------------------ /** * @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); /** * @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); /** * @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); // ------------------------------------------------------------------------ /** * @ingroup api_network_settings * * @brief Set DHCP enabled. * * @return Result of method. See @ref WiconnectResult */ WiconnectResult setDhcpEnabled(bool enabled); /** * @ingroup api_network_settings * * @brief Get if DHCP enabled. */ WiconnectResult getDhcpEnabled(bool *enabledPtr); /** * @ingroup api_network_settings * * @brief Set static IP settings */ WiconnectResult setIpSettings(uint32_t ip, uint32_t netmask, uint32_t gateway); /** * @ingroup api_network_settings * * @brief Set static IP settings (with string parameters) */ WiconnectResult setIpSettings(const char* ip, const char* netmask, const char* gateway); /** * @ingroup api_network_settings * * @brief Get network IP settings */ WiconnectResult getIpSettings(uint32_t *ip, uint32_t *netmask, uint32_t *gateway); /** * @ingroup api_network_settings * * @brief Get signal strength to WiFi network */ WiconnectResult getSignalStrength(NetworkSignalStrength *signalStrengthPtr); // ------------------------------------------------------------------------ /** * @ingroup conversion_util * * @brief Convert string to IP address */ static bool strToIp(const char *str, uint32_t *intPtr); /** * @ingroup conversion_util * * @brief Convert IP address to string */ static const char* ipToStr(uint32_t ip, char *ipStrBuffer = NULL); /** * @ingroup conversion_util * * @brief Convert @ref NetworkStatus to string */ static const char* networkStatusToStr(NetworkStatus status); /** * @ingroup conversion_util * * @brief Convert @ref NetworkSignalStrength to string */ static const char* signalStrengthToStr(NetworkSignalStrength signalStrenth); /** * @ingroup conversion_util * * @brief Convert RSSI (in dBm) to @ref NetworkSignalStrength */ static NetworkSignalStrength rssiToSignalStrength(int rssi); /** * @ingroup conversion_util * * @brief Convert string to @ref NetworkSecurity */ static NetworkSecurity strToNetworkSecurity(const char *str); /** * @ingroup conversion_util * * @brief Convert @ref NetworkSecurity to string */ static const char* networkSecurityToStr(NetworkSecurity security); /** * @ingroup conversion_util * * @brief Convert string @ref Ssid */ static bool strToSsid(const char *str, Ssid *ssid); /** * @ingroup conversion_util * * @brief Convert @ref Ssid to string */ static const char* ssidToStr(const Ssid *ssid, char *ssidStrBuffer = NULL); /** * @ingroup conversion_util * * @brief Convert string @ref MacAddress */ static bool strToMacAddress(const char *str, MacAddress *macAddress); /** * @ingroup conversion_util * * @brief Convert @ref MacAddress to string */ static const char* macAddressToStr(const MacAddress *macAddress, char *macStrBuffer = NULL); protected: NetworkInterface(Wiconnect *wiconnect); WiconnectResult processScanResults(char *resultStr, ScanResultList &resultList); #ifdef WICONNECT_ASYNC_TIMER_ENABLED Callback completeHandler; PeriodicTimer monitorTimer; void webSetupStatusMonitor(); void webSetupStatusCheckCallback(WiconnectResult result, void *arg1, void *arg2); void joinStatusMonitor(); void joinStatusCheckCallback(WiconnectResult result, void *arg1, void *arg2); //void scanCompleteCallback(WiconnectResult result, void *arg1, void *arg2); #endif private: Wiconnect *wiconnect; }; }