1/**
2\page hostapd_ctrl_iface_page hostapd control interface
3
4hostapd implements a control interface that can be used by
5external programs to control the operations of the hostapd
6daemon and to get status information and event notifications. There is
7a small C library, in a form of a single C file, \ref wpa_ctrl.c, that
8provides helper functions to facilitate the use of the control
9interface. External programs can link this file into them and then use
10the library functions documented in \ref wpa_ctrl.h to interact with
11wpa_supplicant. This library can also be used with C++. \ref hostapd_cli.c
12is an example program using this library.
13
14There are multiple mechanisms for inter-process communication. For
15example, Linux version of hostapd is using UNIX domain sockets for the
16control interface. The use of the functions defined in \ref wpa_ctrl.h can
17be used to hide the details of the used IPC from external programs.
18
19
20\section using_ctrl_iface Using the control interface
21
22External programs, e.g., a GUI or a configuration utility, that need to
23communicate with hostapd should link in \ref wpa_ctrl.c. This
24allows them to use helper functions to open connection to the control
25interface with \ref wpa_ctrl_open() and to send commands with
26\ref wpa_ctrl_request().
27
28hostapd uses the control interface for two types of communication:
29commands and unsolicited event messages. Commands are a pair of
30messages, a request from the external program and a response from
31hostapd. These can be executed using \ref wpa_ctrl_request().
32Unsolicited event messages are sent by hostapd to the control
33interface connection without specific request from the external program
34for receiving each message. However, the external program needs to
35attach to the control interface with \ref wpa_ctrl_attach() to receive these
36unsolicited messages.
37
38If the control interface connection is used both for commands and
39unsolicited event messages, there is potential for receiving an
40unsolicited message between the command request and response.
41\ref wpa_ctrl_request() caller will need to supply a callback, msg_cb,
42for processing these messages. Often it is easier to open two
43control interface connections by calling \ref wpa_ctrl_open() twice and
44then use one of the connections for commands and the other one for
45unsolicited messages. This way command request/response pairs will
46not be broken by unsolicited messages. \ref wpa_cli.c is an example of how
47to use only one connection for both purposes and wpa_gui demonstrates
48how to use two separate connections.
49
50Once the control interface connection is not needed anymore, it should
51be closed by calling \ref wpa_ctrl_close(). If the connection was used for
52unsolicited event messages, it should be first detached by calling
53\ref wpa_ctrl_detach().
54
55
56\section ctrl_iface_cmds Control interface commands
57
58Following commands can be used with \ref wpa_ctrl_request():
59
60\subsection ctrl_iface_PING PING
61
62This command can be used to test whether hostapd is replying
63to the control interface commands. The expected reply is \c PONG if the
64connection is open and hostapd is processing commands.
65
66*/
67