pa_wifi_ap.h

1 #ifndef PA_WIFI_AP_H
2 #define PA_WIFI_AP_H
3 // -------------------------------------------------------------------------------------------------
4 /**
5  *
6  *
7  * Copyright (C) Sierra Wireless Inc. Use of this work is subject to license.
8  *
9  */
10 // -------------------------------------------------------------------------------------------------
11 #include "legato.h"
12 #include "interfaces.h"
13 
14 //--------------------------------------------------------------------------------------------------
15 /**
16  * Event handler for PA WiFi access point changes.
17  *
18  * Handles the PA WiFi events.
19  */
20 //--------------------------------------------------------------------------------------------------
21 typedef void (*pa_wifiAp_NewEventHandlerFunc_t)
22 (
23  le_wifiAp_Event_t event,
24  ///< [IN]
25  ///< WiFi event to process
26  void *contextPtr
27  ///< [IN]
28  ///< Associated WiFi event context
29 );
30 
31 //--------------------------------------------------------------------------------------------------
32 /**
33  * Add handler function for WiFi related events.
34  *
35  * These events provide information on WiFi access point status.
36  *
37  * @return LE_OK Function succeeded.
38  */
39 //--------------------------------------------------------------------------------------------------
40 LE_SHARED le_result_t pa_wifiAp_AddEventHandler
41 (
42  pa_wifiAp_NewEventHandlerFunc_t handlerPtr,
43  ///< [IN]
44  ///< Event handler function pointer
45 
46  void *contextPtr
47  ///< [IN]
48  ///< Associated event context
49 );
50 
51 //--------------------------------------------------------------------------------------------------
52 /**
53  * This function must be called to initialize the PA WiFi Access Point.
54  *
55  * @return LE_OK The function succeeded.
56  */
57 //--------------------------------------------------------------------------------------------------
58 LE_SHARED le_result_t pa_wifiAp_Init
59 (
60  void
61 );
62 
63 //--------------------------------------------------------------------------------------------------
64 /**
65  * This function must be called to release the platform adaptor WiFi module.
66  *
67  * @return LE_OK The function succeeded.
68  */
69 //--------------------------------------------------------------------------------------------------
70 LE_SHARED le_result_t pa_wifiAp_Release
71 (
72  void
73 );
74 
75 //--------------------------------------------------------------------------------------------------
76 /**
77  * This function starts the WiFi access point.
78  * Note that all settings, if to be used, such as security, username, password must set prior to
79  * starting the access point.
80  *
81  * @return LE_FAULT The function failed.
82  * @return LE_OK The function succeeded.
83  *
84  */
85 //--------------------------------------------------------------------------------------------------
86 le_result_t pa_wifiAp_Start
87 (
88  void
89 );
90 
91 //--------------------------------------------------------------------------------------------------
92 /**
93  * This function stops the WiFi access point.
94  *
95  * @return LE_FAULT The function failed.
96  * @return LE_OK The function succeeded.
97  *
98  */
99 //--------------------------------------------------------------------------------------------------
100 le_result_t pa_wifiAp_Stop
101 (
102  void
103 );
104 
105 //--------------------------------------------------------------------------------------------------
106 /**
107  * Set the security protocol to use.
108  *
109  * @note WEP is not supported as it is unsecure and has been deprecated in favor of WPA/WPA2.
110  * This limitation applies to access point mode only.
111  *
112  * @return LE_BAD_PARAMETER Some parameter is invalid.
113  * @return LE_OK Function succeeded.
114  */
115 //--------------------------------------------------------------------------------------------------
116 le_result_t pa_wifiAp_SetSecurityProtocol
117 (
118  le_wifiAp_SecurityProtocol_t securityProtocol
119  ///< [IN]
120  ///< The security protocol used to communicate with the access point.
121 );
122 
123 //--------------------------------------------------------------------------------------------------
124 /**
125  * Set the Service Set IDentification (SSID) of the access point.
126  *
127  * @note The SSID does not have to be human readable ASCII values, but often is.
128  *
129  * @return LE_BAD_PARAMETER Some parameter is invalid.
130  * @return LE_OK Function succeeded.
131  */
132 //--------------------------------------------------------------------------------------------------
133 le_result_t pa_wifiAp_SetSsid
134 (
135  const uint8_t *ssidPtr,
136  ///< [IN]
137  ///< The SSID to set as an octet array.
138 
139  size_t ssidNumElements
140  ///< [IN]
141  ///< The length of the SSID in octets.
142 );
143 
144 //--------------------------------------------------------------------------------------------------
145 /**
146  * Set the passphrase used to generate the PSK.
147  *
148  * @note This is one way to authenticate against the access point. The other one is provided by the
149  * le_wifiAp_SetPreSharedKey() function. Both ways are exclusive and are effective only when used
150  * with WPA-personal authentication.
151  *
152  * @return LE_BAD_PARAMETER Parameter is invalid.
153  * @return LE_OK Function succeeded.
154  */
155 //--------------------------------------------------------------------------------------------------
156 le_result_t pa_wifiAp_SetPassPhrase
157 (
158  const char *passphrasePtr
159  ///< [IN]
160  ///< Passphrase to authenticate against the access point.
161 );
162 
163 //--------------------------------------------------------------------------------------------------
164 /**
165  * Set the pre-shared key (PSK).
166  *
167  * @note This is one way to authenticate against the access point. The other one is provided by the
168  * le_wifiAp_SetPassPhrase() function. Both ways are exclusive and are effective only when used
169  * with WPA-personal authentication.
170  *
171  * @return LE_BAD_PARAMETER Parameter is invalid.
172  * @return LE_OK Function succeeded.
173  */
174 //--------------------------------------------------------------------------------------------------
175 le_result_t pa_wifiAp_SetPreSharedKey
176 (
177  const char *preSharedKeyPtr
178  ///< [IN]
179  ///< Pre-shared key used to authenticate against the access point.
180 );
181 
182 //--------------------------------------------------------------------------------------------------
183 /**
184  * Set if the Access Point should announce it's presence.
185  * Default value is TRUE.
186  * If the value is set to FALSE, the access point will be hidden.
187  *
188  * @return LE_OK Function succeeded.
189  *
190  */
191 //--------------------------------------------------------------------------------------------------
192 le_result_t pa_wifiAp_SetDiscoverable
193 (
194  bool isDiscoverable
195  ///< [IN]
196  ///< If TRUE, the access point SSID is visible by the clients otherwise it is hidden.
197 );
198 
199 //--------------------------------------------------------------------------------------------------
200 /**
201  * Set the WiFi channel to use.
202  * Default value is 1.
203  * Some legal restrictions for values 12 - 14 might apply for your region.
204  *
205  * @return LE_OUT_OF_RANGE Requested channel number is out of range.
206  * @return LE_OK Function succeeded.
207  *
208  */
209 //--------------------------------------------------------------------------------------------------
210 le_result_t pa_wifiAp_SetChannel
211 (
212  int8_t channelNumber
213  ///< [IN]
214  ///< the channel number must be between 1 and 14.
215 );
216 
217 //--------------------------------------------------------------------------------------------------
218 /**
219  * Set the maximum number of clients connected to WiFi access point at the same time.
220  * Default value is 10.
221  *
222  * @note This value depends on the hardware/software capabilities of the WiFi module used.
223  *
224  * @return LE_OUT_OF_RANGE Requested number of users exceeds the capabilities of the Access Point.
225  * @return LE_OK Function succeeded.
226  *
227  */
228 //--------------------------------------------------------------------------------------------------
229 le_result_t pa_wifiAp_SetMaxNumberClients
230 (
231  int maxNumberClients
232  ///< [IN]
233  ///< the maximum number of clients regarding the WiFi driver and hardware capabilities.
234 );
235 
236 //--------------------------------------------------------------------------------------------------
237 /**
238  * Define the access point IP address and the client IP addresses range.
239  *
240  * @note The access point IP address must be defined outside the client IP addresses range.
241  *
242  * @return LE_BAD_PARAMETER At least, one of the given IP addresses is invalid.
243  * @return LE_FAULT A system call has failed.
244  * @return LE_OK Function succeeded.
245  *
246  */
247 //--------------------------------------------------------------------------------------------------
248 le_result_t pa_wifiAp_SetIpRange
249 (
250  const char *ipApPtr,
251  ///< [IN]
252  ///< the IP address of the Access Point.
253  const char *ipStartPtr,
254  ///< [IN]
255  ///< the start IP address of the Access Point.
256  const char *ipStopPtr
257  ///< [IN]
258  ///< the stop IP address of the Access Point.
259 );
260 #endif // PA_WIFI_AP_H
#define LE_SHARED
Definition: le_basics.h:240
le_result_t
Definition: le_basics.h:35
le_wifiAp_Event_t
Definition: le_wifiAp_interface.h:160
le_wifiAp_SecurityProtocol_t
Definition: le_wifiAp_interface.h:176