X-Git-Url: http://www.project-moonshot.org/gitweb/?a=blobdiff_plain;f=libeap%2Fdoc%2Fctrl_iface.doxygen;h=7dccdc797ef334b0d6fd1c00a2c79d8f4b3de79d;hb=d1dd9aae6741e74f20bfc35e1db598652680279d;hp=85847f6b1873ce3d3746ef0f5b8fe23018be5755;hpb=3d6aee344d6a992d500869b336d68b09fc07cba3;p=mech_eap.git diff --git a/libeap/doc/ctrl_iface.doxygen b/libeap/doc/ctrl_iface.doxygen index 85847f6..7dccdc7 100644 --- a/libeap/doc/ctrl_iface.doxygen +++ b/libeap/doc/ctrl_iface.doxygen @@ -1,47 +1,47 @@ /** -\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 @@ -49,20 +49,20 @@ to use only one connection for both purposes and wpa_gui demonstrates 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 @@ -217,13 +217,13 @@ Start pre-authentication with the given BSSID. \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 @@ -233,12 +233,12 @@ Change 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 @@ -557,13 +557,13 @@ Device Address>" to indicate the entry following the specified peer Enable/disable extended listen timing. Without parameters, this command disables extended listen timing. When enabling the feature, -two parameters are used: availibility period and availability interval +two parameters are used: availability period and availability interval (both in milliseconds and with range of 1-65535). \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 @@ -583,7 +583,7 @@ CTRL-REQ--- CTRL-RSP--- \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 @@ -598,7 +598,7 @@ CTRL-RSP-PASSWORD-1-secret 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 @@ -645,8 +645,8 @@ OPEN SHARED LEAP 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 @@ -662,14 +662,14 @@ eth0 \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: @@ -694,11 +694,11 @@ 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 +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- @@ -717,7 +717,7 @@ WPA_EVENT_DISCONNECTED: Disconnected, data connection is not available \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 @@ -1012,8 +1012,8 @@ P2P-PROV-DISC-PBC-RESP 02:40:61:c2:f3:b7 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 @@ -1023,7 +1023,8 @@ 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