DGNum/hostapd
6
0
Fork 0
Code Issues Pull requests 1 Projects Releases Packages Wiki Activity Actions

Add preliminary documentation for ctrl_iface events

Browse source
This commit is contained in:
Jouni Malinen 2010-01-15 19:24:08 +02:00 committed by Jouni Malinen
parent 3145e6154c
commit b590812e8f
2 changed files with 239 additions and 2 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

237
doc/ctrl_iface.doxygen
View file

@ -478,4 +478,241 @@ wlan0
eth0 eth0
\endverbatim \endverbatim
\section ctrl_iface_events Control interface events
%wpa_supplicant generates number messages based on events like
connection or a completion of a task. These are available to external
programs that attach to receive unsolicited messages over the control
interface with wpa_ctrl_attach().
The event messages will be delivered over the attach control interface
as text strings that start with the priority level of the message and
a fixed prefix text as defined in wpa_ctrl.h. After this, optional
additional information may be included depending on the event
message. For example, following event message is delivered when new
scan results are available:
\verbatim
<2>CTRL-EVENT-SCAN-RESULTS
\endverbatim
Following priority levels are used:
- 0 = MSGDUMP
- 1 = DEBUG
- 2 = INFO
- 3 = WARNING
- 4 = ERROR
By default, any priority level greater than equal to 2 (INFO) are
delivered over the attached control interface. LEVEL command can be
used to set the level of messages which will be delivered. It should
be noted that there are many debug messages that do not include any
particulat prefix and are subject to change. They may be used for
debug information, but can usually be ignored by external programs.
In most cases, the external program can skip over the priority field
in the beginning of the event message and then compare the following
text to the event strings from wpa_ctrl.h that the program is
interested in processing.
Following subsections describe the most common event notifications
generated by %wpa_supplicant.
\subsection ctrl_iface_event_CTRL_REQ CTRL-REQ-
WPA_CTRL_REQ: Request information from a user. See
\ref ctrl_iface_interactive "Interactive requests" sections for more
details.
\subsection ctrl_iface_event_CONNECTED CTRL-EVENT-CONNECTED
WPA_EVENT_CONNECTED: Indicate successfully completed authentication
and that the data connection is now enabled.
\subsection ctrl_iface_event_DISCONNECTED CTRL-EVENT-DISCONNECTED
WPA_EVENT_DISCONNECTED: Disconnected, data connection is not available
\subsection ctrl_iface_event_TERMINATING CTRL-EVENT-TERMINATING
WPA_EVENT_TERMINATING: %wpa_supplicant is exiting
\subsection ctrl_iface_event_PASSWORD_CHANGED CTRL-EVENT-PASSWORD-CHANGED
WPA_EVENT_PASSWORD_CHANGED: Password change was completed successfully
\subsection ctrl_iface_event_EAP_NOTIFICATION CTRL-EVENT-EAP-NOTIFICATION
WPA_EVENT_EAP_NOTIFICATION: EAP-Request/Notification received
\subsection ctrl_iface_event_EAP_STARTED CTRL-EVENT-EAP-STARTED
WPA_EVENT_EAP_STARTED: EAP authentication started (EAP-Request/Identity
received)
\subsection ctrl_iface_event_EAP_METHOD CTRL-EVENT-EAP-METHOD
WPA_EVENT_EAP_METHOD: EAP method selected
\subsection ctrl_iface_event_EAP_SUCCESS CTRL-EVENT-EAP-SUCCESS
WPA_EVENT_EAP_SUCCESS: EAP authentication completed successfully
\subsection ctrl_iface_event_EAP_FAILURE CTRL-EVENT-EAP-FAILURE
WPA_EVENT_EAP_FAILURE: EAP authentication failed (EAP-Failure received)
\subsection ctrl_iface_event_SCAN_RESULTS CTRL-EVENT-SCAN-RESULTS
WPA_EVENT_SCAN_RESULTS: New scan results available
\subsection ctrl_iface_event_BSS_ADDED CTRL-EVENT-BSS-ADDED
WPA_EVENT_BSS_ADDED: A new BSS entry was added. The event prefix is
followed by the BSS entry id and BSSID.
\verbatim
CTRL-EVENT-BSS-ADDED 34 00:11:22:33:44:55
\endverbatim
\subsection ctrl_iface_event_BSS_REMOVED CTRL-EVENT-BSS-REMOVED
WPA_EVENT_BSS_REMOVED: A BSS entry was removed. The event prefix is
followed by BSS entry id and BSSID.
\verbatim
CTRL-EVENT-BSS-REMOVED 34 00:11:22:33:44:55
\endverbatim
\subsection ctrl_iface_event_WPS_OVERLAP_DETECTED WPS-OVERLAP-DETECTED
WPS_EVENT_OVERLAP: WPS overlap detected in PBC mode
\subsection ctrl_iface_event_WPS_AP_AVAILABLE_PBC WPS-AP-AVAILABLE-PBC
WPS_EVENT_AP_AVAILABLE_PBC: Available WPS AP with active PBC found in
scan results.
\subsection ctrl_iface_event_WPS_AP_AVAILABLE_PIN WPS-AP-AVAILABLE-PIN
WPS_EVENT_AP_AVAILABLE_PIN: Available WPS AP with recently selected PIN
registrar found in scan results.
\subsection ctrl_iface_event_WPS_AP_AVAILABLE WPS-AP-AVAILABLE
WPS_EVENT_AP_AVAILABLE: Available WPS AP found in scan results
\subsection ctrl_iface_event_WPS_CRED_RECEIVED WPS-CRED-RECEIVED
WPS_EVENT_CRED_RECEIVED: A new credential received
\subsection ctrl_iface_event_WPS_M2D WPS-M2D
WPS_EVENT_M2D: M2D received
\subsection ctrl_iface_event_WPS_FAIL
WPS_EVENT_FAIL: WPS registration failed after M2/M2D
\subsection ctrl_iface_event_WPS_SUCCESS WPS-SUCCESS
WPS_EVENT_SUCCESS: WPS registration completed successfully
\subsection ctrl_iface_event_WPS_TIMEOUT WPS-TIMEOUT
WPS_EVENT_TIMEOUT: WPS enrollment attempt timed out and was terminated
\subsection ctrl_iface_event_WPS_ENROLLEE_SEEN WPS-ENROLLEE-SEEN
WPS_EVENT_ENROLLEE_SEEN: WPS Enrollee was detected (used in AP mode).
The event prefix is followed by MAC addr, UUID-E, pri dev type,
config methods, dev passwd id, request type, [dev name].
\verbatim
WPS-ENROLLEE-SEEN 02:00:00:00:01:00
572cf82f-c957-5653-9b16-b5cfb298abf1 1-0050F204-1 0x80 4 1
[Wireless Client]
\endverbatim
\subsection ctrl_iface_event_WPS_ER_AP_ADD WPS-ER-AP-ADD
WPS_EVENT_ER_AP_ADD: WPS ER discovered an AP
\verbatim
WPS-ER-AP-ADD 87654321-9abc-def0-1234-56789abc0002 02:11:22:33:44:55
pri_dev_type=6-0050F204-1 wps_state=1 |Very friendly name|Company|
Long description of the model|WAP|http://w1.fi/|http://w1.fi/hostapd/
\endverbatim
\subsection ctrl_iface_event_WPS_ER_AP_REMOVE WPS-ER-AP-REMOVE
WPS_EVENT_ER_AP_REMOVE: WPS ER removed an AP entry
\verbatim
WPS-ER-AP-REMOVE 87654321-9abc-def0-1234-56789abc0002
\endverbatim
\subsection ctrl_iface_event_WPS_ER_ENROLLEE_ADD WPS-ER-ENROLLEE-ADD
WPS_EVENT_ER_ENROLLEE_ADD: WPS ER discovered a new Enrollee
\verbatim
WPS-ER-ENROLLEE-ADD 2b7093f1-d6fb-5108-adbb-bea66bb87333
02:66:a0:ee:17:27 M1=1 config_methods=0x14d dev_passwd_id=0
pri_dev_type=1-0050F204-1
|Wireless Client|Company|cmodel|123|12345|
\endverbatim
\subsection ctrl_iface_event_WPS_ER_ENROLLEE_REMOVE WPS-ER-ENROLLEE-REMOVE
WPS_EVENT_ER_ENROLLEE_REMOVE: WPS ER removed an Enrollee entry
\verbatim
WPS-ER-ENROLLEE-REMOVE 2b7093f1-d6fb-5108-adbb-bea66bb87333
02:66:a0:ee:17:27
\endverbatim
\subsection ctrl_iface_event_WPS_PIN_NEEDED WPS-PIN-NEEDED
WPS_EVENT_PIN_NEEDED: PIN is needed to complete provisioning with an
Enrollee. This is followed by information about the Enrollee (UUID,
MAC address, device name, manufacturer, model name, model number,
serial number, primary device type).
\verbatim
WPS-PIN-NEEDED 5a02a5fa-9199-5e7c-bc46-e183d3cb32f7 02:2a:c4:18:5b:f3
[Wireless Client|Company|cmodel|123|12345|1-0050F204-1]
\endverbatim
\subsection ctrl_iface_event_WPS_NEW_AP_SETTINGS WPS-NEW-AP-SETTINGS
WPS_EVENT_NEW_AP_SETTINGS: New AP settings were received
\subsection ctrl_iface_event_WPS_REG_SUCCESS WPS-REG-SUCCESS
WPS_EVENT_REG_SUCCESS: WPS provisioning was completed successfully
(AP/Registrar)
\subsection ctrl_iface_event_WPS_AP_SETUP_LOCKED WPS-AP-SETUP-LOCKED
WPS_EVENT_AP_SETUP_LOCKED: AP changed into setup locked state due to
multiple failed configuration attempts using the AP PIN.
\subsection ctrl_iface_event_AP_STA_CONNECTED AP-STA-CONNECTED
AP_STA_CONNECTED: A station associated with us (AP mode event). The
event prefix is followed by the MAC address of the station.
\verbatim
AP-STA-CONNECTED 02:2a:c4:18:5b:f3
\endverbatim
\subsection ctrl_iface_event_AP_STA_DISCONNECTED AP-STA-DISCONNECTED
AP_STA_DISCONNECTED: A station disassociated (AP mode event)
\verbatim
AP-STA-DISCONNECTED 02:2a:c4:18:5b:f3
\endverbatim
*/ */

4
src/common/wpa_ctrl.h
View file

@ -48,9 +48,9 @@ extern "C" {
#define WPA_EVENT_EAP_FAILURE "CTRL-EVENT-EAP-FAILURE " #define WPA_EVENT_EAP_FAILURE "CTRL-EVENT-EAP-FAILURE "
/** New scan results available */ /** New scan results available */
#define WPA_EVENT_SCAN_RESULTS "CTRL-EVENT-SCAN-RESULTS " #define WPA_EVENT_SCAN_RESULTS "CTRL-EVENT-SCAN-RESULTS "
/** A BSS entry was added (followed by BSS entry id and BSSID) */ /** A new BSS entry was added (followed by BSS entry id and BSSID) */
#define WPA_EVENT_BSS_ADDED "CTRL-EVENT-BSS-ADDED " #define WPA_EVENT_BSS_ADDED "CTRL-EVENT-BSS-ADDED "
/** A BSS entry was added (followed by BSS entry id and BSSID) */ /** A BSS entry was removed (followed by BSS entry id and BSSID) */
#define WPA_EVENT_BSS_REMOVED "CTRL-EVENT-BSS-REMOVED " #define WPA_EVENT_BSS_REMOVED "CTRL-EVENT-BSS-REMOVED "
/** WPS overlap detected in PBC mode */ /** WPS overlap detected in PBC mode */