Update ChangeLog files to match the current implementation

[thirdparty/hostap.git] / doc / hostapd_ctrl_iface.doxygen

/**
\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.

*/