pa_wifi.h

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