| /** |
| \page hostapd_ctrl_iface_page hostapd control interface |
| |
| hostapd implements a control interface that can be used by |
| external programs to control the operations of the hostapd |
| 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 |
| 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++. hostapd_cli.c |
| is an example program using this library. |
| |
| There are multiple mechanisms for inter-process communication. For |
| example, Linux version of hostapd is using UNIX domain sockets for the |
| control interface. The use of the functions defined in 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 hostapd should link in 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(). |
| |
| hostapd 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 |
| hostapd. These can be executed using wpa_ctrl_request(). |
| Unsolicited event messages are sent by hostapd 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 |
| 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, |
| for processing these messages. Often it is easier to open two |
| control interface connections by calling 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 |
| 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 |
| unsolicited event messages, it should be first detached by calling |
| wpa_ctrl_detach(). |
| |
| |
| \section ctrl_iface_cmds Control interface commands |
| |
| Following commands can be used with wpa_ctrl_request(): |
| |
| \subsection ctrl_iface_PING PING |
| |
| This command can be used to test whether hostapd is replying |
| to the control interface commands. The expected reply is \c PONG if the |
| connection is open and hostapd is processing commands. |
| |
| */ |