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