wpa_ctrl.h File Reference

wpa_supplicant/hostapd control interface library More...

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Defines
#define	WPA_CTRL_REQ   "CTRL-REQ-"
#define	WPA_CTRL_RSP   "CTRL-RSP-"
#define	WPA_EVENT_CONNECTED   "CTRL-EVENT-CONNECTED "
#define	WPA_EVENT_DISCONNECTED   "CTRL-EVENT-DISCONNECTED "
#define	WPA_EVENT_TERMINATING   "CTRL-EVENT-TERMINATING "
#define	WPA_EVENT_PASSWORD_CHANGED   "CTRL-EVENT-PASSWORD-CHANGED "
#define	WPA_EVENT_EAP_NOTIFICATION   "CTRL-EVENT-EAP-NOTIFICATION "
#define	WPA_EVENT_EAP_STARTED   "CTRL-EVENT-EAP-STARTED "
#define	WPA_EVENT_EAP_METHOD   "CTRL-EVENT-EAP-METHOD "
#define	WPA_EVENT_EAP_SUCCESS   "CTRL-EVENT-EAP-SUCCESS "
#define	WPA_EVENT_EAP_FAILURE   "CTRL-EVENT-EAP-FAILURE "
Functions
wpa_ctrl *	wpa_ctrl_open (const char *ctrl_path)
	Open a control interface to wpa_supplicant/hostapd.
void	wpa_ctrl_close (struct wpa_ctrl *ctrl)
	Close a control interface to wpa_supplicant/hostapd.
int	wpa_ctrl_request (struct wpa_ctrl *ctrl, const char *cmd, size_t cmd_len, char *reply, size_t *reply_len, void(*msg_cb)(char *msg, size_t len))
	Send a command to wpa_supplicant/hostapd.
int	wpa_ctrl_attach (struct wpa_ctrl *ctrl)
	Register as an event monitor for the control interface.
int	wpa_ctrl_detach (struct wpa_ctrl *ctrl)
	Unregister event monitor from the control interface.
int	wpa_ctrl_recv (struct wpa_ctrl *ctrl, char *reply, size_t *reply_len)
	Receive a pending control interface message.
int	wpa_ctrl_pending (struct wpa_ctrl *ctrl)
	Check whether there are pending event messages.
int	wpa_ctrl_get_fd (struct wpa_ctrl *ctrl)
	Get file descriptor used by the control interface.

---

Detailed Description

wpa_supplicant/hostapd control interface library

Copyright

Copyright (c) 2004-2006, Jouni Malinen <[email protected]>

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License version 2 as published by the Free Software Foundation.

Alternatively, this software may be distributed under the terms of BSD license.

See README and COPYING for more details.

Definition in file wpa_ctrl.h.

---

Define Documentation

#define WPA_CTRL_REQ   "CTRL-REQ-"

Interactive request for identity/password/pin Definition at line 26 of file wpa_ctrl.h.

#define WPA_CTRL_RSP   "CTRL-RSP-"

Response to identity/password/pin request Definition at line 29 of file wpa_ctrl.h.

#define WPA_EVENT_CONNECTED   "CTRL-EVENT-CONNECTED "

Authentication completed successfully and data connection enabled Definition at line 33 of file wpa_ctrl.h.

#define WPA_EVENT_DISCONNECTED   "CTRL-EVENT-DISCONNECTED "

Disconnected, data connection is not available Definition at line 35 of file wpa_ctrl.h.

#define WPA_EVENT_EAP_FAILURE   "CTRL-EVENT-EAP-FAILURE "

EAP authentication failed (EAP-Failure received) Definition at line 49 of file wpa_ctrl.h.

#define WPA_EVENT_EAP_METHOD   "CTRL-EVENT-EAP-METHOD "

EAP method selected Definition at line 45 of file wpa_ctrl.h.

#define WPA_EVENT_EAP_NOTIFICATION   "CTRL-EVENT-EAP-NOTIFICATION "

EAP-Request/Notification received Definition at line 41 of file wpa_ctrl.h.

#define WPA_EVENT_EAP_STARTED   "CTRL-EVENT-EAP-STARTED "

EAP authentication started (EAP-Request/Identity received) Definition at line 43 of file wpa_ctrl.h.

#define WPA_EVENT_EAP_SUCCESS   "CTRL-EVENT-EAP-SUCCESS "

EAP authentication completed successfully Definition at line 47 of file wpa_ctrl.h.

#define WPA_EVENT_PASSWORD_CHANGED   "CTRL-EVENT-PASSWORD-CHANGED "

Password change was completed successfully Definition at line 39 of file wpa_ctrl.h.

#define WPA_EVENT_TERMINATING   "CTRL-EVENT-TERMINATING "

wpa_supplicant is exiting Definition at line 37 of file wpa_ctrl.h.

---

Function Documentation

int wpa_ctrl_attach (  struct wpa_ctrl *  ctrl  )

Register as an event monitor for the control interface. Parameters: ctrl  Control interface data from wpa_ctrl_open() Returns: 0 on success, -1 on failure, -2 on timeout This function registers the control interface connection as a monitor for wpa_supplicant/hostapd events. After a success wpa_ctrl_attach() call, the control interface connection starts receiving event messages that can be read with wpa_ctrl_recv().

void wpa_ctrl_close (  struct wpa_ctrl *  ctrl  )

Close a control interface to wpa_supplicant/hostapd. Parameters: ctrl  Control interface data from wpa_ctrl_open() This function is used to close a control interface.

int wpa_ctrl_detach (  struct wpa_ctrl *  ctrl  )

Unregister event monitor from the control interface. Parameters: ctrl  Control interface data from wpa_ctrl_open() Returns: 0 on success, -1 on failure, -2 on timeout This function unregisters the control interface connection as a monitor for wpa_supplicant/hostapd events, i.e., cancels the registration done with wpa_ctrl_attach().

int wpa_ctrl_get_fd (  struct wpa_ctrl *  ctrl  )

Get file descriptor used by the control interface. Parameters: ctrl  Control interface data from wpa_ctrl_open() Returns: File descriptor used for the connection This function can be used to get the file descriptor that is used for the control interface connection. The returned value can be used, e.g., with select() while waiting for multiple events. The returned file descriptor must not be used directly for sending or receiving packets; instead, the library functions wpa_ctrl_request() and wpa_ctrl_recv() must be used for this.

struct wpa_ctrl* wpa_ctrl_open (  const char *  ctrl_path  )

Open a control interface to wpa_supplicant/hostapd. Parameters: ctrl_path  Path for UNIX domain sockets; ignored if UDP sockets are used. Returns: Pointer to abstract control interface data or NULL on failure This function is used to open a control interface to wpa_supplicant/hostapd. ctrl_path is usually /var/run/wpa_supplicant or /var/run/hostapd. This path is configured in wpa_supplicant/hostapd and other programs using the control interface need to use matching path configuration.

int wpa_ctrl_pending (  struct wpa_ctrl *  ctrl  )

Check whether there are pending event messages. Parameters: ctrl  Control interface data from wpa_ctrl_open() Returns: 1 if there are pending messages, 0 if no, or -1 on error This function will check whether there are any pending control interface message available to be received with wpa_ctrl_recv(). wpa_ctrl_pending() is only used for event messages, i.e., wpa_ctrl_attach() must have been used to register the control interface as an event monitor.

int wpa_ctrl_recv (  struct wpa_ctrl *  ctrl, char *  reply, size_t *  reply_len )

Receive a pending control interface message. Parameters: ctrl  Control interface data from wpa_ctrl_open() reply  Buffer for the message data reply_len  Length of the reply buffer Returns: 0 on success, -1 on failure This function will receive a pending control interface message. This function will block if no messages are available. The received response will be written to reply and reply_len is set to the actual length of the reply. wpa_ctrl_recv() is only used for event messages, i.e., wpa_ctrl_attach() must have been used to register the control interface as an event monitor.

int wpa_ctrl_request (  struct wpa_ctrl *  ctrl, const char *  cmd, size_t  cmd_len, char *  reply, size_t *  reply_len, void(*)(char *msg, size_t len)  msg_cb )

Send a command to wpa_supplicant/hostapd. Parameters: ctrl  Control interface data from wpa_ctrl_open() cmd  Command; usually, ASCII text, e.g., "PING" cmd_len  Length of the cmd in bytes reply  Buffer for the response reply_len  Reply buffer length msg_cb  Callback function for unsolicited messages or NULL if not used Returns: 0 on success, -1 on error (send or receive failed), -2 on timeout This function is used to send commands to wpa_supplicant/hostapd. Received response will be written to reply and reply_len is set to the actual length of the reply. This function will block for up to two seconds while waiting for the reply. If unsolicited messages are received, the blocking time may be longer. msg_cb can be used to register a callback function that will be called for unsolicited messages received while waiting for the command response. These messages may be received if wpa_ctrl_request() is called at the same time as wpa_supplicant/hostapd is sending such a message. This can happen only if the program has used wpa_ctrl_attach() to register itself as a monitor for event messages. Alternatively to msg_cb, programs can register two control interface connections and use one of them for commands and the other one for receiving event messages, in other words, call wpa_ctrl_attach() only for the control interface connection that will be used for event messages.

---