@@ -50,6 +50,102 @@ Common API
5050
5151Here are the common APIs that are used for both modes, AP and STA.
5252
53+ onEvent (and removeEvent)
54+ *************************
55+
56+ Registers a caller-supplied function to be called when WiFi events
57+ occur. Several forms are available.
58+
59+ Function pointer callback taking the event ID:
60+
61+ .. code-block :: arduino
62+
63+ typedef void (*WiFiEventCb)(arduino_event_id_t);
64+ wifi_event_id_t onEvent(WiFiEventCb, arduino_event_id_t = ARDUINO_EVENT_MAX);
65+
66+
67+
68+ .. code-block :: arduino
69+
70+ typedef struct{
71+ arduino_event_id_t event_id;
72+ arduino_event_info_t event_info;
73+ } arduino_event_t;
74+
75+ typedef void (*WiFiEventSysCb)(arduino_event_t *);
76+ wifi_event_id_t onEvent(WiFiEventSysCb, arduino_event_id_t = ARDUINO_EVENT_MAX);
77+
78+ std::function `` taking event ID and info separately:
79+
80+ .. code-block :: arduino
81+
82+ typedef std::function<void(arduino_event_id_t, arduino_event_info_t)> WiFiEventFuncCb;
83+ wifi_event_id_t onEvent(WiFiEventFuncCb, arduino_event_id_t = ARDUINO_EVENT_MAX);
84+
85+
86+
87+ .. code-block :: arduino
88+
89+ void removeEvent(WiFiEventCb, arduino_event_id_t = ARDUINO_EVENT_MAX);
90+ void removeEvent(WiFiEventSysCb, arduino_event_id_t = ARDUINO_EVENT_MAX);
91+ void removeEvent(wifi_event_id_t = ARDUINO_EVENT_MAX);
92+
93+
94+ invoke the callback only for that specific event; with the default
95+ ``ARDUINO_EVENT_MAX ``, the callback will be invoked for all WiFi events.
96+
97+ Any callback function is given the event type in a parameter.
98+ Some of the possible callback function formats also take an
99+ ``arduino_event_info_t `` (or use ``arduino_event_t `` which includes both
100+ ID and info) which is a union of structs with additional information
101+ about different event types.
102+
103+ See
104+ `WiFiGeneric.h <https://github.com/espressif/arduino-esp32/blob/master/libraries/WiFi/src/WiFiGeneric.h >`_
105+ for the list of event types and "info" substructures, and also see a full
106+ example of event handling: `events example `_.
107+
108+ .. warning ::
109+
110+ Event callback functions are invoked on a separate
111+ `thread <https://en.wikipedia.org/wiki/Thread_(computing) >`_
112+ (`FreeRTOS task <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/system/freertos_idf.html#tasks >`_)
113+ independent of the main application thread that runs ``setup() `` and
114+ ``loop() ``. Callback functions must therefore be
115+ `thread-safe <https://en.wikipedia.org/wiki/Thread_safety >`_;
116+ they must not access shared/global variables directly without locking,
117+ and must only call similarly thread-safe functions.
118+
119+ Some core operations like ``Serial.print() `` are thread-safe but many
120+ functions are not. Notably, ``WiFi.onEvent() `` and ``WiFi.removeEvent() ``
121+ are not thread-safe and should never be invoked from a callback thread.
122+
123+ setHostname (and getHostname)
124+ *****************************
125+
126+ Sets the name the DHCP client uses to identify itself. In a typical network
127+ setup this will be the name that shows up in the Wi-Fi router's device list.
128+ The hostname must be no longer than 32 characters.
129+
130+ .. code-block :: arduino
131+
132+ setHostname(const char *hostname);
133+
134+
135+ on the chip type and MAC address. The current hostname (default or custom)
136+ may be retrieved:
137+
138+ .. code-block :: arduino
139+
140+ const char *getHostname();
141+
142+ warning ::
143+
144+ The ``setHostname() `` function must be called BEFORE WiFi is started with
145+ ``WiFi.begin() ``, ``WiFi.softAP() ``, ``WiFi.mode() ``, or ``WiFi.run() ``.
146+ To change the name, reset WiFi with ``WiFi.mode(WIFI_MODE_NULL) ``,
147+ then proceed with ``WiFi.setHostname(...) `` and restart WiFi from scratch.
148+
53149useStaticBuffers
54150****************
55151
@@ -547,11 +643,13 @@ Loads all infos from a scanned wifi in to the ptr parameters.
547643
548644 bool getNetworkInfo(uint8_t networkItem, String &ssid, uint8_t &encryptionType, int32_t &RSSI, uint8_t* &BSSID, int32_t &channel);
549645
550- WiFiScan ``, take a look at the ``WiFiScan.ino `` example available.
646+ WiFiScan ``, take a look at the ``WiFiScan.ino `` or `` WiFiScanAsync.ino `` example available.
551647
552648Examples
553649--------
554650
651+ `Complete list of WiFi examples <https://github.com/espressif/arduino-esp32/tree/master/libraries/WiFi/examples >`_.
652+
555653.. _ap example :
556654
557655Wi-Fi AP Example
@@ -568,5 +666,10 @@ Wi-Fi STA Example
568666.. literalinclude :: ../../../libraries/WiFi/examples/WiFiClient/WiFiClient.ino
569667 :language: arduino
570668
571- References
572- ----------
669+ .. _events example :
670+
671+ Wi-Fi Events Example
672+ ********************
673+
674+ .. literalinclude :: ../../../libraries/WiFi/examples/WiFiClientEvents/WiFiClientEvents.ino
675+ :language: arduino
0 commit comments