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