1 /*
2  * SPDX-FileCopyrightText: 2019-2023 Espressif Systems (Shanghai) CO LTD
3  *
4  * SPDX-License-Identifier: Apache-2.0
5  */
6 
7 #ifndef _ESP_WIFI_DEFAULT_H
8 #define _ESP_WIFI_DEFAULT_H
9 
10 #include "esp_netif.h"
11 #include "esp_wifi_types.h"
12 
13 #ifdef __cplusplus
14 extern "C" {
15 #endif
16 
17 /**
18  * @brief Attaches wifi station interface to supplied netif
19  *
20  * @param esp_netif instance to attach the wifi station to
21  *
22  * @return
23  *  - ESP_OK on success
24  *  - ESP_FAIL if attach failed
25  */
26 esp_err_t esp_netif_attach_wifi_station(esp_netif_t *esp_netif);
27 
28 /**
29  * @brief Attaches wifi soft AP interface to supplied netif
30  *
31  * @param esp_netif instance to attach the wifi AP to
32  *
33  * @return
34  *  - ESP_OK on success
35  *  - ESP_FAIL if attach failed
36  */
37 esp_err_t esp_netif_attach_wifi_ap(esp_netif_t *esp_netif);
38 
39 /**
40  * @brief Sets default wifi event handlers for STA interface
41  *
42  * @return
43  *  - ESP_OK on success, error returned from esp_event_handler_register if failed
44  */
45 esp_err_t esp_wifi_set_default_wifi_sta_handlers(void);
46 
47 /**
48  * @brief Sets default wifi event handlers for AP interface
49  *
50  * @return
51  *  - ESP_OK on success, error returned from esp_event_handler_register if failed
52  */
53 esp_err_t esp_wifi_set_default_wifi_ap_handlers(void);
54 
55 /**
56  * @brief Sets default wifi event handlers for NAN interface
57  *
58  * @return
59  *  - ESP_OK on success, error returned from esp_event_handler_register if failed
60  */
61 esp_err_t esp_wifi_set_default_wifi_nan_handlers(void);
62 
63 /**
64  * @brief Clears default wifi event handlers for supplied network interface
65  *
66  * @param esp_netif instance of corresponding if object
67  *
68  * @return
69  *  - ESP_OK on success, error returned from esp_event_handler_register if failed
70  */
71 esp_err_t esp_wifi_clear_default_wifi_driver_and_handlers(void *esp_netif);
72 
73 /**
74  * @brief Creates default WIFI AP. In case of any init error this API aborts.
75  *
76  * @note The API creates esp_netif object with default WiFi access point config,
77  * attaches the netif to wifi and registers wifi handlers to the default event loop.
78  * This API uses assert() to check for potential errors, so it could abort the program.
79  * (Note that the default event loop needs to be created prior to calling this API)
80  *
81  * @return pointer to esp-netif instance
82  */
83 esp_netif_t* esp_netif_create_default_wifi_ap(void);
84 
85 /**
86  * @brief Creates default WIFI STA. In case of any init error this API aborts.
87  *
88  * @note The API creates esp_netif object with default WiFi station config,
89  * attaches the netif to wifi and registers wifi handlers to the default event loop.
90  * This API uses assert() to check for potential errors, so it could abort the program.
91  * (Note that the default event loop needs to be created prior to calling this API)
92  *
93  * @return pointer to esp-netif instance
94  */
95 esp_netif_t* esp_netif_create_default_wifi_sta(void);
96 
97 /**
98  * @brief Creates default WIFI NAN. In case of any init error this API aborts.
99  *
100  * @note The API creates esp_netif object with default WiFi station config,
101  * attaches the netif to wifi and registers wifi handlers to the default event loop.
102  * (Note that the default event loop needs to be created prior to calling this API)
103  *
104  * @return pointer to esp-netif instance
105  */
106 esp_netif_t* esp_netif_create_default_wifi_nan(void);
107 
108 /**
109  * @brief Destroys default WIFI netif created with esp_netif_create_default_wifi_...() API.
110  *
111  * @param[in] esp_netif object to detach from WiFi and destroy
112  *
113  * @note This API unregisters wifi handlers and detaches the created object from the wifi.
114  * (this function is a no-operation if esp_netif is NULL)
115  */
116 void esp_netif_destroy_default_wifi(void *esp_netif);
117 
118 /**
119  * @brief Creates esp_netif WiFi object based on the custom configuration.
120  *
121  * @attention This API DOES NOT register default handlers!
122  *
123  * @param[in] wifi_if type of wifi interface
124  * @param[in] esp_netif_config inherent esp-netif configuration pointer
125  *
126  * @return pointer to esp-netif instance
127  */
128 esp_netif_t* esp_netif_create_wifi(wifi_interface_t wifi_if, const esp_netif_inherent_config_t *esp_netif_config);
129 
130 /**
131  * @brief Creates default STA and AP network interfaces for esp-mesh.
132  *
133  * Both netifs are almost identical to the default station and softAP, but with
134  * DHCP client and server disabled. Please note that the DHCP client is typically
135  * enabled only if the device is promoted to a root node.
136  *
137  * Returns created interfaces which could be ignored setting parameters to NULL
138  * if an application code does not need to save the interface instances
139  * for further processing.
140  *
141  * @param[out] p_netif_sta pointer where the resultant STA interface is saved (if non NULL)
142  * @param[out] p_netif_ap pointer where the resultant AP interface is saved (if non NULL)
143  *
144  * @return ESP_OK on success
145  */
146 esp_err_t esp_netif_create_default_wifi_mesh_netifs(esp_netif_t **p_netif_sta, esp_netif_t **p_netif_ap);
147 
148 #ifdef __cplusplus
149 }
150 #endif
151 
152 #endif //_ESP_WIFI_DEFAULT_H
153