You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

wpa_ctrl.h 7.2 KiB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187
  1. /*
  2. * Unmodifed version of src/common/wpa_ctrl.h from wpa_supplicant.
  3. *
  4. * wpa_supplicant/hostapd control interface library
  5. * Copyright (c) 2004-2006, Jouni Malinen <j@w1.fi>
  6. *
  7. * This program is free software; you can redistribute it and/or modify
  8. * it under the terms of the GNU General Public License version 2 as
  9. * published by the Free Software Foundation.
  10. *
  11. * Alternatively, this software may be distributed under the terms of BSD
  12. * license.
  13. */
  14. #ifndef WPA_CTRL_H
  15. #define WPA_CTRL_H
  16. #ifdef __cplusplus
  17. extern "C" {
  18. #endif
  19. /* wpa_supplicant control interface - fixed message prefixes */
  20. /** Interactive request for identity/password/pin */
  21. #define WPA_CTRL_REQ "CTRL-REQ-"
  22. /** Response to identity/password/pin request */
  23. #define WPA_CTRL_RSP "CTRL-RSP-"
  24. /* Event messages with fixed prefix */
  25. /** Authentication completed successfully and data connection enabled */
  26. #define WPA_EVENT_CONNECTED "CTRL-EVENT-CONNECTED "
  27. /** Disconnected, data connection is not available */
  28. #define WPA_EVENT_DISCONNECTED "CTRL-EVENT-DISCONNECTED "
  29. /** wpa_supplicant is exiting */
  30. #define WPA_EVENT_TERMINATING "CTRL-EVENT-TERMINATING "
  31. /** Password change was completed successfully */
  32. #define WPA_EVENT_PASSWORD_CHANGED "CTRL-EVENT-PASSWORD-CHANGED "
  33. /** EAP-Request/Notification received */
  34. #define WPA_EVENT_EAP_NOTIFICATION "CTRL-EVENT-EAP-NOTIFICATION "
  35. /** EAP authentication started (EAP-Request/Identity received) */
  36. #define WPA_EVENT_EAP_STARTED "CTRL-EVENT-EAP-STARTED "
  37. /** EAP method selected */
  38. #define WPA_EVENT_EAP_METHOD "CTRL-EVENT-EAP-METHOD "
  39. /** EAP authentication completed successfully */
  40. #define WPA_EVENT_EAP_SUCCESS "CTRL-EVENT-EAP-SUCCESS "
  41. /** EAP authentication failed (EAP-Failure received) */
  42. #define WPA_EVENT_EAP_FAILURE "CTRL-EVENT-EAP-FAILURE "
  43. /** New scan results available */
  44. #define WPA_EVENT_SCAN_RESULTS "CTRL-EVENT-SCAN-RESULTS "
  45. /* wpa_supplicant/hostapd control interface access */
  46. /**
  47. * wpa_ctrl_open - Open a control interface to wpa_supplicant/hostapd
  48. * @ctrl_path: Path for UNIX domain sockets; ignored if UDP sockets are used.
  49. * Returns: Pointer to abstract control interface data or %NULL on failure
  50. *
  51. * This function is used to open a control interface to wpa_supplicant/hostapd.
  52. * ctrl_path is usually /var/run/wpa_supplicant or /var/run/hostapd. This path
  53. * is configured in wpa_supplicant/hostapd and other programs using the control
  54. * interface need to use matching path configuration.
  55. */
  56. struct wpa_ctrl * wpa_ctrl_open(const char *ctrl_path);
  57. /**
  58. * wpa_ctrl_close - Close a control interface to wpa_supplicant/hostapd
  59. * @ctrl: Control interface data from wpa_ctrl_open()
  60. *
  61. * This function is used to close a control interface.
  62. */
  63. void wpa_ctrl_close(struct wpa_ctrl *ctrl);
  64. /**
  65. * wpa_ctrl_request - Send a command to wpa_supplicant/hostapd
  66. * @ctrl: Control interface data from wpa_ctrl_open()
  67. * @cmd: Command; usually, ASCII text, e.g., "PING"
  68. * @cmd_len: Length of the cmd in bytes
  69. * @reply: Buffer for the response
  70. * @reply_len: Reply buffer length
  71. * @msg_cb: Callback function for unsolicited messages or %NULL if not used
  72. * Returns: 0 on success, -1 on error (send or receive failed), -2 on timeout
  73. *
  74. * This function is used to send commands to wpa_supplicant/hostapd. Received
  75. * response will be written to reply and reply_len is set to the actual length
  76. * of the reply. This function will block for up to two seconds while waiting
  77. * for the reply. If unsolicited messages are received, the blocking time may
  78. * be longer.
  79. *
  80. * msg_cb can be used to register a callback function that will be called for
  81. * unsolicited messages received while waiting for the command response. These
  82. * messages may be received if wpa_ctrl_request() is called at the same time as
  83. * wpa_supplicant/hostapd is sending such a message. This can happen only if
  84. * the program has used wpa_ctrl_attach() to register itself as a monitor for
  85. * event messages. Alternatively to msg_cb, programs can register two control
  86. * interface connections and use one of them for commands and the other one for
  87. * receiving event messages, in other words, call wpa_ctrl_attach() only for
  88. * the control interface connection that will be used for event messages.
  89. */
  90. int wpa_ctrl_request(struct wpa_ctrl *ctrl, const char *cmd, size_t cmd_len,
  91. char *reply, size_t *reply_len,
  92. void (*msg_cb)(char *msg, size_t len));
  93. /**
  94. * wpa_ctrl_attach - Register as an event monitor for the control interface
  95. * @ctrl: Control interface data from wpa_ctrl_open()
  96. * Returns: 0 on success, -1 on failure, -2 on timeout
  97. *
  98. * This function registers the control interface connection as a monitor for
  99. * wpa_supplicant/hostapd events. After a success wpa_ctrl_attach() call, the
  100. * control interface connection starts receiving event messages that can be
  101. * read with wpa_ctrl_recv().
  102. */
  103. int wpa_ctrl_attach(struct wpa_ctrl *ctrl);
  104. /**
  105. * wpa_ctrl_detach - Unregister event monitor from the control interface
  106. * @ctrl: Control interface data from wpa_ctrl_open()
  107. * Returns: 0 on success, -1 on failure, -2 on timeout
  108. *
  109. * This function unregisters the control interface connection as a monitor for
  110. * wpa_supplicant/hostapd events, i.e., cancels the registration done with
  111. * wpa_ctrl_attach().
  112. */
  113. int wpa_ctrl_detach(struct wpa_ctrl *ctrl);
  114. /**
  115. * wpa_ctrl_recv - Receive a pending control interface message
  116. * @ctrl: Control interface data from wpa_ctrl_open()
  117. * @reply: Buffer for the message data
  118. * @reply_len: Length of the reply buffer
  119. * Returns: 0 on success, -1 on failure
  120. *
  121. * This function will receive a pending control interface message. This
  122. * function will block if no messages are available. The received response will
  123. * be written to reply and reply_len is set to the actual length of the reply.
  124. * wpa_ctrl_recv() is only used for event messages, i.e., wpa_ctrl_attach()
  125. * must have been used to register the control interface as an event monitor.
  126. */
  127. int wpa_ctrl_recv(struct wpa_ctrl *ctrl, char *reply, size_t *reply_len);
  128. /**
  129. * wpa_ctrl_pending - Check whether there are pending event messages
  130. * @ctrl: Control interface data from wpa_ctrl_open()
  131. * Returns: 1 if there are pending messages, 0 if no, or -1 on error
  132. *
  133. * This function will check whether there are any pending control interface
  134. * message available to be received with wpa_ctrl_recv(). wpa_ctrl_pending() is
  135. * only used for event messages, i.e., wpa_ctrl_attach() must have been used to
  136. * register the control interface as an event monitor.
  137. */
  138. int wpa_ctrl_pending(struct wpa_ctrl *ctrl);
  139. /**
  140. * wpa_ctrl_get_fd - Get file descriptor used by the control interface
  141. * @ctrl: Control interface data from wpa_ctrl_open()
  142. * Returns: File descriptor used for the connection
  143. *
  144. * This function can be used to get the file descriptor that is used for the
  145. * control interface connection. The returned value can be used, e.g., with
  146. * select() while waiting for multiple events.
  147. *
  148. * The returned file descriptor must not be used directly for sending or
  149. * receiving packets; instead, the library functions wpa_ctrl_request() and
  150. * wpa_ctrl_recv() must be used for this.
  151. */
  152. int wpa_ctrl_get_fd(struct wpa_ctrl *ctrl);
  153. #ifdef CONFIG_CTRL_IFACE_UDP
  154. #define WPA_CTRL_IFACE_PORT 9877
  155. #define WPA_GLOBAL_CTRL_IFACE_PORT 9878
  156. #endif /* CONFIG_CTRL_IFACE_UDP */
  157. #ifdef __cplusplus
  158. }
  159. #endif
  160. #endif /* WPA_CTRL_H */