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>
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  */
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  */
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 /** @}*/
Common interface between Wi-Fi devices.
Definition: WiFiInterface.h:32
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:140
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:151
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:144
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.