Mistake on this page?
Report an issue in GitHub or email us
WiFiInterface.h
1 /*
2  * Copyright (c) 2015 - 2016 ARM Limited
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 /** @file WifiInterface.h Common interface between Wi-Fi devices */
18 /** @addtogroup netinterface
19  * @{
20  */
21 
22 #ifndef WIFI_INTERFACE_H
23 #define WIFI_INTERFACE_H
24 
25 #include <string.h>
27 #include "netsocket/WiFiAccessPoint.h"
28 
29 /** Common interface between Wi-Fi devices.
30  */
31 class WiFiInterface: public virtual NetworkInterface {
32 public:
33  /** Get the default Wi-Fi interface.
34  *
35  * This is provided as a weak method so applications can override it.
36  * Default behavior is to get the target's default interface, if
37  * any.
38  *
39  * @return pointer to interface, if any.
40  */
42 
43  /** Set the Wi-Fi network credentials.
44  *
45  * @param ssid Name of the network to connect to.
46  * @param pass Security passphrase to connect to the network.
47  * @param security Type of encryption for connection
48  * (defaults to NSAPI_SECURITY_NONE).
49  * @return NSAPI_ERROR_OK on success, or error code on failure.
50  */
51  virtual nsapi_error_t set_credentials(const char *ssid, const char *pass,
52  nsapi_security_t security = NSAPI_SECURITY_NONE) = 0;
53 
54  /** Set the Wi-Fi network channel.
55  *
56  * @param channel Channel to make the connection, or 0 for any (Default: 0).
57  * @return NSAPI_ERROR_OK on success, or error code on failure.
58  */
59  virtual nsapi_error_t set_channel(uint8_t channel) = 0;
60 
61  /** Get the current radio signal strength for active connection.
62  *
63  * @return Connection strength in dBm (negative value),
64  * or 0 if measurement impossible.
65  */
66  virtual int8_t get_rssi() = 0;
67 
68  /** Attempt to connect to a Wi-Fi network.
69  *
70  * @param ssid Name of the network to connect to.
71  * @param pass Security passphrase to connect to the network.
72  * @param security Type of encryption for connection (Default: NSAPI_SECURITY_NONE).
73  * @param channel Channel to make the connection, or 0 for any (Default: 0).
74  * @return NSAPI_ERROR_OK on success, or error code on failure.
75  */
76  virtual nsapi_error_t connect(const char *ssid, const char *pass,
77  nsapi_security_t security = NSAPI_SECURITY_NONE, uint8_t channel = 0) = 0;
78 
79  /** Attempt to connect to a Wi-Fi network. Requires ssid and passphrase to be set.
80  * If passphrase is invalid, NSAPI_ERROR_AUTH_ERROR is returned.
81  *
82  * @return NSAPI_ERROR_OK on success, negative error code on failure.
83  */
84  nsapi_error_t connect() override = 0;
85 
86  /** Stop the interface.
87  *
88  * @return NSAPI_ERROR_OK on success, or error code on failure.
89  */
90  nsapi_error_t disconnect() override = 0;
91 
92  /** Scan for available networks.
93  *
94  * @note This is a blocking function.
95  *
96  * If the \p count is 0, the function only returns the number of available networks.
97  * If the \p count is greater than 0 and the \p res is not NULL, the array of discovered APs is populated
98  * with discovered networks up to the value of the \p count.
99  *
100  * @param res Pointer to allocated array to store discovered APs.
101  * @param count Size of allocated res array, or 0 to only count available APs.
102  * @return Number of entries in res, or if count was 0, number of available networks.
103  * Negative on error (@see nsapi_types.h for nsapi_error).
104  */
105  virtual nsapi_size_or_error_t scan(WiFiAccessPoint *res, nsapi_size_t count) = 0;
106 
107  /** @copydoc NetworkInterface::wifiInterface
108  */
110  {
111  return this;
112  }
113 
114 #if !defined(DOXYGEN_ONLY)
115 protected:
116 
117  /** Get the target's default Wi-Fi interface.
118  *
119  * This is provided as a weak method so targets can override it. The
120  * default implementation returns NULL.
121  *
122  * @return pointer to interface, if any.
123  */
124  static WiFiInterface *get_target_default_instance();
125 #endif //!defined(DOXYGEN_ONLY)
126 
127 public:
128  /** Set default parameters on a Wi-Fi interface.
129  *
130  * A Wi-Fi interface instantiated directly or using
131  * WiFiInterface::get_default_instance() is initially unconfigured.
132  * This call can be used to set the default parameters that would
133  * have been set if the interface had been requested using
134  * NetworkInterface::get_default_instance() (see nsapi JSON
135  * configuration).
136  */
137  void set_default_parameters() override;
138 };
139 
140 #endif
141 
142 /** @}*/
Common interface between Wi-Fi devices.
Definition: WiFiInterface.h:31
Network Interface base class.
virtual nsapi_error_t set_channel(uint8_t channel)=0
Set the Wi-Fi network channel.
signed int nsapi_error_t
Type used to represent error codes.
Definition: nsapi_types.h:95
virtual nsapi_error_t set_credentials(const char *ssid, const char *pass, nsapi_security_t security=NSAPI_SECURITY_NONE)=0
Set the Wi-Fi network credentials.
signed int nsapi_size_or_error_t
Type used to represent either a size or error passed through sockets.
Definition: nsapi_types.h:106
static WiFiInterface * get_default_instance()
Get the default Wi-Fi interface.
virtual int8_t get_rssi()=0
Get the current radio signal strength for active connection.
nsapi_error_t disconnect() override=0
Stop the interface.
Common interface that is shared between network devices.
virtual nsapi_size_or_error_t scan(WiFiAccessPoint *res, nsapi_size_t count)=0
Scan for available networks.
unsigned int nsapi_size_t
Type used to represent the size of data passed through sockets.
Definition: nsapi_types.h:99
void set_default_parameters() override
defined(DOXYGEN_ONLY)
enum nsapi_security nsapi_security_t
Enum of encryption types.
WiFiInterface * wifiInterface() final
Return pointer to a WiFiInterface.
nsapi_error_t connect() override=0
Attempt to connect to a Wi-Fi network.
WiFiAccessPoint class.
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.