le_wifiAp_interface.h

Go to the documentation of this file.
1 
2 
3 /*
4  * ====================== WARNING ======================
5  *
6  * THE CONTENTS OF THIS FILE HAVE BEEN AUTO-GENERATED.
7  * DO NOT MODIFY IN ANY WAY.
8  *
9  * ====================== WARNING ======================
10  */
11 
12 /**
13  * @page c_le_wifi_ap WiFi Access Point Service
14  *
15  * @ref le_wifiAp_interface.h "API Reference"
16  *
17  * <HR>
18  *
19  * This WiFi Service API provides Wifi Access Point setup.
20  * Please note that if there is only one wifi hardware the WiFi Access Point
21  * cannot be used at the same time as the WiFi Client service.
22  *
23  * @section le_wifi_binding IPC interfaces binding
24  *
25  *
26  * Here's a code sample binding to WiFi service:
27  * @verbatim
28  bindings:
29  {
30  clientExe.clientComponent.le_wifiAp -> wifiService.le_wifiAp
31  }
32  @endverbatim
33  *
34  *
35  *
36  * @section le_wifiAp_connect_to_ap Setting parameters for the Access Point
37  *
38  * Note that these parameters must be set before the access point is started.
39  * See each function for its default value.
40  *
41  * To set the SSID for the Access Point use the following function:
42  * - le_wifiAp_SetSsid()
43  *
44  * To set the pass phrase prior for the Access Point use the function:
45  * Also see le_wifiAp_SetPreSharedKey().
46  * - le_wifiAp_SetPassPhrase()
47  *
48  * Instead of setting the pass phrase, the Pre Shared Key (PSK), can be set explicitly.
49  * To set the Pre Shared Key prior for the Access Point start use the function:
50  * - le_wifiAp_SetPreSharedKey()
51  *
52  * Sets the security protocol to use.
53  * - le_wifiAp_SetSecurityProtocol()
54  *
55  * Sets is the Access Point should show up in network scans or not.
56  * - le_wifiAp_SetDiscoverable()
57  *
58  * Sets which channel to use.
59  * - le_wifiAp_SetChannel()
60  *
61  *
62  * @snippet "apps/sample/wifiApTest/wifiApTestComponent/wifiApTest.c" SetCred
63  *
64  * @section le_wifiAp_Start Starting the WiFi Access Point
65  *
66  * The WiFi Access Point is started with the function le_wifiAp_Start(). Unless values have been changed, default values will be used:
67  * - le_wifiAp_Start():
68  *
69  * To subscribe to wifi events le_wifiAp_AddNewEventHandler() is to be called.
70  * - le_wifiAp_AddNewEventHandler()
71  *
72  *
73  * @snippet "apps/sample/wifiApTest/wifiApTestComponent/wifiApTest.c" Subscribe
74  *
75  * <HR>
76  *
77  * Copyright (C) Sierra Wireless Inc.
78  */
79 /**
80  * @file le_wifiAp_interface.h
81  *
82  * Legato @ref c_le_wifiAp include file.
83  *
84  * Copyright (C) Sierra Wireless Inc.
85  */
86 
87 #ifndef LE_WIFIAP_INTERFACE_H_INCLUDE_GUARD
88 #define LE_WIFIAP_INTERFACE_H_INCLUDE_GUARD
89 
90 
91 #include "legato.h"
92 
93 // Interface specific includes
94 #include "le_wifiDefs_interface.h"
95 
96 
97 //--------------------------------------------------------------------------------------------------
98 /**
99  * Type for handler called when a server disconnects.
100  */
101 //--------------------------------------------------------------------------------------------------
102 typedef void (*le_wifiAp_DisconnectHandler_t)(void *);
103 
104 //--------------------------------------------------------------------------------------------------
105 /**
106  *
107  * Connect the current client thread to the service providing this API. Block until the service is
108  * available.
109  *
110  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
111  * called before any other functions in this API. Normally, ConnectService is automatically called
112  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
113  *
114  * This function is created automatically.
115  */
116 //--------------------------------------------------------------------------------------------------
118 (
119  void
120 );
121 
122 //--------------------------------------------------------------------------------------------------
123 /**
124  *
125  * Try to connect the current client thread to the service providing this API. Return with an error
126  * if the service is not available.
127  *
128  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
129  * called before any other functions in this API. Normally, ConnectService is automatically called
130  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
131  *
132  * This function is created automatically.
133  *
134  * @return
135  * - LE_OK if the client connected successfully to the service.
136  * - LE_UNAVAILABLE if the server is not currently offering the service to which the client is
137  * bound.
138  * - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
139  * - LE_COMM_ERROR if the Service Directory cannot be reached.
140  */
141 //--------------------------------------------------------------------------------------------------
143 (
144  void
145 );
146 
147 //--------------------------------------------------------------------------------------------------
148 /**
149  * Set handler called when server disconnection is detected.
150  *
151  * When a server connection is lost, call this handler then exit with LE_FATAL. If a program wants
152  * to continue without exiting, it should call longjmp() from inside the handler.
153  */
154 //--------------------------------------------------------------------------------------------------
156 (
157  le_wifiAp_DisconnectHandler_t disconnectHandler,
158  void *contextPtr
159 );
160 
161 //--------------------------------------------------------------------------------------------------
162 /**
163  *
164  * Disconnect the current client thread from the service providing this API.
165  *
166  * Normally, this function doesn't need to be called. After this function is called, there's no
167  * longer a connection to the service, and the functions in this API can't be used. For details, see
168  * @ref apiFilesC_client.
169  *
170  * This function is created automatically.
171  */
172 //--------------------------------------------------------------------------------------------------
174 (
175  void
176 );
177 
178 
179 //--------------------------------------------------------------------------------------------------
180 /**
181  * WiFi Access Point Events.
182  */
183 //--------------------------------------------------------------------------------------------------
184 typedef enum
185 {
187  ///< Client connected to WiFi Access Point.
189  ///< Client disconnected from WiFi Access Point.
190 }
192 
193 
194 //--------------------------------------------------------------------------------------------------
195 /**
196  * WiFi Access Point Security levels.
197  */
198 //--------------------------------------------------------------------------------------------------
199 typedef enum
200 {
202  ///< WiFi Access Point is open and has no password.
204  ///< WiFi Access Point has WPA2 activated.
205 }
207 
208 
209 //--------------------------------------------------------------------------------------------------
210 /**
211  * Reference type used by Add/Remove functions for EVENT 'le_wifiAp_NewEvent'
212  */
213 //--------------------------------------------------------------------------------------------------
214 typedef struct le_wifiAp_NewEventHandler* le_wifiAp_NewEventHandlerRef_t;
215 
216 
217 //--------------------------------------------------------------------------------------------------
218 /**
219  * Handler for WiFi Access Point changes
220  */
221 //--------------------------------------------------------------------------------------------------
222 typedef void (*le_wifiAp_EventHandlerFunc_t)
223 (
224  le_wifiAp_Event_t event,
225  ///< Handles the wifi events
226  void* contextPtr
227  ///<
228 );
229 
230 //--------------------------------------------------------------------------------------------------
231 /**
232  * Add handler function for EVENT 'le_wifiAp_NewEvent'
233  *
234  * These events provide information on WiFi Access Point
235  *
236  */
237 //--------------------------------------------------------------------------------------------------
239 (
240  le_wifiAp_EventHandlerFunc_t handlerPtr,
241  ///< [IN]
242  void* contextPtr
243  ///< [IN]
244 );
245 
246 //--------------------------------------------------------------------------------------------------
247 /**
248  * Remove handler function for EVENT 'le_wifiAp_NewEvent'
249  */
250 //--------------------------------------------------------------------------------------------------
252 (
254  ///< [IN]
255 );
256 
257 //--------------------------------------------------------------------------------------------------
258 /**
259  * This function starts the WIFI Access Point.
260  * @note that all settings, if to be used, such as security, username, password must set prior to
261  * starting the Access Point.
262  *
263  * @return
264  * - LE_FAULT if the function failed.
265  * - LE_OK if the function succeeded.
266  *
267  */
268 //--------------------------------------------------------------------------------------------------
270 (
271  void
272 );
273 
274 //--------------------------------------------------------------------------------------------------
275 /**
276  * This function stops the WIFI Access Point.
277  *
278  * @return
279  * - LE_FAULT if the function failed.
280  * - LE_OK if the function succeeded.
281  *
282  */
283 //--------------------------------------------------------------------------------------------------
285 (
286  void
287 );
288 
289 //--------------------------------------------------------------------------------------------------
290 /**
291  * Set the Service set identification (SSID) of the AccessPoint
292  * Default value is "LEGATO Access Point"
293  * @note that the SSID does not have to be human readable ASCII values, but often has.
294  *
295  * @return
296  * - LE_BAD_PARAMETER if some parameter is invalid.
297  * - LE_OK if the function succeeded.
298  */
299 //--------------------------------------------------------------------------------------------------
301 (
302  const uint8_t* ssidPtr,
303  ///< [IN] The SSID to set as a octet array.
304  size_t ssidSize
305  ///< [IN]
306 );
307 
308 //--------------------------------------------------------------------------------------------------
309 /**
310  * Set the Security protocol to use.
311  * Default value is SECURITY_WPA2.
312  * @note that the SSID does not have to be human readable ASCII values, but often has.
313  *
314  * @return
315  * - LE_BAD_PARAMETER if some parameter is invalid.
316  * - LE_OK if the function succeeded.
317  */
318 //--------------------------------------------------------------------------------------------------
320 (
321  le_wifiAp_SecurityProtocol_t securityProtocol
322  ///< [IN] The security protocol to use.
323 );
324 
325 //--------------------------------------------------------------------------------------------------
326 /**
327  * Set the passphrase used to generate the PSK.
328  *
329  * @note If the PSK is to be set directly, please use le_wifiAp_SetPreSharedKey()
330  *
331  * @return
332  * - LE_BAD_PARAMETER if parameter is invalid.
333  * - LE_OK if the function succeeded.
334  *
335  */
336 //--------------------------------------------------------------------------------------------------
338 (
339  const char* LE_NONNULL passPhrase
340  ///< [IN] pass-phrase for PSK
341 );
342 
343 //--------------------------------------------------------------------------------------------------
344 /**
345  * Set the Pre Shared Key, PSK.
346  * There is no default value, since le_wifiAp_SetPassPhrase is used as default.
347  * @note the difference between le_wifiAp_SetPassPhrase() and this function
348  *
349  * @return
350  * - LE_BAD_PARAMETER if parameter is invalid.
351  * - LE_OK if the function succeeded.
352  *
353  */
354 //--------------------------------------------------------------------------------------------------
356 (
357  const char* LE_NONNULL preSharedKey
358  ///< [IN] PSK. Note the difference between PSK and Pass Phrase.
359 );
360 
361 //--------------------------------------------------------------------------------------------------
362 /**
363  * Set if the Access Point should announce its presence.
364  * Default value is TRUE.
365  * If the value is set to FALSE, the Access Point will be hidden.
366  *
367  * @return LE_OK if the function succeeded.
368  *
369  */
370 //--------------------------------------------------------------------------------------------------
372 (
373  bool discoverable
374  ///< [IN] If TRUE the Access Point shows up on scans, else it is hidden.
375 );
376 
377 //--------------------------------------------------------------------------------------------------
378 /**
379  * Set which WiFi Channel to use.
380  * Default value is 1.
381  * Some legal restrictions for values 12 - 14 might apply for your region.
382  *
383  * @return
384  * - LE_OUT_OF_RANGE if requested channel number is out of range.
385  * - LE_OK if the function succeeded.
386  *
387  */
388 //--------------------------------------------------------------------------------------------------
390 (
391  int8_t channelNumber
392  ///< [IN] the channel number must be between 1 and 14.
393 );
394 
395 //--------------------------------------------------------------------------------------------------
396 /**
397  * Set number of maximally allowed clients to connect to the Access Point at the same time.
398  *
399  * @return
400  * - LE_OUT_OF_RANGE if requested number of users exceeds the capabilities of the Access Point.
401  * - LE_OK if the function succeeded.
402  *
403  */
404 //--------------------------------------------------------------------------------------------------
406 (
407  int8_t maxNumberOfClient
408  ///< [IN] the maximum number of clients
409 );
410 
411 //--------------------------------------------------------------------------------------------------
412 /**
413  * Defines the IP adresses range for the host AP.
414  *
415  * @return
416  * - LE_BAD_PARAMETER if at least one of the given IP addresses is invalid.
417  * - LE_FAULT if a system call failed.
418  * - LE_OK if the function succeeded.
419  *
420  */
421 //--------------------------------------------------------------------------------------------------
423 (
424  const char* LE_NONNULL ipAp,
425  ///< [IN] the IP address of the Access Point.
426  const char* LE_NONNULL ipStart,
427  ///< [IN] the start IP address of the Access Point.
428  const char* LE_NONNULL ipStop
429  ///< [IN] the stop IP address of the Access Point.
430 );
431 
432 #endif // LE_WIFIAP_INTERFACE_H_INCLUDE_GUARD
void le_wifiAp_DisconnectService(void)
le_result_t
Definition: le_basics.h:35
le_result_t le_wifiAp_Stop(void)
le_result_t le_wifiAp_SetPreSharedKey(const char *LE_NONNULL preSharedKey)
struct le_wifiAp_NewEventHandler * le_wifiAp_NewEventHandlerRef_t
Definition: le_wifiAp_interface.h:214
le_wifiAp_Event_t
Definition: le_wifiAp_interface.h:184
void le_wifiAp_SetServerDisconnectHandler(le_wifiAp_DisconnectHandler_t disconnectHandler, void *contextPtr)
le_wifiAp_NewEventHandlerRef_t le_wifiAp_AddNewEventHandler(le_wifiAp_EventHandlerFunc_t handlerPtr, void *contextPtr)
le_result_t le_wifiAp_SetSecurityProtocol(le_wifiAp_SecurityProtocol_t securityProtocol)
le_result_t le_wifiAp_SetSsid(const uint8_t *ssidPtr, size_t ssidSize)
Client disconnected from WiFi Access Point.
Definition: le_wifiAp_interface.h:188
le_result_t le_wifiAp_SetMaxNumberOfClients(int8_t maxNumberOfClient)
le_result_t le_wifiAp_SetDiscoverable(bool discoverable)
void(* le_wifiAp_EventHandlerFunc_t)(le_wifiAp_Event_t event, void *contextPtr)
Definition: le_wifiAp_interface.h:223
le_result_t le_wifiAp_SetPassPhrase(const char *LE_NONNULL passPhrase)
le_result_t le_wifiAp_SetChannel(int8_t channelNumber)
void le_wifiAp_ConnectService(void)
void le_wifiAp_RemoveNewEventHandler(le_wifiAp_NewEventHandlerRef_t handlerRef)
Client connected to WiFi Access Point.
Definition: le_wifiAp_interface.h:186
WiFi Access Point has WPA2 activated.
Definition: le_wifiAp_interface.h:203
le_wifiAp_SecurityProtocol_t
Definition: le_wifiAp_interface.h:199
le_result_t le_wifiAp_SetIpRange(const char *LE_NONNULL ipAp, const char *LE_NONNULL ipStart, const char *LE_NONNULL ipStop)
WiFi Access Point is open and has no password.
Definition: le_wifiAp_interface.h:201
void(* le_wifiAp_DisconnectHandler_t)(void *)
Definition: le_wifiAp_interface.h:102
le_result_t le_wifiAp_Start(void)
le_result_t le_wifiAp_TryConnectService(void)