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