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  */
142 //--------------------------------------------------------------------------------------------------
143 LE_SHARED le_result_t pa_wifiClient_ScanDone
144 (
145  void
146 );
147 
148 //--------------------------------------------------------------------------------------------------
149 /**
150  * This function connects a wifiClient.
151  *
152  * @return LE_FAULT The function failed.
153  * @return LE_OK The function succeeded.
154  */
155 //--------------------------------------------------------------------------------------------------
156 LE_SHARED le_result_t pa_wifiClient_Connect
157 (
158  uint8_t ssidBytes[LE_WIFIDEFS_MAX_SSID_BYTES],
159  /// [IN]
160  ///< Contains ssidLength number of bytes
161  uint8_t ssidLength
162  /// [IN]
163  ///< The number of bytes in the ssidBytes
164 );
165 
166 //--------------------------------------------------------------------------------------------------
167 /**
168  * This function disconnects a wifiClient.
169  *
170  * @return LE_FAULT The function failed.
171  * @return LE_OK The function succeeded.
172  */
173 //--------------------------------------------------------------------------------------------------
174 LE_SHARED le_result_t pa_wifiClient_Disconnect
175 (
176  void
177 );
178 
179 //--------------------------------------------------------------------------------------------------
180 /**
181  * Set the username and password (WPA-Entreprise).
182  *
183  * @return LE_FAULT The function failed.
184  * @return LE_OK The function succeeded.
185  */
186 //--------------------------------------------------------------------------------------------------
187 LE_SHARED le_result_t pa_wifiClient_SetUserCredentials
188 (
189  const char *usernamePtr,
190  ///< [IN]
191  ///< Username used for authentication
192  const char *passwordPtr
193  ///< [IN]
194  ///< Password used for authentication
195 );
196 
197 //--------------------------------------------------------------------------------------------------
198 /**
199  * Set the PassPhrase used to create PSK (WPA-Personal).
200  * @see pa_wifiClient_SetPreSharedKey
201  *
202  * @return LE_FAULT The function failed.
203  * @return LE_OK The function succeeded.
204  */
205 //--------------------------------------------------------------------------------------------------
206 LE_SHARED le_result_t pa_wifiClient_SetPassphrase
207 (
208  const char *passphrasePtr
209  ///< [IN]
210  ///< Passphrase used for authentication
211 );
212 
213 //--------------------------------------------------------------------------------------------------
214 /**
215  * Set the PreSharedKey (WPA-Personal)
216  * @see pa_wifiClient_SetPassPhrase
217  *
218  * @return LE_FAULT The function failed.
219  * @return LE_OK The function succeeded.
220  */
221 //--------------------------------------------------------------------------------------------------
222 LE_SHARED le_result_t pa_wifiClient_SetPreSharedKey
223 (
224  const char *preSharedKeyPtr
225  ///< [IN]
226  ///< Pre-shared key (PSK) used for authentication
227 );
228 
229 //--------------------------------------------------------------------------------------------------
230 /**
231  * This function specifies whether the target Access Point is hiding its presence from clients or
232  * not. When an Access Point is hidden, it cannot be discovered by a scan process.
233  *
234  * @note By default, this attribute is not set which means that the client is unable to connect to
235  * a hidden access point. When enabled, the client will be able to connect to the access point
236  * whether it is hidden or not.
237  */
238 //--------------------------------------------------------------------------------------------------
239 LE_SHARED void pa_wifiClient_SetHiddenNetworkAttribute
240 (
241  bool hidden
242  ///< [IN]
243  ///< If TRUE, the WIFI client will be able to connect to a hidden access point.
244 );
245 
246 //--------------------------------------------------------------------------------------------------
247 /**
248  * Set the WEP key (WEP)
249  *
250  * @return LE_FAULT The function failed.
251  * @return LE_OK The function succeeded.
252  */
253 //--------------------------------------------------------------------------------------------------
254 LE_SHARED le_result_t pa_wifiClient_SetWepKey
255 (
256  const char *wepKeyPtr
257  ///< [IN]
258  ///< Wired Equivalent Privacy (WEP) key used for authentication
259 );
260 
261 //--------------------------------------------------------------------------------------------------
262 /**
263  * Set the security protocol for connection
264  *
265  * @return LE_FAULT The function failed.
266  * @return LE_OK The function succeeded.
267  */
268 //--------------------------------------------------------------------------------------------------
269 LE_SHARED le_result_t pa_wifiClient_SetSecurityProtocol
270 (
271  const le_wifiClient_SecurityProtocol_t securityProtocol
272  ///< [IN]
273  ///< Security protocol used for communication.
274 );
275 
276 //--------------------------------------------------------------------------------------------------
277 /**
278  * Clears all username, password, pre-shared key, passphrase settings previously made by
279  * @see pa_wifiClient_SetPassPhrase
280  * @see pa_wifiClient_SetPreSharedKey
281  * @see pa_wifiClient_SetUserCredentials
282  *
283  * @return LE_FAULT The function failed.
284  * @return LE_OK The function succeeded.
285  */
286 //--------------------------------------------------------------------------------------------------
287 LE_SHARED le_result_t pa_wifiClient_ClearAllCredentials
288 (
289  void
290 );
291 
292 //--------------------------------------------------------------------------------------------------
293 /**
294  * Start WiFi Client PA
295  *
296  * @return LE_FAULT The function failed.
297  * @return LE_OK The function succeeded.
298  */
299 //--------------------------------------------------------------------------------------------------
300 LE_SHARED le_result_t pa_wifiClient_Start
301 (
302  void
303 );
304 
305 //--------------------------------------------------------------------------------------------------
306 /**
307  * Stop WiFi Client PA
308  *
309  * @return LE_FAULT The function failed.
310  * @return LE_OK The function succeeded.
311  */
312 //--------------------------------------------------------------------------------------------------
313 LE_SHARED le_result_t pa_wifiClient_Stop
314 (
315  void
316 );
317 #endif // PA_WIFI_H
le_wifiClient_SecurityProtocol_t
Definition: le_wifiClient_interface.h:320
#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