From 5c925bf96ed2ccf507f07c909a6430929212deb0 Mon Sep 17 00:00:00 2001 From: Angus Gratton Date: Thu, 29 Jun 2017 17:20:45 +1000 Subject: [PATCH] esp_wifi.h: Document the Vendor-Specific Information Element functions --- components/esp32/include/esp_wifi.h | 39 ++++++++++++----------- components/esp32/include/esp_wifi_types.h | 21 ++++++++++-- 2 files changed, 39 insertions(+), 21 deletions(-) diff --git a/components/esp32/include/esp_wifi.h b/components/esp32/include/esp_wifi.h index 6f1e8729ec..5f7aa9c222 100755 --- a/components/esp32/include/esp_wifi.h +++ b/components/esp32/include/esp_wifi.h @@ -730,37 +730,38 @@ esp_err_t esp_wifi_set_auto_connect(bool en); esp_err_t esp_wifi_get_auto_connect(bool *en); /** - * @brief Set vendor specific element + * @brief Set 802.11 Vendor-Specific Information Element * - * @param enable enable or not - * @param type information element type - * @param idx information element index - * @param vnd_ie pointer to a vendor specific element + * @param enable If true, specified IE is enabled. If false, specified IE is removed. + * @param type Information Element type. Determines the frame type to associate with the IE. + * @param idx Index to set or clear. Each IE type can be associated with up to two elements (indices 0 & 1). + * @param vnd_ie Pointer to vendor specific element data. First 6 bytes should be a header with fields matching vendor_ie_data_t. + * If enable is false, this argument is ignored and can be NULL. Data does not need to remain valid after the function returns. * * @return * - ESP_OK: succeed - * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by eps_wifi_init - * - ESP_ERR_WIFI_ARG: invalid argument - * - ESP_ERR_WIFI_NO_MEM: out of memory * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init() + * - ESP_ERR_WIFI_ARG: Invalid argument, including if first byte of vnd_ie is not WIFI_VENDOR_IE_ELEMENT_ID (0xDD) + * or second byte is an invalid length. + * - ESP_ERR_WIFI_NO_MEM: Out of memory */ -esp_err_t esp_wifi_set_vendor_ie(bool enable, wifi_vendor_ie_type_t type, wifi_vendor_ie_id_t idx, uint8_t *vnd_ie); +esp_err_t esp_wifi_set_vendor_ie(bool enable, wifi_vendor_ie_type_t type, wifi_vendor_ie_id_t idx, const void *vnd_ie); /** - * @brief Define function pointer for vendor specific element callback - * @param ctx reserved - * @param type information element type - * @param sa source address - * @param vnd_ie pointer to a vendor specific element - * @param rssi received signal strength indication + * @brief Function signature for received Vendor-Specific Information Element callback. + * @param ctx Context argument, as passed to esp_wifi_set_vendor_ie_cb() when registering callback. + * @param type Information element type, based on frame type received. + * @param sa Source 802.11 address. + * @param vnd_ie Pointer to the vendor specific element data received. + * @param rssi Received signal strength indication. */ -typedef void (*esp_vendor_ie_cb_t) (void *ctx, wifi_vendor_ie_type_t type, const uint8_t sa[6], const uint8_t *vnd_ie, int rssi); +typedef void (*esp_vendor_ie_cb_t) (void *ctx, wifi_vendor_ie_type_t type, const uint8_t sa[6], const vendor_ie_data_t *vnd_ie, int rssi); /** - * @brief Set vendor specific element callback + * @brief Register Vendor-Specific Information Element monitoring callback. * - * @param cb callback function - * @param ctx reserved + * @param cb Callback function + * @param ctx Context argument, passed to callback function. * * @return * - ESP_OK: succeed diff --git a/components/esp32/include/esp_wifi_types.h b/components/esp32/include/esp_wifi_types.h index f9a0467399..2410b73ce1 100755 --- a/components/esp32/include/esp_wifi_types.h +++ b/components/esp32/include/esp_wifi_types.h @@ -188,8 +188,9 @@ typedef enum { } wifi_storage_t; /** - * @brief Vendor IE type + * @brief Vendor Information Element type * + * Determines the frame type that the IE will be associated with. */ typedef enum { WIFI_VND_IE_TYPE_BEACON, @@ -200,14 +201,30 @@ typedef enum { } wifi_vendor_ie_type_t; /** - * @brief Vendor IE index + * @brief Vendor Information Element index * + * Each IE type can have up to two associated vendor ID elements. */ typedef enum { WIFI_VND_IE_ID_0, WIFI_VND_IE_ID_1, } wifi_vendor_ie_id_t; +#define WIFI_VENDOR_IE_ELEMENT_ID 0xDD + +/** + * @brief Vendor Information Element header + * + * The first bytes of the Information Element will match this header. Payload follows. + */ +typedef struct { + uint8_t element_id; /**< Should be set to WIFI_VENDOR_IE_ELEMENT_ID (0xDD) */ + uint8_t length; /**< Length of all bytes in the element data following this field. Minimum 4. */ + uint8_t vendor_oui[3]; /**< Vendor identifier (OUI). */ + uint8_t vendor_oui_type; /**< Vendor-specific OUI type. */ + uint8_t payload[0]; /**< Payload. Length is equal to value in 'length' field, minus 4. */ +} vendor_ie_data_t; + typedef struct { signed rssi:8; /**< signal intensity of packet */ unsigned rate:5; /**< data rate */