pa_wifi.h

1 // -------------------------------------------------------------------------------------------------
2 /**
3  * WiFi Client Platform Adapter
4  *
5  * Copyright (C) Sierra Wireless Inc.
6  *
7  */
8 // -------------------------------------------------------------------------------------------------
9 #ifndef PA_WIFI_H
10 #define PA_WIFI_H
11 
12 #include "legato.h"
13 #include "interfaces.h"
14 
15 //--------------------------------------------------------------------------------------------------
16 /**
17  * AccessPoint structure.
18  */
19 //--------------------------------------------------------------------------------------------------
20 typedef struct
21 {
22  int16_t signalStrength; ///< 0xffff means value was not found.
23  uint8_t ssidLength; ///< The number of bytes in the ssidBytes.
24  uint8_t ssidBytes[LE_WIFIDEFS_MAX_SSID_BYTES]; ///< Contains ssidLength number of bytes.
25  char bssid[LE_WIFIDEFS_MAX_BSSID_BYTES]; ///< Contains the bssid.
27 
28 //--------------------------------------------------------------------------------------------------
29 /**
30  * Event handler for PA WiFi access point changes.
31  *
32  * Handles the PA WiFi events.
33  */
34 //--------------------------------------------------------------------------------------------------
35 typedef void (*pa_wifiClient_NewEventHandlerFunc_t)
36 (
38  ///< [IN]
39  ///< WiFi event to process
40  void *contextPtr
41  ///< [IN]
42  ///< Associated WiFi event context
43 );
44 
45 //--------------------------------------------------------------------------------------------------
46 /**
47  * Add handler function for PA EVENT 'le_wifiClient_Event_t'
48  *
49  * This event provides information on PA WiFi Client event changes.
50  */
51 //--------------------------------------------------------------------------------------------------
52 LE_SHARED le_result_t pa_wifiClient_AddEventHandler
53 (
54  pa_wifiClient_NewEventHandlerFunc_t handlerPtr,
55  ///< [IN]
56  ///< Event handler function pointer.
57  void *contextPtr
58  ///< [IN]
59  ///< Associated event context.
60 );
61 
62 //--------------------------------------------------------------------------------------------------
63 /**
64  * This function must be called to initialize the PA WiFi Module.
65  *
66  * @return LE_OK The function succeeded.
67  */
68 //--------------------------------------------------------------------------------------------------
69 LE_SHARED le_result_t pa_wifiClient_Init
70 (
71  void
72 );
73 
74 //--------------------------------------------------------------------------------------------------
75 /**
76  * This function must be called to release the PA WiFi Module.
77  *
78  * @return LE_OK The function succeeded.
79  */
80 //--------------------------------------------------------------------------------------------------
81 LE_SHARED le_result_t pa_wifiClient_Release
82 (
83  void
84 );
85 
86 //--------------------------------------------------------------------------------------------------
87 /**
88  * This function will start a scan and returns when it is done.
89  * It should NOT return until the scan is done.
90  * Results are read via pa_wifiClient_GetScanResult.
91  * When the reading is done pa_wifiClient_ScanDone MUST be called.
92  *
93  * @return LE_FAULT The function failed.
94  * @return LE_BUSY The function is already ongoing.
95  * @return LE_OK The function succeeded.
96  */
97 //--------------------------------------------------------------------------------------------------
98 LE_SHARED le_result_t pa_wifiClient_Scan
99 (
100  void
101 );
102 
103 //--------------------------------------------------------------------------------------------------
104 /**
105  * This function is used to find out if a scan is currently running.
106  *
107  * @return TRUE Scan is running.
108  * @return FALSE Scan is not running
109  */
110 //--------------------------------------------------------------------------------------------------
111 LE_SHARED bool pa_wifiClient_IsScanRunning
112 (
113  void
114 );
115 
116 //--------------------------------------------------------------------------------------------------
117 /**
118  * This function can be called after pa_wifi_Scan.
119  * When the reading is done, it no longer returns LE_OK
120  * pa_wifiClient_ScanDone MUST be called.
121  *
122  * @return LE_NOT_FOUND There is no more AP found.
123  * @return LE_OK The function succeeded.
124  * @return LE_FAULT The function failed.
125  */
126 //--------------------------------------------------------------------------------------------------
127 LE_SHARED le_result_t pa_wifiClient_GetScanResult
128 (
129  pa_wifiClient_AccessPoint_t *accessPointPtr
130  ///< [IN][OUT]
131  ///< Structure provided by calling function.
132  ///< Results filled out if result was LE_OK.
133 );
134 
135 //--------------------------------------------------------------------------------------------------
136 /**
137  * This function must be called after the pa_wifiClient_Scan() has been done.
138  * It signals that the scan results are no longer needed and frees some internal resourses.
139  *
140  * @return LE_OK The function succeeded.
141  * @return LE_FAULT The scan failed
142  */
143 //--------------------------------------------------------------------------------------------------
144 LE_SHARED le_result_t pa_wifiClient_ScanDone
145 (
146  void
147 );
148 
149 //--------------------------------------------------------------------------------------------------
150 /**
151  * This function connects a wifiClient.
152  *
153  * @return LE_FAULT The function failed.
154  * @return LE_OK The function succeeded.
155  */
156 //--------------------------------------------------------------------------------------------------
157 LE_SHARED le_result_t pa_wifiClient_Connect
158 (
159  uint8_t ssidBytes[LE_WIFIDEFS_MAX_SSID_BYTES],
160  /// [IN]
161  ///< Contains ssidLength number of bytes
162  uint8_t ssidLength
163  /// [IN]
164  ///< The number of bytes in the ssidBytes
165 );
166 
167 //--------------------------------------------------------------------------------------------------
168 /**
169  * This function disconnects a wifiClient.
170  *
171  * @return LE_FAULT The function failed.
172  * @return LE_OK The function succeeded.
173  */
174 //--------------------------------------------------------------------------------------------------
175 LE_SHARED le_result_t pa_wifiClient_Disconnect
176 (
177  void
178 );
179 
180 //--------------------------------------------------------------------------------------------------
181 /**
182  * Set the username and password (WPA-Entreprise).
183  *
184  * @return LE_FAULT The function failed.
185  * @return LE_OK The function succeeded.
186  */
187 //--------------------------------------------------------------------------------------------------
188 LE_SHARED le_result_t pa_wifiClient_SetUserCredentials
189 (
190  const char *usernamePtr,
191  ///< [IN]
192  ///< Username used for authentication
193  const char *passwordPtr
194  ///< [IN]
195  ///< Password used for authentication
196 );
197 
198 //--------------------------------------------------------------------------------------------------
199 /**
200  * Set the PassPhrase used to create PSK (WPA-Personal).
201  * @see pa_wifiClient_SetPreSharedKey
202  *
203  * @return LE_FAULT The function failed.
204  * @return LE_OK The function succeeded.
205  */
206 //--------------------------------------------------------------------------------------------------
207 LE_SHARED le_result_t pa_wifiClient_SetPassphrase
208 (
209  const char *passphrasePtr
210  ///< [IN]
211  ///< Passphrase used for authentication
212 );
213 
214 //--------------------------------------------------------------------------------------------------
215 /**
216  * Set the PreSharedKey (WPA-Personal)
217  * @see pa_wifiClient_SetPassPhrase
218  *
219  * @return LE_FAULT The function failed.
220  * @return LE_OK The function succeeded.
221  */
222 //--------------------------------------------------------------------------------------------------
223 LE_SHARED le_result_t pa_wifiClient_SetPreSharedKey
224 (
225  const char *preSharedKeyPtr
226  ///< [IN]
227  ///< Pre-shared key (PSK) used for authentication
228 );
229 
230 //--------------------------------------------------------------------------------------------------
231 /**
232  * This function specifies whether the target Access Point is hiding its presence from clients or
233  * not. When an Access Point is hidden, it cannot be discovered by a scan process.
234  *
235  * @note By default, this attribute is not set which means that the client is unable to connect to
236  * a hidden access point. When enabled, the client will be able to connect to the access point
237  * whether it is hidden or not.
238  */
239 //--------------------------------------------------------------------------------------------------
240 LE_SHARED void pa_wifiClient_SetHiddenNetworkAttribute
241 (
242  bool hidden
243  ///< [IN]
244  ///< If TRUE, the WIFI client will be able to connect to a hidden access point.
245 );
246 
247 //--------------------------------------------------------------------------------------------------
248 /**
249  * Set the WEP key (WEP)
250  *
251  * @return LE_FAULT The function failed.
252  * @return LE_OK The function succeeded.
253  */
254 //--------------------------------------------------------------------------------------------------
255 LE_SHARED le_result_t pa_wifiClient_SetWepKey
256 (
257  const char *wepKeyPtr
258  ///< [IN]
259  ///< Wired Equivalent Privacy (WEP) key used for authentication
260 );
261 
262 //--------------------------------------------------------------------------------------------------
263 /**
264  * Set the security protocol for connection
265  *
266  * @return LE_FAULT The function failed.
267  * @return LE_OK The function succeeded.
268  */
269 //--------------------------------------------------------------------------------------------------
270 LE_SHARED le_result_t pa_wifiClient_SetSecurityProtocol
271 (
272  const le_wifiClient_SecurityProtocol_t securityProtocol
273  ///< [IN]
274  ///< Security protocol used for communication.
275 );
276 
277 //--------------------------------------------------------------------------------------------------
278 /**
279  * Clears all username, password, pre-shared key, passphrase settings previously made by
280  * @see pa_wifiClient_SetPassPhrase
281  * @see pa_wifiClient_SetPreSharedKey
282  * @see pa_wifiClient_SetUserCredentials
283  *
284  * @return LE_FAULT The function failed.
285  * @return LE_OK The function succeeded.
286  */
287 //--------------------------------------------------------------------------------------------------
288 LE_SHARED le_result_t pa_wifiClient_ClearAllCredentials
289 (
290  void
291 );
292 
293 //--------------------------------------------------------------------------------------------------
294 /**
295  * Start WiFi Client PA
296  *
297  * @return LE_FAULT The function failed.
298  * @return LE_OK The function succeeded.
299  */
300 //--------------------------------------------------------------------------------------------------
301 LE_SHARED le_result_t pa_wifiClient_Start
302 (
303  void
304 );
305 
306 //--------------------------------------------------------------------------------------------------
307 /**
308  * Stop WiFi Client PA
309  *
310  * @return LE_FAULT The function failed.
311  * @return LE_OK The function succeeded.
312  */
313 //--------------------------------------------------------------------------------------------------
314 LE_SHARED le_result_t pa_wifiClient_Stop
315 (
316  void
317 );
318 #endif // PA_WIFI_H
le_wifiClient_SecurityProtocol_t
Definition: le_wifiClient_interface.h:322
#define LE_SHARED
Definition: le_basics.h:240
le_wifiClient_Event_t
Definition: le_wifiClient_interface.h:303
le_result_t
Definition: le_basics.h:35
#define LE_WIFIDEFS_MAX_SSID_BYTES
Definition: le_wifiDefs_interface.h:236
uint8_t ssidLength
The number of bytes in the ssidBytes.
Definition: pa_wifi.h:23
int16_t signalStrength
0xffff means value was not found.
Definition: pa_wifi.h:22
#define LE_WIFIDEFS_MAX_BSSID_BYTES
Definition: le_wifiDefs_interface.h:252
Definition: pa_wifi.h:20