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  * Sets what country code to use.
62  * - le_wifiAp_SetCountryCode()
63  *
64  * Sets which IEEE standard to use.
65  * - le_wifiAp_SetIeeeStandard()
66  *
67  * Gets which IEEE standard was set.
68  * - le_wifiAp_GetIeeeStandard()
69  *
70  * @snippet "apps/sample/wifiApTest/wifiApTestComponent/wifiApTest.c" SetCred
71  *
72  * @section le_wifiAp_Start Starting the WiFi Access Point
73  *
74  * The WiFi Access Point is started with the function le_wifiAp_Start(). Unless values have been changed, default values will be used:
75  * - le_wifiAp_Start():
76  *
77  * To subscribe to wifi events le_wifiAp_AddNewEventHandler() is to be called.
78  * - le_wifiAp_AddNewEventHandler()
79  *
80  *
81  * @snippet "apps/sample/wifiApTest/wifiApTestComponent/wifiApTest.c" Subscribe
82  *
83  * <HR>
84  *
85  * Copyright (C) Sierra Wireless Inc.
86  */
87 /**
88  * @file le_wifiAp_interface.h
89  *
90  * Legato @ref c_le_wifiAp include file.
91  *
92  * Copyright (C) Sierra Wireless Inc.
93  */
94 
95 #ifndef LE_WIFIAP_INTERFACE_H_INCLUDE_GUARD
96 #define LE_WIFIAP_INTERFACE_H_INCLUDE_GUARD
97 
98 
99 #include "legato.h"
100 
101 // Interface specific includes
102 #include "le_wifiDefs_interface.h"
103 
104 // Internal includes for this interface
105 #include "le_wifiAp_common.h"
106 //--------------------------------------------------------------------------------------------------
107 /**
108  * Type for handler called when a server disconnects.
109  */
110 //--------------------------------------------------------------------------------------------------
111 typedef void (*le_wifiAp_DisconnectHandler_t)(void *);
112 
113 //--------------------------------------------------------------------------------------------------
114 /**
115  *
116  * Connect the current client thread to the service providing this API. Block until the service is
117  * available.
118  *
119  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
120  * called before any other functions in this API. Normally, ConnectService is automatically called
121  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
122  *
123  * This function is created automatically.
124  */
125 //--------------------------------------------------------------------------------------------------
127 (
128  void
129 );
130 
131 //--------------------------------------------------------------------------------------------------
132 /**
133  *
134  * Try to connect the current client thread to the service providing this API. Return with an error
135  * if the service is not available.
136  *
137  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
138  * called before any other functions in this API. Normally, ConnectService is automatically called
139  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
140  *
141  * This function is created automatically.
142  *
143  * @return
144  * - LE_OK if the client connected successfully to the service.
145  * - LE_UNAVAILABLE if the server is not currently offering the service to which the client is
146  * bound.
147  * - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
148  * - LE_COMM_ERROR if the Service Directory cannot be reached.
149  */
150 //--------------------------------------------------------------------------------------------------
152 (
153  void
154 );
155 
156 //--------------------------------------------------------------------------------------------------
157 /**
158  * Set handler called when server disconnection is detected.
159  *
160  * When a server connection is lost, call this handler then exit with LE_FATAL. If a program wants
161  * to continue without exiting, it should call longjmp() from inside the handler.
162  */
163 //--------------------------------------------------------------------------------------------------
165 (
166  le_wifiAp_DisconnectHandler_t disconnectHandler,
167  void *contextPtr
168 );
169 
170 //--------------------------------------------------------------------------------------------------
171 /**
172  *
173  * Disconnect the current client thread from the service providing this API.
174  *
175  * Normally, this function doesn't need to be called. After this function is called, there's no
176  * longer a connection to the service, and the functions in this API can't be used. For details, see
177  * @ref apiFilesC_client.
178  *
179  * This function is created automatically.
180  */
181 //--------------------------------------------------------------------------------------------------
183 (
184  void
185 );
186 
187 
188 //--------------------------------------------------------------------------------------------------
189 /**
190  * WiFi Access Point Events.
191  */
192 //--------------------------------------------------------------------------------------------------
193 
194 
195 //--------------------------------------------------------------------------------------------------
196 /**
197  * WiFi Access Point Security levels.
198  */
199 //--------------------------------------------------------------------------------------------------
200 
201 
202 //--------------------------------------------------------------------------------------------------
203 /**
204  * IEEE 802.11 standards Bit Mask
205  */
206 //--------------------------------------------------------------------------------------------------
207 
208 
209 //--------------------------------------------------------------------------------------------------
210 /**
211  * Handler for WiFi Access Point changes
212  */
213 //--------------------------------------------------------------------------------------------------
214 
215 
216 //--------------------------------------------------------------------------------------------------
217 /**
218  * Reference type used by Add/Remove functions for EVENT 'le_wifiAp_NewEvent'
219  */
220 //--------------------------------------------------------------------------------------------------
221 
222 
223 //--------------------------------------------------------------------------------------------------
224 /**
225  * Add handler function for EVENT 'le_wifiAp_NewEvent'
226  *
227  * These events provide information on WiFi Access Point
228  *
229  */
230 //--------------------------------------------------------------------------------------------------
231 le_wifiAp_NewEventHandlerRef_t le_wifiAp_AddNewEventHandler
232 (
233  le_wifiAp_EventHandlerFunc_t handlerPtr,
234  ///< [IN]
235  void* contextPtr
236  ///< [IN]
237 );
238 
239 //--------------------------------------------------------------------------------------------------
240 /**
241  * Remove handler function for EVENT 'le_wifiAp_NewEvent'
242  */
243 //--------------------------------------------------------------------------------------------------
245 (
246  le_wifiAp_NewEventHandlerRef_t handlerRef
247  ///< [IN]
248 );
249 
250 //--------------------------------------------------------------------------------------------------
251 /**
252  * This function starts the WIFI Access Point.
253  * @note that all settings, if to be used, such as security, username, password must set prior to
254  * starting the Access Point.
255  *
256  * @return
257  * - LE_FAULT if the function failed.
258  * - LE_OK if the function succeeded.
259  *
260  */
261 //--------------------------------------------------------------------------------------------------
263 (
264  void
265 );
266 
267 //--------------------------------------------------------------------------------------------------
268 /**
269  * This function stops the WIFI Access Point.
270  *
271  * @return
272  * - LE_FAULT if the function failed.
273  * - LE_OK if the function succeeded.
274  *
275  */
276 //--------------------------------------------------------------------------------------------------
278 (
279  void
280 );
281 
282 //--------------------------------------------------------------------------------------------------
283 /**
284  * Set the Service set identification (SSID) of the AccessPoint
285  * Default value is "LEGATO Access Point"
286  * @note that the SSID does not have to be human readable ASCII values, but often has.
287  *
288  * @return
289  * - LE_BAD_PARAMETER if some parameter is invalid.
290  * - LE_OK if the function succeeded.
291  */
292 //--------------------------------------------------------------------------------------------------
294 (
295  const uint8_t* ssidPtr,
296  ///< [IN] The SSID to set as a octet array.
297  size_t ssidSize
298  ///< [IN]
299 );
300 
301 //--------------------------------------------------------------------------------------------------
302 /**
303  * Set the Security protocol to use.
304  * Default value is SECURITY_WPA2.
305  * @note that the SSID does not have to be human readable ASCII values, but often has.
306  *
307  * @return
308  * - LE_BAD_PARAMETER if some parameter is invalid.
309  * - LE_OK if the function succeeded.
310  */
311 //--------------------------------------------------------------------------------------------------
313 (
314  le_wifiAp_SecurityProtocol_t securityProtocol
315  ///< [IN] The security protocol to use.
316 );
317 
318 //--------------------------------------------------------------------------------------------------
319 /**
320  * Set the passphrase used to generate the PSK.
321  *
322  * @note If the PSK is to be set directly, please use le_wifiAp_SetPreSharedKey()
323  *
324  * @return
325  * - LE_BAD_PARAMETER if parameter is invalid.
326  * - LE_OK if the function succeeded.
327  *
328  */
329 //--------------------------------------------------------------------------------------------------
331 (
332  const char* LE_NONNULL passPhrase
333  ///< [IN] pass-phrase for PSK
334 );
335 
336 //--------------------------------------------------------------------------------------------------
337 /**
338  * Set the Pre Shared Key, PSK.
339  * There is no default value, since le_wifiAp_SetPassPhrase is used as default.
340  * @note the difference between le_wifiAp_SetPassPhrase() and this function
341  *
342  * @return
343  * - LE_BAD_PARAMETER if parameter is invalid.
344  * - LE_OK if the function succeeded.
345  *
346  */
347 //--------------------------------------------------------------------------------------------------
349 (
350  const char* LE_NONNULL preSharedKey
351  ///< [IN] PSK. Note the difference between PSK and Pass Phrase.
352 );
353 
354 //--------------------------------------------------------------------------------------------------
355 /**
356  * Set if the Access Point should announce its presence.
357  * Default value is TRUE.
358  * If the value is set to FALSE, the Access Point will be hidden.
359  *
360  * @return LE_OK if the function succeeded.
361  *
362  */
363 //--------------------------------------------------------------------------------------------------
365 (
366  bool discoverable
367  ///< [IN] If TRUE the Access Point shows up on scans, else it is hidden.
368 );
369 
370 //--------------------------------------------------------------------------------------------------
371 /**
372  * Set which IEEE standard to use.
373  * Default hardware mode is IEEE 802.11g.
374  *
375  * @return
376  * - LE_BAD_PARAMETER if invalid IEEE standard is set.
377  * - LE_OK if the function succeeded.
378  *
379  */
380 //--------------------------------------------------------------------------------------------------
382 (
383  le_wifiAp_IeeeStdBitMask_t stdMask
384  ///< [IN] Bit mask for the IEEE standard.
385 );
386 
387 //--------------------------------------------------------------------------------------------------
388 /**
389  * Get which IEEE standard was set.
390  * Default hardware mode is IEEE 802.11g.
391  *
392  * @return
393  * - LE_FAULT if the function failed.
394  * - LE_OK if the function succeeded.
395  *
396  */
397 //--------------------------------------------------------------------------------------------------
399 (
400  le_wifiAp_IeeeStdBitMask_t* stdMaskPtrPtr
401  ///< [OUT] Bit mask for the IEEE standard.
402 );
403 
404 //--------------------------------------------------------------------------------------------------
405 /**
406  * Set which WiFi Channel to use.
407  * Default value is 7.
408  * Some legal restrictions might apply for your region.
409  * The channel number must be between 1 and 14 for IEEE 802.11b/g.
410  * The channel number must be between 7 and 196 for IEEE 802.11a.
411  * The channel number must be between 1 and 6 for IEEE 802.11ad.
412  * @return
413  * - LE_OUT_OF_RANGE if requested channel number is out of range.
414  * - LE_OK if the function succeeded.
415  *
416  */
417 //--------------------------------------------------------------------------------------------------
419 (
420  uint16_t channelNumber
421  ///< [IN] the channel number.
422 );
423 
424 //--------------------------------------------------------------------------------------------------
425 /**
426  * Set what country code to use for regulatory domain.
427  * ISO/IEC 3166-1 Alpha-2 code is used.
428  * Default country code is US.
429  * @return
430  * - LE_FAULT if the function failed.
431  * - LE_OK if the function succeeded.
432  *
433  */
434 //--------------------------------------------------------------------------------------------------
436 (
437  const char* LE_NONNULL countryCode
438  ///< [IN] the country code.
439 );
440 
441 //--------------------------------------------------------------------------------------------------
442 /**
443  * Set number of maximally allowed clients to connect to the Access Point at the same time.
444  *
445  * @return
446  * - LE_OUT_OF_RANGE if requested number of users exceeds the capabilities of the Access Point.
447  * - LE_OK if the function succeeded.
448  *
449  */
450 //--------------------------------------------------------------------------------------------------
452 (
453  int8_t maxNumberOfClient
454  ///< [IN] the maximum number of clients
455 );
456 
457 //--------------------------------------------------------------------------------------------------
458 /**
459  * Defines the IP adresses range for the host AP.
460  *
461  * @return
462  * - LE_BAD_PARAMETER if at least one of the given IP addresses is invalid.
463  * - LE_FAULT if a system call failed.
464  * - LE_OK if the function succeeded.
465  *
466  */
467 //--------------------------------------------------------------------------------------------------
469 (
470  const char* LE_NONNULL ipAp,
471  ///< [IN] the IP address of the Access Point.
472  const char* LE_NONNULL ipStart,
473  ///< [IN] the start IP address of the Access Point.
474  const char* LE_NONNULL ipStop
475  ///< [IN] the stop IP address of the Access Point.
476 );
477 
478 #endif // LE_WIFIAP_INTERFACE_H_INCLUDE_GUARD
le_result_t le_wifiAp_SetIpRange(const char *LE_NONNULL ipAp, const char *LE_NONNULL ipStart, const char *LE_NONNULL ipStop)
le_result_t le_wifiAp_SetSsid(const uint8_t *ssidPtr, size_t ssidSize)
le_result_t
Definition: le_basics.h:35
le_result_t le_wifiAp_SetDiscoverable(bool discoverable)
le_result_t le_wifiAp_SetChannel(uint16_t channelNumber)
le_result_t le_wifiAp_Stop(void)
le_result_t le_wifiAp_TryConnectService(void)
void le_wifiAp_ConnectService(void)
void le_wifiAp_DisconnectService(void)
void le_wifiAp_RemoveNewEventHandler(le_wifiAp_NewEventHandlerRef_t handlerRef)
le_result_t le_wifiAp_SetPassPhrase(const char *LE_NONNULL passPhrase)
le_result_t le_wifiAp_GetIeeeStandard(le_wifiAp_IeeeStdBitMask_t *stdMaskPtrPtr)
le_result_t le_wifiAp_Start(void)
le_result_t le_wifiAp_SetMaxNumberOfClients(int8_t maxNumberOfClient)
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_FULL_API void le_wifiAp_SetServerDisconnectHandler(le_wifiAp_DisconnectHandler_t disconnectHandler, void *contextPtr)
le_result_t le_wifiAp_SetCountryCode(const char *LE_NONNULL countryCode)
void(* le_wifiAp_DisconnectHandler_t)(void *)
Definition: le_wifiAp_interface.h:111
le_result_t le_wifiAp_SetPreSharedKey(const char *LE_NONNULL preSharedKey)
le_result_t le_wifiAp_SetIeeeStandard(le_wifiAp_IeeeStdBitMask_t stdMask)
#define LE_FULL_API
Definition: le_basics.h:288