WiFiInterface.h

00001 
00002 /* WiFiInterface
00003  * Copyright (c) 2015 - 2016 ARM Limited
00004  *
00005  * Licensed under the Apache License, Version 2.0 (the "License");
00006  * you may not use this file except in compliance with the License.
00007  * You may obtain a copy of the License at
00008  *
00009  *     http://www.apache.org/licenses/LICENSE-2.0
00010  *
00011  * Unless required by applicable law or agreed to in writing, software
00012  * distributed under the License is distributed on an "AS IS" BASIS,
00013  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00014  * See the License for the specific language governing permissions and
00015  * limitations under the License.
00016  */
00017 
00018 #ifndef WIFI_INTERFACE_H
00019 #define WIFI_INTERFACE_H
00020 
00021 #include <string.h>
00022 #include "netsocket/NetworkInterface.h"
00023 #include "netsocket/WiFiAccessPoint.h"
00024 
00025 /** Common interface that is shared between Wi-Fi devices.
00026  *
00027  *  @addtogroup netsocket
00028  */
00029 class WiFiInterface: public virtual NetworkInterface {
00030 public:
00031     /** Get the default Wi-Fi interface.
00032      *
00033      * This is provided as a weak method so applications can override.
00034      * Default behaviour is to get the target's default interface, if
00035      * any.
00036      *
00037      * @return pointer to interface, if any.
00038      */
00039     static WiFiInterface *get_default_instance();
00040 
00041     /** Set the Wi-Fi network credentials.
00042      *
00043      *  @param ssid      Name of the network to connect to.
00044      *  @param pass      Security passphrase to connect to the network.
00045      *  @param security  Type of encryption for connection
00046      *                   (defaults to NSAPI_SECURITY_NONE).
00047      *  @return          NSAPI_ERROR_OK on success, or error code on failure.
00048      */
00049     virtual nsapi_error_t set_credentials(const char *ssid, const char *pass,
00050                                           nsapi_security_t security = NSAPI_SECURITY_NONE ) = 0;
00051 
00052     /** Set the Wi-Fi network channel.
00053      *
00054      *  @param channel   Channel on which the connection is to be made, or 0 for any (Default: 0).
00055      *  @return          NSAPI_ERROR_OK on success, or error code on failure.
00056      */
00057     virtual nsapi_error_t set_channel(uint8_t channel) = 0;
00058 
00059     /** Get the current radio signal strength for active connection.
00060      *
00061      *  @return         Connection strength in dBm (negative value),
00062      *                  or 0 if measurement impossible.
00063      */
00064     virtual int8_t get_rssi() = 0;
00065 
00066     /** Attempt to connect to a Wi-Fi network.
00067      *
00068      *  @param ssid      Name of the network to connect to.
00069      *  @param pass      Security passphrase to connect to the network.
00070      *  @param security  Type of encryption for connection (Default: NSAPI_SECURITY_NONE).
00071      *  @param channel   Channel on which the connection is to be made, or 0 for any (Default: 0).
00072      *  @return          NSAPI_ERROR_OK on success, or error code on failure.
00073      */
00074     virtual nsapi_error_t connect(const char *ssid, const char *pass,
00075                                   nsapi_security_t security = NSAPI_SECURITY_NONE , uint8_t channel = 0) = 0;
00076 
00077     /** Attempt to connect to a Wi-Fi network. Requires ssid and passphrase to be set.
00078      *  If passphrase is invalid, NSAPI_ERROR_AUTH_ERROR is returned.
00079      *
00080      *  @return         NSAPI_ERROR_OK on success, negative error code on failure.
00081      */
00082     virtual nsapi_error_t connect() = 0;
00083 
00084     /** Stop the interface.
00085      *
00086      *  @return         NSAPI_ERROR_OK on success, or error code on failure.
00087      */
00088     virtual nsapi_error_t disconnect() = 0;
00089 
00090     /** Scan for available networks.
00091      *
00092      *  This function will block. If the count is 0, function will only return count of available networks, so that
00093      *  user can allocated necessary memory. If the count is grater than 0 and the a \p res is not NULL it'll be populated
00094      *  with discovered networks up to value of count.
00095      *
00096      *  @param  res      Pointer to allocated array to store discovered APs.
00097      *  @param  count    Size of allocated res array, or 0 to only count available APs.
00098      *  @return          Number of entries in res, or if count was 0 number of available networks.
00099      *                   Negative on error (@see nsapi_types.h for nsapi_error).
00100      */
00101     virtual nsapi_size_or_error_t scan(WiFiAccessPoint *res, nsapi_size_t count) = 0;
00102 
00103     /** @copydoc NetworkInterface::wifiInterface
00104      */
00105     virtual WiFiInterface *wifiInterface()
00106     {
00107         return this;
00108     }
00109 
00110 #if !defined(DOXYGEN_ONLY)
00111 protected:
00112 
00113     /** Get the target's default Wi-Fi interface.
00114      *
00115      * This is provided as a weak method so targets can override. The
00116      * default implementation returns NULL.
00117      *
00118      * @return pointer to interface, if any.
00119      */
00120     static WiFiInterface *get_target_default_instance();
00121 #endif //!defined(DOXYGEN_ONLY)
00122 };
00123 
00124 #endif
00125 
00126 /** @}*/