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 /** WiFiInterface class
00026  *
00027  *  Common interface that is shared between WiFi devices
00028  *  @addtogroup netsocket
00029  */
00030 class WiFiInterface: public virtual NetworkInterface {
00031 public:
00032     /** Get the default WiFi interface.
00033      *
00034      * This is provided as a weak method so applications can override.
00035      * Default behaviour is to get the target's default interface, if
00036      * any.
00037      *
00038      * @return pointer to interface, if any
00039      */
00040     static WiFiInterface *get_default_instance();
00041 
00042     /** Set the WiFi network credentials
00043      *
00044      *  @param ssid      Name of the network to connect to
00045      *  @param pass      Security passphrase to connect to the network
00046      *  @param security  Type of encryption for connection
00047      *                   (defaults to NSAPI_SECURITY_NONE)
00048      *  @return          0 on success, or error code on failure
00049      */
00050     virtual nsapi_error_t set_credentials(const char *ssid, const char *pass,
00051                                           nsapi_security_t security = NSAPI_SECURITY_NONE ) = 0;
00052 
00053     /** Set the WiFi network channel
00054      *
00055      *  @param channel   Channel on which the connection is to be made, or 0 for any (Default: 0)
00056      *  @return          0 on success, or error code on failure
00057      */
00058     virtual nsapi_error_t set_channel(uint8_t channel) = 0;
00059 
00060     /** Gets the current radio signal strength for active connection
00061      *
00062      *  @return         Connection strength in dBm (negative value),
00063      *                  or 0 if measurement impossible
00064      */
00065     virtual int8_t get_rssi() = 0;
00066 
00067     /** Start the interface
00068      *
00069      *  Attempts to connect to a WiFi network.
00070      *
00071      *  @param ssid      Name of the network to connect to
00072      *  @param pass      Security passphrase to connect to the network
00073      *  @param security  Type of encryption for connection (Default: NSAPI_SECURITY_NONE)
00074      *  @param channel   Channel on which the connection is to be made, or 0 for any (Default: 0)
00075      *  @return          0 on success, or error code on failure
00076      */
00077     virtual nsapi_error_t connect(const char *ssid, const char *pass,
00078                                   nsapi_security_t security = NSAPI_SECURITY_NONE , uint8_t channel = 0) = 0;
00079 
00080     /** Start the interface
00081      *
00082      *  Attempts to connect to a WiFi network. Requires ssid and passphrase to be set.
00083      *  If passphrase is invalid, NSAPI_ERROR_AUTH_ERROR is returned.
00084      *
00085      *  @return         0 on success, negative error code on failure
00086      */
00087     virtual nsapi_error_t connect() = 0;
00088 
00089     /** Stop the interface
00090      *
00091      *  @return         0 on success, or error code on failure
00092      */
00093     virtual nsapi_error_t disconnect() = 0;
00094 
00095     /** Scan for available networks
00096      *
00097      *  This function will block. If the @a count is 0, function will only return count of available networks, so that
00098      *  user can allocated necessary memory. If the \p count is grater than 0 and the a \p res is not NULL it'll be populated
00099      *  with discovered networks up to value of \p count.
00100      *
00101      *  @param  res      Pointer to allocated array to store discovered AP
00102      *  @param  count    Size of allocated @a res array, or 0 to only count available AP
00103      *  @return          Number of entries in \p count, or if \p count was 0 number of available networks,
00104      *                   negative on error see @a nsapi_error
00105      */
00106     virtual nsapi_size_or_error_t scan(WiFiAccessPoint *res, nsapi_size_t count) = 0;
00107 
00108     virtual WiFiInterface *wifiInterface()
00109     {
00110         return this;
00111     }
00112 
00113 protected:
00114 
00115     /** Get the target's default WiFi interface.
00116      *
00117      * This is provided as a weak method so targets can override. The
00118      * default implementation returns NULL.
00119      *
00120      * @return pointer to interface, if any
00121      */
00122     static WiFiInterface *get_target_default_instance();
00123 };
00124 
00125 #endif
00126 
00127 /** @}*/