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