/**
-\page ctrl_iface_page %wpa_supplicant control interface
+\page ctrl_iface_page wpa_supplicant control interface
-%wpa_supplicant implements a control interface that can be used by
-external programs to control the operations of the %wpa_supplicant
+wpa_supplicant implements a control interface that can be used by
+external programs to control the operations of the wpa_supplicant
daemon and to get status information and event notifications. There is
-a small C library, in a form of a single C file, wpa_ctrl.c, that
+a small C library, in a form of a single C file, \ref wpa_ctrl.c, that
provides helper functions to facilitate the use of the control
interface. External programs can link this file into them and then use
-the library functions documented in wpa_ctrl.h to interact with
-%wpa_supplicant. This library can also be used with C++. wpa_cli.c and
+the library functions documented in \ref wpa_ctrl.h to interact with
+wpa_supplicant. This library can also be used with C++. \ref wpa_cli.c and
wpa_gui are example programs using this library.
There are multiple mechanisms for inter-process communication. For
-example, Linux version of %wpa_supplicant is using UNIX domain sockets
+example, Linux version of wpa_supplicant is using UNIX domain sockets
for the control interface and Windows version UDP sockets. The use of
-the functions defined in wpa_ctrl.h can be used to hide the details of
+the functions defined in \ref wpa_ctrl.h can be used to hide the details of
the used IPC from external programs.
\section using_ctrl_iface Using the control interface
External programs, e.g., a GUI or a configuration utility, that need to
-communicate with %wpa_supplicant should link in wpa_ctrl.c. This
+communicate with wpa_supplicant should link in \ref wpa_ctrl.c. This
allows them to use helper functions to open connection to the control
-interface with wpa_ctrl_open() and to send commands with
-wpa_ctrl_request().
+interface with \ref wpa_ctrl_open() and to send commands with
+\ref wpa_ctrl_request().
-%wpa_supplicant uses the control interface for two types of communication:
+wpa_supplicant uses the control interface for two types of communication:
commands and unsolicited event messages. Commands are a pair of
messages, a request from the external program and a response from
-%wpa_supplicant. These can be executed using wpa_ctrl_request().
-Unsolicited event messages are sent by %wpa_supplicant to the control
+wpa_supplicant. These can be executed using \ref wpa_ctrl_request().
+Unsolicited event messages are sent by wpa_supplicant to the control
interface connection without specific request from the external program
for receiving each message. However, the external program needs to
-attach to the control interface with wpa_ctrl_attach() to receive these
+attach to the control interface with \ref wpa_ctrl_attach() to receive these
unsolicited messages.
If the control interface connection is used both for commands and
unsolicited event messages, there is potential for receiving an
unsolicited message between the command request and response.
-wpa_ctrl_request() caller will need to supply a callback, msg_cb,
+\ref wpa_ctrl_request() caller will need to supply a callback, msg_cb,
for processing these messages. Often it is easier to open two
-control interface connections by calling wpa_ctrl_open() twice and
+control interface connections by calling \ref wpa_ctrl_open() twice and
then use one of the connections for commands and the other one for
unsolicited messages. This way command request/response pairs will
not be broken by unsolicited messages. wpa_cli is an example of how
how to use two separate connections.
Once the control interface connection is not needed anymore, it should
-be closed by calling wpa_ctrl_close(). If the connection was used for
+be closed by calling \ref wpa_ctrl_close(). If the connection was used for
unsolicited event messages, it should be first detached by calling
-wpa_ctrl_detach().
+\ref wpa_ctrl_detach().
\section ctrl_iface_cmds Control interface commands
-Following commands can be used with wpa_ctrl_request():
+Following commands can be used with \ref wpa_ctrl_request():
\subsection ctrl_iface_PING PING
-This command can be used to test whether %wpa_supplicant is replying
+This command can be used to test whether wpa_supplicant is replying
to the control interface commands. The expected reply is \c PONG if the
-connection is open and %wpa_supplicant is processing commands.
+connection is open and wpa_supplicant is processing commands.
\subsection ctrl_iface_MIB MIB
\subsection ctrl_iface_ATTACH ATTACH
Attach the connection as a monitor for unsolicited events. This can
-be done with wpa_ctrl_attach().
+be done with \ref wpa_ctrl_attach().
\subsection ctrl_iface_DETACH DETACH
Detach the connection as a monitor for unsolicited events. This can
-be done with wpa_ctrl_detach().
+be done with \ref wpa_ctrl_detach().
\subsection ctrl_iface_LEVEL LEVEL <debug level>
\subsection ctrl_iface_RECONFIGURE RECONFIGURE
-Force %wpa_supplicant to re-read its configuration data.
+Force wpa_supplicant to re-read its configuration data.
\subsection ctrl_iface_TERMINATE TERMINATE
-Terminate %wpa_supplicant process.
+Terminate wpa_supplicant process.
\subsection ctrl_iface_BSSID BSSID <network id> <BSSID>
\section ctrl_iface_interactive Interactive requests
-If %wpa_supplicant needs additional information during authentication
+If wpa_supplicant needs additional information during authentication
(e.g., password), it will use a specific prefix, \c CTRL-REQ-
(\a WPA_CTRL_REQ macro) in an unsolicited event message. An external
program, e.g., a GUI, can provide such information by using
CTRL-RSP-<field name>-<network id>-<value>
\endverbatim
-For example, request from %wpa_supplicant:
+For example, request from wpa_supplicant:
\verbatim
CTRL-REQ-PASSWORD-1-Password needed for SSID test-network
\endverbatim
Get list of supported functionality (eap, pairwise, group,
proto). Supported functionality is shown as space separate lists of
-values used in the same format as in %wpa_supplicant configuration.
+values used in the same format as in wpa_supplicant configuration.
If optional argument, 'strict', is added, only the values that the
driver claims to explicitly support are included. Without this, all
available capabilities are included if the driver does not provide
Change ap_scan value:
0 = no scanning,
-1 = %wpa_supplicant requests scans and uses scan results to select the AP,
-2 = %wpa_supplicant does not use scanning and just requests driver to
+1 = wpa_supplicant requests scans and uses scan results to select the AP,
+2 = wpa_supplicant does not use scanning and just requests driver to
associate and take care of AP selection
\section ctrl_iface_events Control interface events
-%wpa_supplicant generates number messages based on events like
+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().
+interface with \ref 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
+a fixed prefix text as defined in \ref 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:
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
+text to the event strings from \ref wpa_ctrl.h that the program is
interested in processing.
Following subsections describe the most common event notifications
-generated by %wpa_supplicant.
+generated by wpa_supplicant.
\subsection ctrl_iface_event_CTRL_REQ CTRL-REQ-
\subsection ctrl_iface_event_TERMINATING CTRL-EVENT-TERMINATING
-WPA_EVENT_TERMINATING: %wpa_supplicant is exiting
+WPA_EVENT_TERMINATING: wpa_supplicant is exiting
\subsection ctrl_iface_event_PASSWORD_CHANGED CTRL-EVENT-PASSWORD-CHANGED
P2P-SERV-DISC-REQ: Indicate reception of a P2P service discovery
request. The following parameters are included after the event prefix:
-frequency in MHz, source address, dialog token, Service Query TLV(s) as
-hexdump.
+frequency in MHz, source address, dialog token, Service Update
+Indicator, Service Query TLV(s) as hexdump.
\verbatim
P2P-SERV-DISC-REQ 2412 02:40:61:c2:f3:b7 0 0 02000001
P2P-SERV-DISC-RESP: Indicate reception of a P2P service discovery
response. The following parameters are included after the event prefix:
-source address, dialog token, Service Responce TLV(s) as hexdump.
+source address, Service Update Indicator, Service Response TLV(s) as
+hexdump.
\verbatim
P2P-SERV-DISC-RESP 02:40:61:c2:f3:b7 0 0300000101
projects / mech_eap.git / blobdiff