add wifi api comments

pull/21/head
liuzhifu 2016-09-07 20:33:13 +08:00 zatwierdzone przez Wu Jian Gang
rodzic b86e060647
commit ded5df7513
2 zmienionych plików z 96 dodań i 0 usunięć

Wyświetl plik

@ -105,10 +105,64 @@ typedef struct {
system_event_info_t event_info; /**< event information */
} system_event_t;
/**
* @brief Application specified event callback function
*
* @param system_event_t *event : event type defined in this file
*
* @return ESP_OK : succeed
* @return others : fail
*/
typedef esp_err_t (*system_event_cb_t)(system_event_t *event);
/**
* @brief Set application specified event callback function
*
* @attention 1. If cb is NULL, means application don't need to handle
* If cb is not NULL, it will be call when a event is received, after the default event callback is completed
*
* @param system_event_cb_t cb : callback
*
* @return ESP_OK : succeed
* @return others : fail
*/
system_event_cb_t esp_event_set_cb(system_event_cb_t cb);
/**
* @brief Send a event to event task
*
* @attention 1. Other task/module, such as TCPIP modudle, can call this API to send a event to event task
*
*
* @param system_event_t * event : event
*
* @return ESP_OK : succeed
* @return others : fail
*/
esp_err_t esp_event_send(system_event_t * event);
/**
* @brief Get the event handler
*
* @attention : currently this API returns event queue handler, generally this handler is used to
*
*
* @param null
*
* @return void* : event queue pointer
*/
void* esp_event_get_handler(void);
/**
* @brief Init the event module
* Create the event handler and task
*
* @param system_event_cb_t cb : application specified event callback, it can be modified by call esp_event_set_cb
*
* @return ESP_OK : succeed
* @return others : fail
*/
esp_err_t esp_event_init(system_event_cb_t cb);
#ifdef __cplusplus

Wyświetl plik

@ -12,6 +12,48 @@
// See the License for the specific language governing permissions and
// limitations under the License.
/* Notes about WiFi Programming
*
* The esp32 wifi programming model can be dipcts as following picture:
*
*
* default handler user handler
* ------------- --------------- ---------------
* | | event | | callback or | |
* | tcpip | ---------> | event | ----------> | application |
* | stack | | task | event | task |
* |-----------| |-------------| |-------------|
* /|\ |
* | |
* event | |
* | |
* | |
* --------------- |
* | | |
* | WiFi Driver |/__________________|
* | |\ API call
* | |
* |-------------|
*
* The wifi driver can be consider as black box, it knows nothing about the high layer code, such as
* TCPIP stack, application task, event task etc, all it can do is to receive API call from high laeyer
* or post event queue to a specified Queue, which is initilized by API esp_wifi_init().
*
* The event task is a daemon task, which receives events from WiFi driver or from other subsystem, such
* as TCPIP stack, event task will call the default callback function on receiving the event. For example,
* on receiving event SYSTEM_EVENT_STA_CONNECTED, it will call tcpip_adapter_start() to start the DHCP
* client in it's default handler.
*
* Application can register it's owner event callback function by API esp_event_init, then the application callback
* function will be called after the default callback. Also, if application don't want to excute the callback
* in event task, what it need to do is to post the related event to application task in the application callback function.
*
* The application task (code) generally mix all these thing together, it call APIs to init the system/wifi and
* handle the events when necessary.
*
*/
#ifndef __ESP_WIFI_H__
#define __ESP_WIFI_H__