1 /*
2  * WPA Supplicant / UNIX domain socket -based control interface
3  * Copyright (c) 2004-2020, Jouni Malinen <j@w1.fi>
4  *
5  * This software may be distributed under the terms of the BSD license.
6  * See README for more details.
7  */
8 
9 #ifndef CTRL_IFACE_H
10 #define CTRL_IFACE_H
11 
12 #ifdef CONFIG_CTRL_IFACE
13 
14 #ifndef CTRL_IFACE_MAX_LEN
15 #define CTRL_IFACE_MAX_LEN 8192
16 #endif /* CTRL_IFACE_MAX_LEN */
17 
18 /* Shared functions from ctrl_iface.c; to be called by ctrl_iface backends */
19 
20 /**
21  * wpa_supplicant_ctrl_iface_process - Process ctrl_iface command
22  * @wpa_s: Pointer to wpa_supplicant data
23  * @buf: Received command buffer (nul terminated string)
24  * @resp_len: Variable to be set to the response length
25  * Returns: Response (*resp_len bytes) or %NULL on failure
26  *
27  * Control interface backends call this function when receiving a message that
28  * they do not process internally, i.e., anything else than ATTACH, DETACH,
29  * and LEVEL. The return response value is then sent to the external program
30  * that sent the command. Caller is responsible for freeing the buffer after
31  * this. If %NULL is returned, *resp_len can be set to two special values:
32  * 1 = send "FAIL\n" response, 2 = send "OK\n" response. If *resp_len has any
33  * other value, no response is sent.
34  */
35 char * wpa_supplicant_ctrl_iface_process(struct wpa_supplicant *wpa_s,
36 					 char *buf, size_t *resp_len);
37 
38 /**
39  * wpa_supplicant_global_ctrl_iface_process - Process global ctrl_iface command
40  * @global: Pointer to global data from wpa_supplicant_init()
41  * @buf: Received command buffer (nul terminated string)
42  * @resp_len: Variable to be set to the response length
43  * Returns: Response (*resp_len bytes) or %NULL on failure
44  *
45  * Control interface backends call this function when receiving a message from
46  * the global ctrl_iface connection. The return response value is then sent to
47  * the external program that sent the command. Caller is responsible for
48  * freeing the buffer after this. If %NULL is returned, *resp_len can be set to
49  * two special values: 1 = send "FAIL\n" response, 2 = send "OK\n" response. If
50  * *resp_len has any other value, no response is sent.
51  */
52 char * wpa_supplicant_global_ctrl_iface_process(struct wpa_global *global,
53 						char *buf, size_t *resp_len);
54 
55 
56 /* Functions that each ctrl_iface backend must implement */
57 
58 /**
59  * wpa_supplicant_ctrl_iface_init - Initialize control interface
60  * @wpa_s: Pointer to wpa_supplicant data
61  * Returns: Pointer to private data on success, %NULL on failure
62  *
63  * Initialize the control interface and start receiving commands from external
64  * programs.
65  *
66  * Required to be implemented in each control interface backend.
67  */
68 struct ctrl_iface_priv *
69 wpa_supplicant_ctrl_iface_init(struct wpa_supplicant *wpa_s);
70 
71 /**
72  * wpa_supplicant_ctrl_iface_deinit - Deinitialize control interface
73  * @wpa_s: Pointer to wpa_supplicant data
74  * @priv: Pointer to private data from wpa_supplicant_ctrl_iface_init()
75  *
76  * Deinitialize the control interface that was initialized with
77  * wpa_supplicant_ctrl_iface_init() and any data related to the wpa_s instance.
78  * @priv may be %NULL if the control interface has not yet been initialized.
79  *
80  * Required to be implemented in each control interface backend.
81  */
82 void wpa_supplicant_ctrl_iface_deinit(struct wpa_supplicant *wpa_s,
83 				      struct ctrl_iface_priv *priv);
84 
85 /**
86  * wpa_supplicant_ctrl_iface_wait - Wait for ctrl_iface monitor
87  * @priv: Pointer to private data from wpa_supplicant_ctrl_iface_init()
88  *
89  * Wait until the first message from an external program using the control
90  * interface is received. This function can be used to delay normal startup
91  * processing to allow control interface programs to attach with
92  * %wpa_supplicant before normal operations are started.
93  *
94  * Required to be implemented in each control interface backend.
95  */
96 void wpa_supplicant_ctrl_iface_wait(struct ctrl_iface_priv *priv);
97 
98 /**
99  * wpa_supplicant_global_ctrl_iface_init - Initialize global control interface
100  * @global: Pointer to global data from wpa_supplicant_init()
101  * Returns: Pointer to private data on success, %NULL on failure
102  *
103  * Initialize the global control interface and start receiving commands from
104  * external programs.
105  *
106  * Required to be implemented in each control interface backend.
107  */
108 struct ctrl_iface_global_priv *
109 wpa_supplicant_global_ctrl_iface_init(struct wpa_global *global);
110 
111 /**
112  * wpa_supplicant_global_ctrl_iface_deinit - Deinitialize global ctrl interface
113  * @priv: Pointer to private data from wpa_supplicant_global_ctrl_iface_init()
114  *
115  * Deinitialize the global control interface that was initialized with
116  * wpa_supplicant_global_ctrl_iface_init().
117  *
118  * Required to be implemented in each control interface backend.
119  */
120 void wpa_supplicant_global_ctrl_iface_deinit(
121 	struct ctrl_iface_global_priv *priv);
122 
123 void wpas_ctrl_radio_work_flush(struct wpa_supplicant *wpa_s);
124 
125 #else /* CONFIG_CTRL_IFACE */
126 
127 static inline struct ctrl_iface_priv *
128 wpa_supplicant_ctrl_iface_init(struct wpa_supplicant *wpa_s)
129 {
130 	return (void *) -1;
131 }
132 
133 static inline void
134 wpa_supplicant_ctrl_iface_deinit(struct wpa_supplicant *wpa_s,
135 				 struct ctrl_iface_priv *priv)
136 {
137 }
138 
139 static inline void
140 wpa_supplicant_ctrl_iface_send(struct ctrl_iface_priv *priv, int level,
141 			       char *buf, size_t len)
142 {
143 }
144 
145 static inline void
146 wpa_supplicant_ctrl_iface_wait(struct ctrl_iface_priv *priv)
147 {
148 }
149 
150 static inline struct ctrl_iface_global_priv *
151 wpa_supplicant_global_ctrl_iface_init(struct wpa_global *global)
152 {
153 	return (void *) 1;
154 }
155 
156 static inline void
157 wpa_supplicant_global_ctrl_iface_deinit(struct ctrl_iface_global_priv *priv)
158 {
159 }
160 
161 static inline void wpas_ctrl_radio_work_flush(struct wpa_supplicant *wpa_s)
162 {
163 }
164 
165 #endif /* CONFIG_CTRL_IFACE */
166 
167 #endif /* CTRL_IFACE_H */
168