mirror of
https://github.com/espressif/esp-idf.git
synced 2024-09-21 06:56:11 -04:00
change(wifi): Add supplicant's public API header files to doc
This commit is contained in:
Kapil Gupta
parent
6c9692ecef
commit
52120cde26
@ -13,18 +13,33 @@
|
||||
extern "C" {
|
||||
#endif
|
||||
|
||||
/**
|
||||
* @brief Enumeration of phase 2 authentication types for EAP-TTLS.
|
||||
*
|
||||
* This enumeration defines the supported phase 2 authentication methods
|
||||
* that can be used in the EAP-TTLS (Extensible Authentication Protocol -
|
||||
* Tunneled Transport Layer Security) protocol for the second authentication
|
||||
* phase.
|
||||
*/
|
||||
typedef enum {
|
||||
ESP_EAP_TTLS_PHASE2_EAP,
|
||||
ESP_EAP_TTLS_PHASE2_MSCHAPV2,
|
||||
ESP_EAP_TTLS_PHASE2_MSCHAP,
|
||||
ESP_EAP_TTLS_PHASE2_PAP,
|
||||
ESP_EAP_TTLS_PHASE2_CHAP
|
||||
ESP_EAP_TTLS_PHASE2_EAP, /**< EAP (Extensible Authentication Protocol) */
|
||||
ESP_EAP_TTLS_PHASE2_MSCHAPV2, /**< MS-CHAPv2 (Microsoft Challenge Handshake Authentication Protocol - Version 2) */
|
||||
ESP_EAP_TTLS_PHASE2_MSCHAP, /**< MS-CHAP (Microsoft Challenge Handshake Authentication Protocol) */
|
||||
ESP_EAP_TTLS_PHASE2_PAP, /**< PAP (Password Authentication Protocol) */
|
||||
ESP_EAP_TTLS_PHASE2_CHAP /**< CHAP (Challenge Handshake Authentication Protocol) */
|
||||
} esp_eap_ttls_phase2_types;
|
||||
|
||||
/**
|
||||
* @brief Configuration settings for EAP-FAST
|
||||
* (Extensible Authentication Protocol - Flexible Authentication via Secure Tunneling).
|
||||
*
|
||||
* This structure defines the configuration options that can be used to customize the behavior of the
|
||||
* EAP-FAST authentication protocol, specifically for Fast Provisioning and PAC (Protected Access Credential) handling.
|
||||
*/
|
||||
typedef struct {
|
||||
int fast_provisioning; /* Enables or disables Fast Provisioning in EAP-FAST */
|
||||
int fast_max_pac_list_len; /* Maximum length of the PAC (Protected Access Credential) list */
|
||||
bool fast_pac_format_binary; /* Set to true for binary format PAC, false for ASCII format PAC */
|
||||
int fast_provisioning; /**< Enable or disable Fast Provisioning in EAP-FAST (0 = disabled, 1 = enabled) */
|
||||
int fast_max_pac_list_len; /**< Maximum length of the PAC (Protected Access Credential) list */
|
||||
bool fast_pac_format_binary; /**< Set to true for binary format PAC, false for ASCII format PAC */
|
||||
} esp_eap_fast_config;
|
||||
|
||||
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
/*
|
||||
* SPDX-FileCopyrightText: 2021 Espressif Systems (Shanghai) CO LTD
|
||||
* SPDX-FileCopyrightText: 2021-2023 Espressif Systems (Shanghai) CO LTD
|
||||
*
|
||||
* SPDX-License-Identifier: Apache-2.0
|
||||
*/
|
||||
@ -13,39 +13,41 @@ extern "C" {
|
||||
#endif
|
||||
|
||||
/**
|
||||
* enum non_pref_chan_reason: Reason for non preference of channel
|
||||
* @brief Enumeration of reasons for a channel being non-preferred in a wireless network.
|
||||
*
|
||||
* This enumeration defines various reasons why a specific channel might be considered non-preferred
|
||||
* in a wireless network configuration.
|
||||
*/
|
||||
enum non_pref_chan_reason {
|
||||
NON_PREF_CHAN_REASON_UNSPECIFIED = 0,
|
||||
NON_PREF_CHAN_REASON_RSSI = 1,
|
||||
NON_PREF_CHAN_REASON_EXT_INTERFERENCE = 2,
|
||||
NON_PREF_CHAN_REASON_INT_INTERFERENCE = 3,
|
||||
NON_PREF_CHAN_REASON_UNSPECIFIED = 0, /**< Unspecified reason for non-preference */
|
||||
NON_PREF_CHAN_REASON_RSSI = 1, /**< Non-preferred due to low RSSI (Received Signal Strength Indication) */
|
||||
NON_PREF_CHAN_REASON_EXT_INTERFERENCE = 2, /**< Non-preferred due to external interference */
|
||||
NON_PREF_CHAN_REASON_INT_INTERFERENCE = 3, /**< Non-preferred due to internal interference */
|
||||
};
|
||||
|
||||
/**
|
||||
* @brief Channel structure for non preferred channel
|
||||
* @brief Structure representing a non-preferred channel in a wireless network.
|
||||
*
|
||||
* @param reason: enum non_pref_chan_reason
|
||||
* @param oper_class: operating class for the channel
|
||||
* @param chan: channel number
|
||||
* @param preference: channel preference
|
||||
* This structure encapsulates information about a non-preferred channel
|
||||
* including the reason for its non-preference, the operating class, channel number, and preference level.
|
||||
*/
|
||||
struct non_pref_chan {
|
||||
enum non_pref_chan_reason reason;
|
||||
uint8_t oper_class;
|
||||
uint8_t chan;
|
||||
uint8_t preference;
|
||||
enum non_pref_chan_reason reason; /**< Reason for the channel being non-preferred */
|
||||
uint8_t oper_class; /**< Operating class of the channel */
|
||||
uint8_t chan; /**< Channel number */
|
||||
uint8_t preference; /**< Preference level of the channel */
|
||||
};
|
||||
|
||||
/**
|
||||
* @brief Array structure for non preferred channel struct
|
||||
* @brief Structure representing a list of non-preferred channels in a wireless network.
|
||||
*
|
||||
* @param non_pref_chan_num: channel count
|
||||
* @param chan: array of non_pref_chan type
|
||||
* This structure encapsulates information about a list of non-preferred channels
|
||||
* including the number of non-preferred channels and an array of structures
|
||||
* representing individual non-preferred channels.
|
||||
*/
|
||||
struct non_pref_chan_s {
|
||||
size_t non_pref_chan_num;
|
||||
struct non_pref_chan chan[];
|
||||
size_t non_pref_chan_num; /**< Number of non-preferred channels in the list */
|
||||
struct non_pref_chan chan[]; /**< Array of structures representing individual non-preferred channels */
|
||||
};
|
||||
|
||||
/**
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
/*
|
||||
* SPDX-FileCopyrightText: 2019-2021 Espressif Systems (Shanghai) CO LTD
|
||||
* SPDX-FileCopyrightText: 2019-2023 Espressif Systems (Shanghai) CO LTD
|
||||
*
|
||||
* SPDX-License-Identifier: Apache-2.0
|
||||
*/
|
||||
@ -33,32 +33,60 @@ extern "C" {
|
||||
#define ESP_ERR_WIFI_WPS_TYPE (ESP_ERR_WIFI_BASE + 52) /*!< WPS type error */
|
||||
#define ESP_ERR_WIFI_WPS_SM (ESP_ERR_WIFI_BASE + 53) /*!< WPS state machine is not initialized */
|
||||
|
||||
/**
|
||||
* @brief Enumeration of WPS (Wi-Fi Protected Setup) types.
|
||||
*/
|
||||
typedef enum wps_type {
|
||||
WPS_TYPE_DISABLE = 0,
|
||||
WPS_TYPE_PBC,
|
||||
WPS_TYPE_PIN,
|
||||
WPS_TYPE_MAX,
|
||||
WPS_TYPE_DISABLE = 0, /**< WPS is disabled */
|
||||
WPS_TYPE_PBC, /**< WPS Push Button Configuration method */
|
||||
WPS_TYPE_PIN, /**< WPS PIN (Personal Identification Number) method */
|
||||
WPS_TYPE_MAX /**< Maximum value for WPS type enumeration */
|
||||
} wps_type_t;
|
||||
|
||||
#define WPS_MAX_MANUFACTURER_LEN 65
|
||||
#define WPS_MAX_MODEL_NUMBER_LEN 33
|
||||
#define WPS_MAX_MODEL_NAME_LEN 33
|
||||
#define WPS_MAX_DEVICE_NAME_LEN 33
|
||||
#define WPS_MAX_MANUFACTURER_LEN 65 /**< Maximum length of the manufacturer name in WPS information */
|
||||
#define WPS_MAX_MODEL_NUMBER_LEN 33 /**< Maximum length of the model number in WPS information */
|
||||
#define WPS_MAX_MODEL_NAME_LEN 33 /**< Maximum length of the model name in WPS information */
|
||||
#define WPS_MAX_DEVICE_NAME_LEN 33 /**< Maximum length of the device name in WPS information */
|
||||
|
||||
/**
|
||||
* @brief Structure representing WPS factory information for ESP device.
|
||||
*
|
||||
* This structure holds various strings representing factory information for a device, such as the manufacturer,
|
||||
* model number, model name, and device name. Each string is a null-terminated character array. If any of the
|
||||
* strings are empty, the default values are used.
|
||||
*/
|
||||
typedef struct {
|
||||
char manufacturer[WPS_MAX_MANUFACTURER_LEN]; /*!< Manufacturer, null-terminated string. The default manufcturer is used if the string is empty */
|
||||
char model_number[WPS_MAX_MODEL_NUMBER_LEN]; /*!< Model number, null-terminated string. The default model number is used if the string is empty */
|
||||
char model_name[WPS_MAX_MODEL_NAME_LEN]; /*!< Model name, null-terminated string. The default model name is used if the string is empty */
|
||||
char device_name[WPS_MAX_DEVICE_NAME_LEN]; /*!< Device name, null-terminated string. The default device name is used if the string is empty */
|
||||
char manufacturer[WPS_MAX_MANUFACTURER_LEN]; /*!< Manufacturer of the device. If empty, the default manufacturer is used. */
|
||||
char model_number[WPS_MAX_MODEL_NUMBER_LEN]; /*!< Model number of the device. If empty, the default model number is used. */
|
||||
char model_name[WPS_MAX_MODEL_NAME_LEN]; /*!< Model name of the device. If empty, the default model name is used. */
|
||||
char device_name[WPS_MAX_DEVICE_NAME_LEN]; /*!< Device name. If empty, the default device name is used. */
|
||||
} wps_factory_information_t;
|
||||
|
||||
#define PIN_LEN 9
|
||||
#define PIN_LEN 9 /*!< The length of the WPS PIN (Personal Identification Number). */
|
||||
/**
|
||||
* @brief Structure representing configuration settings for WPS (Wi-Fi Protected Setup).
|
||||
*
|
||||
* This structure encapsulates various configuration settings for WPS, including the WPS type (PBC or PIN),
|
||||
* factory information that will be shown in the WPS Information Element (IE), and a PIN if the WPS type is
|
||||
* set to PIN.
|
||||
*/
|
||||
typedef struct {
|
||||
wps_type_t wps_type;
|
||||
wps_factory_information_t factory_info;
|
||||
char pin[PIN_LEN];
|
||||
wps_type_t wps_type; /*!< The type of WPS to be used (PBC or PIN). */
|
||||
wps_factory_information_t factory_info; /*!< Factory information to be shown in the WPS Information Element (IE). Vendor can choose to display their own information. */
|
||||
char pin[PIN_LEN]; /*!< WPS PIN (Personal Identification Number) used when wps_type is set to WPS_TYPE_PIN. */
|
||||
} esp_wps_config_t;
|
||||
|
||||
/**
|
||||
* @def WPS_CONFIG_INIT_DEFAULT(type)
|
||||
* @brief Initialize a default WPS configuration structure with specified WPS type.
|
||||
*
|
||||
* This macro initializes a `esp_wps_config_t` structure with default values for the specified WPS type.
|
||||
* It sets the WPS type, factory information (including default manufacturer, model number, model name, and device name),
|
||||
* and a default PIN value if applicable.
|
||||
*
|
||||
* @param type The WPS type to be used (PBC or PIN).
|
||||
* @return An initialized `esp_wps_config_t` structure with the specified WPS type and default values.
|
||||
*/
|
||||
#define WPS_CONFIG_INIT_DEFAULT(type) { \
|
||||
.wps_type = type, \
|
||||
.factory_info = { \
|
||||
@ -73,9 +101,7 @@ typedef struct {
|
||||
/**
|
||||
* @brief Enable Wi-Fi WPS function.
|
||||
*
|
||||
* @attention WPS can only be used when station is enabled.
|
||||
*
|
||||
* @param wps_type_t wps_type : WPS type, so far only WPS_TYPE_PBC and WPS_TYPE_PIN is supported
|
||||
* @param config : WPS config to be used in connection
|
||||
*
|
||||
* @return
|
||||
* - ESP_OK : succeed
|
||||
@ -88,8 +114,6 @@ esp_err_t esp_wifi_wps_enable(const esp_wps_config_t *config);
|
||||
/**
|
||||
* @brief Disable Wi-Fi WPS function and release resource it taken.
|
||||
*
|
||||
* @param null
|
||||
*
|
||||
* @return
|
||||
* - ESP_OK : succeed
|
||||
* - ESP_ERR_WIFI_WPS_MODE : wifi is not in station mode or sniffer mode is on
|
||||
@ -97,9 +121,9 @@ esp_err_t esp_wifi_wps_enable(const esp_wps_config_t *config);
|
||||
esp_err_t esp_wifi_wps_disable(void);
|
||||
|
||||
/**
|
||||
* @brief WPS starts to work.
|
||||
* @brief Start WPS session.
|
||||
*
|
||||
* @attention WPS can only be used when station is enabled.
|
||||
* @attention WPS can only be used when station is enabled. WPS needs to be enabled first for using this API.
|
||||
*
|
||||
* @param timeout_ms : deprecated: This argument's value will have not effect in functionality of API.
|
||||
* The argument will be removed in future.
|
||||
@ -120,7 +144,7 @@ esp_err_t esp_wifi_wps_start(int timeout_ms);
|
||||
*
|
||||
* @attention WPS can only be used when softAP is enabled.
|
||||
*
|
||||
* @param esp_wps_config_t config: wps configuration to be used.
|
||||
* @param config: wps configuration to be used.
|
||||
*
|
||||
* @return
|
||||
* - ESP_OK : succeed
|
||||
@ -133,8 +157,6 @@ esp_err_t esp_wifi_ap_wps_enable(const esp_wps_config_t *config);
|
||||
/**
|
||||
* @brief Disable Wi-Fi SoftAP WPS function and release resource it taken.
|
||||
*
|
||||
* @param null
|
||||
*
|
||||
* @return
|
||||
* - ESP_OK : succeed
|
||||
* - ESP_ERR_WIFI_WPS_MODE : wifi is not in station mode or sniffer mode is on
|
||||
|
||||
@ -185,6 +185,11 @@ INPUT = \
|
||||
$(PROJECT_PATH)/components/esp_wifi/include/esp_wifi_default.h \
|
||||
$(PROJECT_PATH)/components/esp_wifi/include/esp_wifi_types.h \
|
||||
$(PROJECT_PATH)/components/esp_wifi/include/esp_wifi.h \
|
||||
$(PROJECT_PATH)/components/wpa_supplicant/esp_supplicant/include/esp_mbo.h \
|
||||
$(PROJECT_PATH)/components/wpa_supplicant/esp_supplicant/include/esp_eap_client.h \
|
||||
$(PROJECT_PATH)/components/wpa_supplicant/esp_supplicant/include/esp_rrm.h \
|
||||
$(PROJECT_PATH)/components/wpa_supplicant/esp_supplicant/include/esp_wnm.h \
|
||||
$(PROJECT_PATH)/components/wpa_supplicant/esp_supplicant/include/esp_wps.h \
|
||||
$(PROJECT_PATH)/components/esp_wifi/wifi_apps/include/esp_nan.h \
|
||||
$(PROJECT_PATH)/components/esp-tls/esp_tls_errors.h \
|
||||
$(PROJECT_PATH)/components/esp-tls/esp_tls.h \
|
||||
|
||||
@ -28,3 +28,8 @@ API Reference
|
||||
|
||||
.. include-build-file:: inc/esp_wifi.inc
|
||||
.. include-build-file:: inc/esp_wifi_types.inc
|
||||
.. include-build-file:: inc/esp_eap_client.inc
|
||||
.. include-build-file:: inc/esp_wps.inc
|
||||
.. include-build-file:: inc/esp_rrm.inc
|
||||
.. include-build-file:: inc/esp_wnm.inc
|
||||
.. include-build-file:: inc/esp_mbo.inc
|
||||
|
||||
@ -11,3 +11,4 @@ Migration from 5.0 to 5.1
|
||||
storage
|
||||
networking
|
||||
system
|
||||
wifi
|
||||
|
||||
10
docs/en/migration-guides/release-5.x/5.1/wifi.rst
Normal file
10
docs/en/migration-guides/release-5.x/5.1/wifi.rst
Normal file
@ -0,0 +1,10 @@
|
||||
WiFi
|
||||
====
|
||||
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
|
||||
WiFi Enterprise security
|
||||
------------------------
|
||||
|
||||
APIs defined in `esp_wpa2.h` have been deprecated. Please use newer APIs from `esp_eap_client.h`.
|
||||
@ -11,3 +11,4 @@
|
||||
storage
|
||||
networking
|
||||
system
|
||||
wifi
|
||||
|
||||
10
docs/zh_CN/migration-guides/release-5.x/5.1/wifi.rst
Normal file
10
docs/zh_CN/migration-guides/release-5.x/5.1/wifi.rst
Normal file
@ -0,0 +1,10 @@
|
||||
WiFi
|
||||
====
|
||||
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
|
||||
WiFi企业级安全
|
||||
------------------------
|
||||
|
||||
在 `esp_wpa2.h` 中定义的API已被弃用，请使用来自 `esp_eap_client.h` 的新API。
|
||||
Loading…
Reference in New Issue
Block a user