le_net_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_net le_net Interface
14  *
15  * @ref le_net_interface.h "API Reference" <br>
16  *
17  * When applications need to exchange data with other devices on the packet switched data network,
18  * a data channel needs to be first established over a connectivity technology like cellular or
19  * WiFi. After such channel is successfully established, then applications can open up IP
20  * sockets on this data channel as necessary as a data pipe for sending and receiving data.
21  *
22  * This @c le_net interface provides network services to Data Channel Service (DCS) client
23  * applications to install, uninstall and manage network configurations, while the @c le_dcs
24  * interface provides APIs for starting (associating with), stopping (disassociating from) selected
25  * channels.
26  *
27  * @warning Since these @c le_net APIs generate network and route changes that affect all services
28  * and applications on the device, users must use them with due diligence and full understanding
29  * of their global effects.
30  *
31  * * @section le_net_UniqueID Unique Identifier
32  *
33  * Like the @c le_dcs interface, many of the @c le_net APIs take channel reference, which is
34  * assigned and managed by @c le_dcs, as the input identifier to uniquely identify the channel
35  * which assigned network configurations are taken for use.
36  *
37  * @section le_net_APIOverview API Overview
38  *
39  * The @c le_net interface provides. More details for these APIs can be found in later subsections.
40  *
41  * @note These following APIs have full support for cellular data channels, but only
42  * le_net_ChangeRoute() supports WiFi channels in the moment.
43  *
44  * | Function | Description |
45  * | -------------------------------| ---------------------------------------------------------------------------------------------------|
46  * | le_net_ChangeRoute() | Add or remove host or network route onto the network interface of a given data channel |
47  * | le_net_SetDefaultGW() | Set a device's default gateway addresses to those assigned for a given channel use |
48  * | le_net_GetDefaultGW() | Get the default gateway address(es) for the channel provided (retrieved from DHCP lease file) |
49  * | le_net_BackupDefaultGW() | Back up a device's current default gateway addresses |
50  * | le_net_RestoreDefaultGW() | Restore the default gateway addresses of a device previously backed up by le_net_BackupDefaultGW() |
51  * | le_net_SetDNS() | Set the DNS server addresses into the device's name server address table |
52  * | le_net_GetDNS() | Get the DNS server addresses for the channel provided (retrieved from DHCP lease file) |
53  * | le_net_RestoreDNS() | Remove the DNS server addresses previously added to the device's name server address table |
54  *
55  *
56  * @subsection le_net_APIDetails_ChangeRoute Change Route
57  *
58  * An application can use the le_net_ChangeRoute() function to add or remove a host or network route
59  * onto the network interface of a given channel. The channel reference as an API input identifies
60  * the network interface which a route is to be added onto or removed from. Whether the operation
61  * is an add or a remove depends on the isAdd boolean value of the last API input argument.
62  *
63  * The IP address and mask input arguments specify the destination address and mask for the route.
64  * The formats used for them are the same as used in the Linux command
65  * "ip route add <ipAddr>/<prefixLength> dev <netInterface>".
66  * If the route is a host route, the prefixLength input argument can be given as
67  * "" (i.e. null string) or "32".
68  * If it is a network route, it should then be specified as a prefix length, such as "16" for
69  * 255.255.0.0 or "24" for 255.255.255.0.
70  *
71  * The following is some sample code over how to use le_net_ChangeRoute():
72  * @code
73  * static le_dcs_ChannelRef_t myChannelRef;
74  *
75  * void ClientChannelChangeRoute
76  * (
77  * le_dcs_ChannelRef_t channelRef,
78  * char *ipAddr,
79  * char *prefixLength,
80  * bool isAdd
81  * )
82  * {
83  * if (LE_OK != le_net_ChangeRoute(channelRef, ipAddr, prefixLength, isAdd))
84  * {
85  * LE_ERROR("Failed to %s route to destination address %s/%s",
86  * isAdd ? "add" : "remove", ipAddr, prefixLength);
87  * }
88  * }
89  *
90  * void AddMyHostRoute
91  * (
92  * void
93  * )
94  * {
95  * ClientChannelChangeRoute(myChannelRef, "1.1.1.1", "", true);
96  * }
97  *
98  * void ChangeMySubnetRoute
99  * (
100  * bool isAdd
101  * )
102  * {
103  * ClientChannelChangeRoute(myChannelRef, "1.1.0.0", "16", isAdd);
104  * }
105  * @endcode
106  *
107  * @subsection le_net_APIDetails_DefaultGW Default Gateway Address
108  *
109  * The @c le_net interface provides four APIs for changing the default gateway address on a
110  * device. To back up the original setting before changing it, le_net_BackupDefaultGW() can be
111  * used. This will save both the default gateway address and the network interface on which it is
112  * installed. Later, when this original setting is to be restored, le_net_RestoreDefaultGW() can
113  * be used.
114  *
115  * To install a different default GW address on a device, le_net_SetDefaultGW() can be called
116  * with the channel reference of the channel provided, which assigned default gateway address will
117  * be used as the device's. Its assigned network interface will be the interface used for this
118  * configuration. To query the channel's default GW address prior to installing it on the device,
119  * le_net_GetDefaultGW() can be used.
120  *
121  * The following is some sample code over how to use le_net_RestoreDefaultGW() and
122  * le_net_BackupDefaultGW():
123  * @code
124  * static le_dcs_ChannelRef_t myChannelRef;
125  * static bool IsDefaultGWAdded = false;
126  *
127  * void ClientConfigNetwork
128  * (
129  * char *ipAddr,
130  * char *prefixLength,
131  * bool isAdd
132  * )
133  * {
134  * if (isAdd)
135  * {
136  * LE_INFO("Adding network configs for channel reference %p", myChannelRef);
137  * le_net_BackupDefaultGW();
138  * IsDefaultGWAdded = (le_net_SetDefaultGW(myChannelRef) == LE_OK);
139  * }
140  * else if (IsDefaultGWAdded)
141  * {
142  * LE_INFO("Restoring network configs for channel reference %p", myChannelRef);
143  * if (LE_OK != le_net_RestoreDefaultGW())
144  * {
145  * LE_ERROR("Failed to restore default gateway addresses");
146  * }
147  * IsDefaultGWAdded = false;
148  * }
149  *
150  * if (LE_OK != le_net_ChangeRoute(myChannelRef, ipAddr, prefixLength, isAdd))
151  * {
152  * LE_ERROR("Failed to %s route to destination %s/%s on channel with "
153  * "reference %p", isAdd ? "add : "remove", ipAddr, prefixLength,
154  * myChannelRef);
155  * }
156  * }
157  * @endcode
158  *
159  * @subsection le_net_APIDetails_DNS DNS Server Addresses
160  *
161  * There are three functions provided for setting a device's DNS server addresses and restoring
162  * them. When an application calls le_net_SetDNS() to provide a channel reference, @c le_net
163  * would query for the DNS server addresses assigned for this channel's use and add them into
164  * the device's global name server address table, which on a typical Linux-based device is at
165  * /etc/resolv.conf. The @c le_net interface would remember this lastly added set of DNS server
166  * address. If, for whatever reason, an application needs to know what a channel's DNS server
167  * address is, le_net_GetDNS() can be used.
168  *
169  * When the application is done with the channel, it needs to remove these previously added DNS
170  * server addresses from the device's global name server address table, which can be done via
171  * le_net_RestoreDNS(). With that called, @c le_net would retrive from its last archived
172  * set of DNS server addresses and seek to delete them from the global table.
173  *
174  * Note that for each data channel there could be zero to two DNS server addresses assigned. The
175  * @c le_net interface currently supports both IPv4 and IPv6.
176  *
177  * The following is some sample code over how to use le_net_SetDNS() and le_net_RestoreDNS():
178  * @code
179  * static bool isDnsAdded = false;
180  *
181  * void ClientConfigDNS
182  * (
183  * le_dcs_ChannelRef_t myChannelRef,
184  * bool isAdd
185  * )
186  * {
187  * if (isAdd)
188  * {
189  * LE_INFO("Adding DNS configs for channel reference %p", myChannelRef);
190  * isDnsAdded = (le_net_SetDNS(myChannelRef) == LE_OK);
191  * }
192  * else if (isDnsAdded)
193  * {
194  * LE_INFO("Restoring DNS configs for channel reference %p", myChannelRef);
195  * le_net_RestoreDNS();
196  * isDnsAdded = false;
197  * }
198  * }
199  * @endcode
200  *
201  * Copyright (C) Sierra Wireless Inc.
202  */
203 /**
204  * @file le_net_interface.h
205  *
206  * Legato @ref c_le_net include file.
207  *
208  * Copyright (C) Sierra Wireless Inc.
209  */
210 
211 #ifndef LE_NET_INTERFACE_H_INCLUDE_GUARD
212 #define LE_NET_INTERFACE_H_INCLUDE_GUARD
213 
214 
215 #include "legato.h"
216 
217 // Interface specific includes
218 #include "le_dcs_interface.h"
219 
220 // Internal includes for this interface
221 #include "le_net_common.h"
222 //--------------------------------------------------------------------------------------------------
223 /**
224  * Type for handler called when a server disconnects.
225  */
226 //--------------------------------------------------------------------------------------------------
227 typedef void (*le_net_DisconnectHandler_t)(void *);
228 
229 //--------------------------------------------------------------------------------------------------
230 /**
231  *
232  * Connect the current client thread to the service providing this API. Block until the service is
233  * available.
234  *
235  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
236  * called before any other functions in this API. Normally, ConnectService is automatically called
237  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
238  *
239  * This function is created automatically.
240  */
241 //--------------------------------------------------------------------------------------------------
243 (
244  void
245 );
246 
247 //--------------------------------------------------------------------------------------------------
248 /**
249  *
250  * Try to connect the current client thread to the service providing this API. Return with an error
251  * if the service is not available.
252  *
253  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
254  * called before any other functions in this API. Normally, ConnectService is automatically called
255  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
256  *
257  * This function is created automatically.
258  *
259  * @return
260  * - LE_OK if the client connected successfully to the service.
261  * - LE_UNAVAILABLE if the server is not currently offering the service to which the client is
262  * bound.
263  * - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
264  * - LE_COMM_ERROR if the Service Directory cannot be reached.
265  */
266 //--------------------------------------------------------------------------------------------------
268 (
269  void
270 );
271 
272 //--------------------------------------------------------------------------------------------------
273 /**
274  * Set handler called when server disconnection is detected.
275  *
276  * When a server connection is lost, call this handler then exit with LE_FATAL. If a program wants
277  * to continue without exiting, it should call longjmp() from inside the handler.
278  */
279 //--------------------------------------------------------------------------------------------------
281 (
282  le_net_DisconnectHandler_t disconnectHandler,
283  void *contextPtr
284 );
285 
286 //--------------------------------------------------------------------------------------------------
287 /**
288  *
289  * Disconnect the current client thread from the service providing this API.
290  *
291  * Normally, this function doesn't need to be called. After this function is called, there's no
292  * longer a connection to the service, and the functions in this API can't be used. For details, see
293  * @ref apiFilesC_client.
294  *
295  * This function is created automatically.
296  */
297 //--------------------------------------------------------------------------------------------------
299 (
300  void
301 );
302 
303 
304 //--------------------------------------------------------------------------------------------------
305 /**
306  * Structure used to communitcate a channel's DNS Server address
307  */
308 //--------------------------------------------------------------------------------------------------
309 
310 
311 //--------------------------------------------------------------------------------------------------
312 /**
313  * Structure used to communitcate a channel's Default Gateway
314  */
315 //--------------------------------------------------------------------------------------------------
316 
317 
318 //--------------------------------------------------------------------------------------------------
319 /**
320  * Add or remove a route on the given channel according to the input flag in the last argument for
321  * the given destination address its given subnet's mask prefix length.
322  *
323  * The channel reference in the first input argument identifies the network interface which a route
324  * is to be added onto or removed from. Whether the operation is an add or a remove depends on the
325  * isAdd boolean value of the last API input argument.
326  *
327  * The IP address and subnet input arguments specify the destination address and subnet for the
328  * route. If it is a network route, the formats used for them are the same as used in the Linux
329  * command "route add -net <ipAddr>/<prefixLength> dev <netInterface>". If the route is a
330  * host route, the prefixLength input argument should be given as "" (i.e. a null string).
331  *
332  * @note The prefixLength parameter used to take a subnet mask (255.255.255.0) for IPv4 and prefix
333  * length for IPv6. Now it only takes prefix length, although compatibility code is present
334  * to make it compatible with previous API declaration. Providing a subnet mask is however
335  * deprecated and the compatibility code will be removed in a latter version.
336  *
337  * @return
338  * - LE_OK upon success, otherwise another le_result_t failure code
339  */
340 //--------------------------------------------------------------------------------------------------
342 (
343  le_dcs_ChannelRef_t channelRef,
344  ///< [IN] the channel onto which the route change is made
345  const char* LE_NONNULL destAddr,
346  ///< [IN] Destination IP address for the route
347  const char* LE_NONNULL prefixLength,
348  ///< [IN] Destination's subnet prefix length
349  bool isAdd
350  ///< [IN] the change is to add (true) or delete (false)
351 );
352 
353 //--------------------------------------------------------------------------------------------------
354 /**
355  * Set the default GW addr for the given data channel retrieved from its technology
356  *
357  * @return
358  * - LE_OK upon success, otherwise LE_FAULT
359  */
360 //--------------------------------------------------------------------------------------------------
362 (
363  le_dcs_ChannelRef_t channelRef
364  ///< [IN] the channel on which interface its default GW
365  ///< addr is to be set
366 );
367 
368 //--------------------------------------------------------------------------------------------------
369 /**
370  * Get the default GW address for the given data channel.
371  *
372  * @note
373  * Accomodates dual-stack IPv4/IPv6 addresses. If the default GW address only is only IPv4 or
374  * IPv6, but not both, the unused field of "addr" will be nulled.
375  *
376  * @return
377  * - LE_OK upon success, otherwise LE_FAULT
378  */
379 //--------------------------------------------------------------------------------------------------
381 (
382  le_dcs_ChannelRef_t channelRef,
383  ///< [IN] Channel to retrieve GW addresses
384  le_net_DefaultGatewayAddresses_t * addrPtr
385  ///< [OUT] Channel's Default GW addresses
386 );
387 
388 //--------------------------------------------------------------------------------------------------
389 /**
390  * Backup the current default GW configs of the system, including both IPv4 and IPv6 as applicable.
391  * For each client application using this API to back up this system setting, only one backup copy
392  * is kept. When a client application makes a second call to this API, its first backup copy will
393  * be overwritten by the newer.
394  * Thus, le_net keeps one single backup copy per client application, and, thus, multiple backup
395  * copies altogether. They are kept in their LIFO (last-in-first-out) chronological order that
396  * the sequence for client applications to call le_net_RestoreDefaltGW() should be in the exact
397  * reverse order of their calling le_net_BackupDefaultGW() such that config backups and restorations
398  * happen in the correct LIFO manner.
399  */
400 //--------------------------------------------------------------------------------------------------
402 (
403  void
404 );
405 
406 //--------------------------------------------------------------------------------------------------
407 /**
408  * Restore the default GW configs of the system to the last backed up ones, including IPv4 and/or
409  * IPv6 depending on whether this same client application has called le_net_SetDefaultGW() to
410  * change the system's IPv4 and/or IPv6 configs or not. The le_net interface remembers it and
411  * perform config restoration only as necessary when le_net_RestoreDefaultGW() is called. When
412  * le_net_BackupDefaultGW() is called, both IPv4 and IPv6 default GW configs are archived when
413  * present.
414  * As le_net keeps one single backup copy per client application, and, thus, multiple backup
415  * copies altogether, they are kept in their LIFO (last-in-first-out) chronological order that
416  * the sequence for client applications to call le_net_RestoreDefaltGW() should be in the exact
417  * reverse order of their calling le_net_BackupDefaultGW() such that config backups and restorations
418  * happen in the correct LIFO manner.
419  * If these applications do not follow this order, the le_net interface will first generate a
420  * warning in the system log and then still go ahead to restore the configs as directed. These
421  * applications hold the responsibility for the resulting routing configs on the device.
422  */
423 //--------------------------------------------------------------------------------------------------
425 (
426  void
427 );
428 
429 //--------------------------------------------------------------------------------------------------
430 /**
431  * Set the DNS addresses for the given data channel retrieved from its technology
432  *
433  * @return
434  * - LE_OK upon success, otherwise LE_FAULT
435  */
436 //--------------------------------------------------------------------------------------------------
438 (
439  le_dcs_ChannelRef_t channelRef
440  ///< [IN] the channel from which the DNS addresses retrieved
441  ///< will be set into the system config
442 );
443 
444 //--------------------------------------------------------------------------------------------------
445 /**
446  * Get the DNS server addresses for the given data channel retrieved from its technology
447  *
448  * @note
449  * Can accomodate up to two dual-stack DNS server addresses. In the case that there are more
450  * than two server addresses, the first two addresses of each IP version will be returned. If
451  * there are fewer than two dual-stack addresses, or contain only one type of IPv4 or IPv6
452  * addresses, the unused portions of the passed structure will be nulled and returned.
453  *
454  * @return
455  * - LE_OK upon success, otherwise LE_FAULT
456  */
457 //--------------------------------------------------------------------------------------------------
459 (
460  le_dcs_ChannelRef_t channelRef,
461  ///< [IN] Channel to retrieve DNS server addresses
462  le_net_DnsServerAddresses_t * addrPtr
463  ///< [OUT] DNS server addresses
464 );
465 
466 //--------------------------------------------------------------------------------------------------
467 /**
468  * Remove the last added DNS addresses via the le_dcs_SetDNS API
469  */
470 //--------------------------------------------------------------------------------------------------
472 (
473  void
474 );
475 
476 #endif // LE_NET_INTERFACE_H_INCLUDE_GUARD
void le_net_RestoreDNS(void)
le_result_t le_net_TryConnectService(void)
void le_net_BackupDefaultGW(void)
le_result_t le_net_SetDNS(le_dcs_ChannelRef_t channelRef)
le_result_t
Definition: le_basics.h:35
LE_FULL_API void le_net_SetServerDisconnectHandler(le_net_DisconnectHandler_t disconnectHandler, void *contextPtr)
le_result_t le_net_GetDNS(le_dcs_ChannelRef_t channelRef, le_net_DnsServerAddresses_t *addrPtr)
void le_net_ConnectService(void)
le_result_t le_net_RestoreDefaultGW(void)
le_result_t le_net_SetDefaultGW(le_dcs_ChannelRef_t channelRef)
#define LE_FULL_API
Definition: le_apiFeatures.h:40
le_result_t le_net_ChangeRoute(le_dcs_ChannelRef_t channelRef, const char *LE_NONNULL destAddr, const char *LE_NONNULL prefixLength, bool isAdd)
void le_net_DisconnectService(void)
void(* le_net_DisconnectHandler_t)(void *)
Definition: le_net_interface.h:227
le_result_t le_net_GetDefaultGW(le_dcs_ChannelRef_t channelRef, le_net_DefaultGatewayAddresses_t *addrPtr)