libeap/doc/hostapd_ctrl_iface.doxygen

   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
   7 a small C library, in a form of a single C file, \ref wpa_ctrl.c, that
   8 provides helper functions to facilitate the use of the control
   9 interface. External programs can link this file into them and then use
  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
  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
  16 control interface. The use of the functions defined in \ref wpa_ctrl.h can
  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
  23 communicate with hostapd should link in \ref wpa_ctrl.c. This
  24 allows them to use helper functions to open connection to the control
  25 interface with \ref wpa_ctrl_open() and to send commands with
  26 \ref wpa_ctrl_request().
  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
  31 hostapd. These can be executed using \ref wpa_ctrl_request().
  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
  35 attach to the control interface with \ref wpa_ctrl_attach() to receive these
  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.
  41 \ref wpa_ctrl_request() caller will need to supply a callback, msg_cb,
  42 for processing these messages. Often it is easier to open two
  43 control interface connections by calling \ref wpa_ctrl_open() twice and
  44 then use one of the connections for commands and the other one for
  45 unsolicited messages. This way command request/response pairs will
  46 not be broken by unsolicited messages. \ref wpa_cli.c is an example of how
  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
  51 be closed by calling \ref wpa_ctrl_close(). If the connection was used for
  52 unsolicited 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
  58 Following commands can be used with \ref wpa_ctrl_request():
  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 */