66 lines
3 KiB
Text
66 lines
3 KiB
Text
/**
|
|
\page ctrl_iface_page 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.
|
|
|
|
*/
|