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