le_mdc_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_mdc Modem Data Control
14  *
15  * @ref le_mdc_interface.h "API Reference"
16  *
17  * <HR>
18  *
19  * A data session is useful for applications that need to send or receive data over a network
20  * where SMS messages are insufficient. To start a data session, a data profile must
21  * be configured as specified by the target network.
22  *
23  * The Modem Data Control (mdc) API is used to manage data profiles and data sessions.
24  *
25  * @section le_mdc_binding IPC interfaces binding
26  *
27  * All the functions of this API are provided by the @b modemService service.
28  *
29  * Here's a code sample binding to modem services:
30  * @verbatim
31  bindings:
32  {
33  clientExe.clientComponent.le_mdc -> modemService.le_mdc
34  }
35  @endverbatim
36  *
37  * @section le_mdc_profile Data Profiles
38  *
39  * If a pre-defined data profile has been configured then this profile can
40  * be loaded using le_mdc_GetProfile().
41  * le_mdc_GetProfile() must be called with @c LE_MDC_DEFAULT_PROFILE to retrieve the default index
42  * used by the modem for data connection.
43  * le_mdc_GetProfile() must be called with @c LE_MDC_SIMTOOLKIT_BIP_DEFAULT_PROFILE to retrieve the
44  * default index used by the modem for Bearer Independent Protocol (BIP).
45  * The maximum number of data profiles supported is modem dependent and can be retrieved with
46  * le_mdc_NumProfiles().
47  *
48  * @note le_mdc_GetProfile() creates a new profile if the profile's index can't be found.
49  *
50  * @warning 0 is not a valid index.
51  *
52  * A pre-defined data profile can be retrieved using le_mdc_GetProfileFromApn() thanks to its
53  * APN.
54  *
55  * A default APN can be set for a defined profile with le_mdc_SetDefaultAPN(), based on the SIM
56  * identification number (ICCID). If no match is found in the database using the ICCID, the search
57  * falls back on the home network (MCC/MNC) to determine the default APN.
58  *
59  * @warning Ensure to check the list of supported data profiles for your specific platform.
60  *
61  * The following data profile parameters can be retrieved:
62  * - Packet Data Protocol using le_mdc_GetPDP().
63  * - Access Point Name using le_mdc_GetAPN().
64  * - Authentication settings using le_mdc_GetAuthentication().
65  *
66  * The following data profile parameters can be set:
67  * - Packet Data Protocol using le_mdc_SetPDP().
68  * - Access Point Name using le_mdc_SetAPN().
69  * - Authentication settings using le_mdc_SetAuthentication().
70  *
71  * @warning The maximum APN length might be limited by the platform.
72  * Please refer to the platform documentation.
73  *
74  * A sample code can be seen in the following page:
75  * - @subpage c_mdcDataProfiles
76  *
77  * @section le_mdc_session Data Sessions
78  *
79  * @subsection le_mdc_session_MO Mobile Originated (MO-PDP context activation)
80  *
81  * le_mdc_MapProfileOnNetworkInterface() may be used to map a data session with a network interface.
82  * To take effect, this API has to be called before starting the data session. Otherwise, the
83  * mapping will be taken into account at the next start of the data profile.
84  *
85  * A data session can be started using le_mdc_StartSession(). To start a data session, a
86  * data profile must be created and written to the modem, or an existing data profile
87  * can be used. A data session can be stopped using le_mdc_StopSession(). The number of
88  * simultaneous data sessions supported is dependent on the modem, but cannot be more than the
89  * maximum number of supported profiles.
90  *
91  * A data session can be started using le_mdc_StartSessionAsync() and stopped using
92  * le_mdc_StopSessionAsync(). These functions are not blocking. The response will be returned
93  * with the @c le_mdc_SessionHandlerFunc_t handler function.
94  *
95  * The current state of a data session can be queried using le_mdc_GetSessionState(). An application
96  * can also a register handler to be notified when the session state changes. The handler
97  * can be managed using le_mdc_AddSessionStateHandler() and le_mdc_RemoveSessionStateHandler().
98  *
99  * @subsection le_mdc_session_MT Mobile Terminated (MT-PDP context activation)
100  * To be notified by the MT-PDP context request, the application has to subscribe to the state
101  * handler using le_mdc_AddMtPdpSessionStateHandler().
102  * When the incoming MT-PDP context request is notified,
103  * the application takes responsibility to trigger the data session for that MT PDP request using
104  * le_mdc_StartSession(). That data session can be stopped using le_mdc_StopSession().
105  *
106  * The network interface settings of that MT-PDP context can be retrieved using the provided
107  * Data Profile.
108  * Please refer to @ref le_mdc_session_networkItf.
109  *
110  * A data session can be rejected using le_mdc_RejectMtPdpSession().
111  * The number of simultaneous data sessions supported is dependent on the modem,
112  * but cannot be more than the maximum number of supported profiles.
113  *
114  * The handler can be released using le_mdc_RemoveMtPdpSessionStateHandler().
115  *
116  * @warning The MT-PDP context activation feature is not supported on all platforms. Please refer to
117  * @ref MT-PDP_context section for full details.
118  *
119  * @subsection le_mdc_session_networkItf Network interface settings
120  * Once a data session starts, a Linux network interface is created. It's the application's
121  * responsibility to configure the network interface, usually through a DHCP client. Query the
122  * interface name using le_mdc_GetInterfaceName(). The IP Preference can be checked with
123  * le_mdc_IsIPv4() or le_mdc_IsIPv6() when the profile is connected. The IP address for the
124  * current data session
125  * can be retrieved by le_mdc_GetIPv4Address() or le_mdc_GetIPv6Address(). The Gateway and
126  * DNS
127  * addresses can be retrieved using le_mdc_GetIPv4GatewayAddress(),
128  * le_mdc_GetIPv4DNSAddresses() or le_mdc_GetIPv6GatewayAddress(), le_mdc_GetIPv6DNSAddresses().
129  * The Access Point Name can be retrieved by le_mdc_GetAPN(). The Data bearer
130  * Technology can be retrieved by le_mdc_GetDataBearerTechnology().
131  *
132  * le_mdc_GetDisconnectionReason() or le_mdc_GetPlatformSpecificDisconnectionCode() let you get
133  * the reason for disconnection of data session by retrieving the call end failure code
134  * from @c le_mdc_ProfileRef_t.
135  *
136  * le_mdc_GetPlatformSpecificFailureConnectionReason() let you get the data session connection
137  * failure reason by retrieving the call connection failure code and type from
138  * @c le_mdc_ProfileRef_t.
139  *
140  * Please refer to @ref platformConstraintsSpecificErrorCodes for platform specific
141  * disconnection code description.
142  *
143  * A sample code can be seen in the following page:
144  * - @subpage c_mdcDataSessions
145  *
146  * The following extended functions should be used to get the disconnection reason instead.
147  * A pdpType parameter is required to specify which session's(IPv4 or IPv6 session) disconnect
148  * reason to get for IPv4v6 mode. For IPv4 and IPv6 mode, the pdpType is ignored because there
149  * is only one session.
150  * - le_mdc_GetDisconnectionReasonExt()
151  * - le_mdc_GetPlatformSpecificDisconnectionCodeExt()
152  * - le_mdc_GetPlatformSpecificFailureConnectionReasonExt()
153  *
154  * @section le_mdc_dataStatistics Data Statistics
155  *
156  * The amount of received and transmitted data can be retrieved through le_mdc_GetBytesCounters().
157  * The returned values correspond to the number of received and transmitted
158  * bytes since the last call to le_mdc_ResetBytesCounter().
159  *
160  * The data statistics collection can be enabled with le_mdc_StartBytesCounter() and disabled
161  * without resetting the counters with le_mdc_StopBytesCounter().
162  *
163  * @note The data statistics collection activation and the data counters are persistent even after
164  * a reboot of the platform.
165  *
166  * A sample code can be seen in the following page:
167  * - @subpage c_mdcDataStatistics
168  *
169  * <HR>
170  *
171  * Copyright (C) Sierra Wireless Inc.
172  */
173 /**
174  * @page c_mdcDataProfiles Sample code for Data Profiles
175  *
176  * @snippet "apps/test/modemServices/mdc/mdcIntegrationTest/mdcTestComp/mdcTest.c" Profiles
177  */
178 /**
179  * @page c_mdcDataSessions Sample code for network interface settings
180  *
181  * @snippet "apps/test/modemServices/mdc/mdcIntegrationTest/mdcTestComp/mdcTest.c" Sessions
182  */
183 /**
184  * @page c_mdcDataStatistics Sample code for Data Statistics
185  *
186  * @snippet "apps/test/modemServices/mdc/mdcIntegrationTest/mdcTestComp/mdcTest.c" Statistics
187  */
188 /**
189  * @file le_mdc_interface.h
190  *
191  * Legato @ref c_mdc include file.
192  *
193  * Copyright (C) Sierra Wireless Inc.
194  */
195 
196 #ifndef LE_MDC_INTERFACE_H_INCLUDE_GUARD
197 #define LE_MDC_INTERFACE_H_INCLUDE_GUARD
198 
199 
200 #include "legato.h"
201 
202 // Internal includes for this interface
203 #include "le_mdc_common.h"
204 //--------------------------------------------------------------------------------------------------
205 /**
206  * Type for handler called when a server disconnects.
207  */
208 //--------------------------------------------------------------------------------------------------
209 typedef void (*le_mdc_DisconnectHandler_t)(void *);
210 
211 //--------------------------------------------------------------------------------------------------
212 /**
213  *
214  * Connect the current client thread to the service providing this API. Block until the service is
215  * available.
216  *
217  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
218  * called before any other functions in this API. Normally, ConnectService is automatically called
219  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
220  *
221  * This function is created automatically.
222  */
223 //--------------------------------------------------------------------------------------------------
225 (
226  void
227 );
228 
229 //--------------------------------------------------------------------------------------------------
230 /**
231  *
232  * Try to connect the current client thread to the service providing this API. Return with an error
233  * if the service is not 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  * @return
242  * - LE_OK if the client connected successfully to the service.
243  * - LE_UNAVAILABLE if the server is not currently offering the service to which the client is
244  * bound.
245  * - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
246  * - LE_COMM_ERROR if the Service Directory cannot be reached.
247  */
248 //--------------------------------------------------------------------------------------------------
250 (
251  void
252 );
253 
254 //--------------------------------------------------------------------------------------------------
255 /**
256  * Set handler called when server disconnection is detected.
257  *
258  * When a server connection is lost, call this handler then exit with LE_FATAL. If a program wants
259  * to continue without exiting, it should call longjmp() from inside the handler.
260  */
261 //--------------------------------------------------------------------------------------------------
263 (
264  le_mdc_DisconnectHandler_t disconnectHandler,
265  void *contextPtr
266 );
267 
268 //--------------------------------------------------------------------------------------------------
269 /**
270  *
271  * Disconnect the current client thread from the service providing this API.
272  *
273  * Normally, this function doesn't need to be called. After this function is called, there's no
274  * longer a connection to the service, and the functions in this API can't be used. For details, see
275  * @ref apiFilesC_client.
276  *
277  * This function is created automatically.
278  */
279 //--------------------------------------------------------------------------------------------------
281 (
282  void
283 );
284 
285 
286 //--------------------------------------------------------------------------------------------------
287 /**
288  * Reference to a modem data connection profile.
289  */
290 //--------------------------------------------------------------------------------------------------
291 
292 
293 //--------------------------------------------------------------------------------------------------
294 /**
295  * Enumeration of data bearer technologies.
296  */
297 //--------------------------------------------------------------------------------------------------
298 
299 
300 //--------------------------------------------------------------------------------------------------
301 /**
302  * Enumeration of Packet Data Protocol.
303  */
304 //--------------------------------------------------------------------------------------------------
305 
306 
307 //--------------------------------------------------------------------------------------------------
308 /**
309  * Authentication bit mask.
310  */
311 //--------------------------------------------------------------------------------------------------
312 
313 
314 //--------------------------------------------------------------------------------------------------
315 /**
316  * Enumeration of connection state.
317  */
318 //--------------------------------------------------------------------------------------------------
319 
320 
321 //--------------------------------------------------------------------------------------------------
322 /**
323  * Enumeration of the possible reasons for the disconnection.
324  */
325 //--------------------------------------------------------------------------------------------------
326 
327 
328 //--------------------------------------------------------------------------------------------------
329 /**
330  * Handler for Data session connection state changes.
331  */
332 //--------------------------------------------------------------------------------------------------
333 
334 
335 //--------------------------------------------------------------------------------------------------
336 /**
337  * Handler for MT-PDP Data session connection state changes.
338  */
339 //--------------------------------------------------------------------------------------------------
340 
341 
342 //--------------------------------------------------------------------------------------------------
343 /**
344  * Handler for asynchronous session start and stop result response
345  *
346  */
347 //--------------------------------------------------------------------------------------------------
348 
349 
350 //--------------------------------------------------------------------------------------------------
351 /**
352  * Reference type used by Add/Remove functions for EVENT 'le_mdc_SessionState'
353  */
354 //--------------------------------------------------------------------------------------------------
355 
356 
357 //--------------------------------------------------------------------------------------------------
358 /**
359  * Reference type used by Add/Remove functions for EVENT 'le_mdc_MtPdpSessionState'
360  */
361 //--------------------------------------------------------------------------------------------------
362 
363 
364 //--------------------------------------------------------------------------------------------------
365 /**
366  * This is the structure with info about a given cellular data profile
367  */
368 //--------------------------------------------------------------------------------------------------
369 
370 
371 //--------------------------------------------------------------------------------------------------
372 /**
373  * Add handler function for EVENT 'le_mdc_SessionState'
374  *
375  * This event provides information on data session connection state changes for the given profileRef.
376  *
377  */
378 //--------------------------------------------------------------------------------------------------
379 le_mdc_SessionStateHandlerRef_t le_mdc_AddSessionStateHandler
380 (
381  le_mdc_ProfileRef_t profileRef,
382  ///< [IN] The profile object of interest
383  le_mdc_SessionStateHandlerFunc_t handlerPtr,
384  ///< [IN]
385  void* contextPtr
386  ///< [IN]
387 );
388 
389 //--------------------------------------------------------------------------------------------------
390 /**
391  * Remove handler function for EVENT 'le_mdc_SessionState'
392  */
393 //--------------------------------------------------------------------------------------------------
395 (
396  le_mdc_SessionStateHandlerRef_t handlerRef
397  ///< [IN]
398 );
399 
400 //--------------------------------------------------------------------------------------------------
401 /**
402  * Add handler function for EVENT 'le_mdc_MtPdpSessionState'
403  *
404  * This event provides information on data session connection state changes for the given profileRef.
405  *
406  */
407 //--------------------------------------------------------------------------------------------------
408 le_mdc_MtPdpSessionStateHandlerRef_t le_mdc_AddMtPdpSessionStateHandler
409 (
410  le_mdc_SessionStateHandlerFunc_t handlerPtr,
411  ///< [IN]
412  void* contextPtr
413  ///< [IN]
414 );
415 
416 //--------------------------------------------------------------------------------------------------
417 /**
418  * Remove handler function for EVENT 'le_mdc_MtPdpSessionState'
419  */
420 //--------------------------------------------------------------------------------------------------
422 (
423  le_mdc_MtPdpSessionStateHandlerRef_t handlerRef
424  ///< [IN]
425 );
426 
427 //--------------------------------------------------------------------------------------------------
428 /**
429  * Get Profile Reference for index
430  *
431  * @note Create a new profile if the profile's index can't be found.
432  *
433  * @warning 0 is not a valid index.
434  *
435  * @warning Ensure to check the list of supported data profiles for your specific platform.
436  *
437  * @return
438  * - Reference to the data profile
439  * - NULL if the profile index does not exist
440  */
441 //--------------------------------------------------------------------------------------------------
442 le_mdc_ProfileRef_t le_mdc_GetProfile
443 (
444  uint32_t index
445  ///< [IN] index of the profile.
446 );
447 
448 //--------------------------------------------------------------------------------------------------
449 /**
450  * Get the index for the given Profile.
451  *
452  * @return
453  * - index of the profile in the modem
454  *
455  * @note
456  * The process exits, if an invalid profile object is given
457  */
458 //--------------------------------------------------------------------------------------------------
459 uint32_t le_mdc_GetProfileIndex
460 (
461  le_mdc_ProfileRef_t profileRef
462  ///< [IN] Query this profile object
463 );
464 
465 //--------------------------------------------------------------------------------------------------
466 /**
467  * Start profile data session.
468  *
469  * @return
470  * - LE_OK on success
471  * - LE_BAD_PARAMETER if input parameter is incorrect
472  * - LE_DUPLICATE if the data session is already connected for the given profile
473  * - LE_TIMEOUT for session start timeout
474  * - LE_FAULT for other failures
475  *
476  * @note
477  * The process exits, if an invalid profile object is given
478  */
479 //--------------------------------------------------------------------------------------------------
481 (
482  le_mdc_ProfileRef_t profileRef
483  ///< [IN] Start data session for this profile object
484 );
485 
486 //--------------------------------------------------------------------------------------------------
487 /**
488  * Start profile data session.
489  *
490  * @note
491  * The process exits, if an invalid profile object is given
492  */
493 //--------------------------------------------------------------------------------------------------
495 (
496  le_mdc_ProfileRef_t profileRef,
497  ///< [IN] Start data session for this profile object
498  le_mdc_SessionHandlerFunc_t handlerPtr,
499  ///< [IN] Handler for start data session result
500  void* contextPtr
501  ///< [IN]
502 );
503 
504 //--------------------------------------------------------------------------------------------------
505 /**
506  * Stop profile data session.
507  *
508  * @return
509  * - LE_OK on success
510  * - LE_BAD_PARAMETER if the input parameter is not valid
511  * - LE_FAULT for other failures
512  *
513  * @note
514  * The process exits, if an invalid profile object is given
515  *
516  * @warning The MT-PDP context activation feature is not supported on all platforms. Please refer to
517  * @ref MT-PDP_context section for full details.
518  */
519 //--------------------------------------------------------------------------------------------------
521 (
522  le_mdc_ProfileRef_t profileRef
523  ///< [IN] Stop data session for this profile object
524 );
525 
526 //--------------------------------------------------------------------------------------------------
527 /**
528  * Stop profile data session.
529  *
530  * @note
531  * The process exits, if an invalid profile object is given
532  */
533 //--------------------------------------------------------------------------------------------------
535 (
536  le_mdc_ProfileRef_t profileRef,
537  ///< [IN] Stop data session for this profile object
538  le_mdc_SessionHandlerFunc_t handlerPtr,
539  ///< [IN] Handler for stop data session result
540  void* contextPtr
541  ///< [IN]
542 );
543 
544 //--------------------------------------------------------------------------------------------------
545 /**
546  * Reject MT-PDP profile data session.
547  *
548  * @return
549  * - LE_OK on success
550  * - LE_BAD_PARAMETER if the input parameter is not valid
551  * - LE_UNSUPPORTED if not supported by the target
552  * - LE_FAULT for other failures
553  *
554  * @note
555  * The process exits, if an invalid profile object is given
556  *
557  * @warning The MT-PDP context activation feature is not supported on all platforms. Please refer to
558  * @ref MT-PDP_context section for full details.
559  */
560 //--------------------------------------------------------------------------------------------------
562 (
563  le_mdc_ProfileRef_t profileRef
564  ///< [IN] Reject MT-PDP data session for this profile object
565 );
566 
567 //--------------------------------------------------------------------------------------------------
568 /**
569  * Get the current data session state.
570  *
571  * @return
572  * - LE_OK on success
573  * - LE_BAD_PARAMETER if an input parameter is not valid
574  * - LE_FAULT on failure
575  *
576  * @note
577  * The process exits, if an invalid profile object is given
578  */
579 //--------------------------------------------------------------------------------------------------
581 (
582  le_mdc_ProfileRef_t profileRef,
583  ///< [IN] Query this profile object
584  le_mdc_ConState_t* connectionStatePtr
585  ///< [OUT] The data session state
586 );
587 
588 //--------------------------------------------------------------------------------------------------
589 /**
590  * Get the network interface name, if the data session is connected.
591  *
592  * @return
593  * - LE_OK on success
594  * - LE_OVERFLOW if the interface name would not fit in interfaceNameStr
595  * - LE_FAULT for all other errors
596  *
597  * @note
598  * The process exits, if an invalid profile object is given
599  */
600 //--------------------------------------------------------------------------------------------------
602 (
603  le_mdc_ProfileRef_t profileRef,
604  ///< [IN] Query this profile object
605  char* interfaceName,
606  ///< [OUT] The name of the network interface
607  size_t interfaceNameSize
608  ///< [IN]
609 );
610 
611 //--------------------------------------------------------------------------------------------------
612 /**
613  * Get the IPv4 address for the given profile, if the data session is connected and has an IPv4
614  * address.
615  *
616  * @return
617  * - LE_OK on success
618  * - LE_OVERFLOW if the IP address would not fit in ipAddrStr
619  * - LE_FAULT for all other errors
620  *
621  * @note
622  * The process exits, if an invalid profile object is given
623  */
624 //--------------------------------------------------------------------------------------------------
626 (
627  le_mdc_ProfileRef_t profileRef,
628  ///< [IN] Query this profile object
629  char* ipAddr,
630  ///< [OUT] The IP address in dotted format
631  size_t ipAddrSize
632  ///< [IN]
633 );
634 
635 //--------------------------------------------------------------------------------------------------
636 /**
637  * Get the gateway IPv4 address for the given profile, if the data session is connected and has an
638  * IPv4 address.
639  *
640  * @return
641  * - LE_OK on success
642  * - LE_OVERFLOW if the IP address would not fit in gatewayAddrStr
643  * - LE_FAULT for all other errors
644  *
645  * @note
646  * The process exits, if an invalid profile object is given
647  */
648 //--------------------------------------------------------------------------------------------------
650 (
651  le_mdc_ProfileRef_t profileRef,
652  ///< [IN] Query this profile object
653  char* gatewayAddr,
654  ///< [OUT] The gateway IP address in dotted format
655  size_t gatewayAddrSize
656  ///< [IN]
657 );
658 
659 //--------------------------------------------------------------------------------------------------
660 /**
661  * Get the primary/secondary DNS v4 addresses for the given profile, if the data session is
662  * connected and has an IPv4 address.
663  *
664  * @return
665  * - LE_OK on success
666  * - LE_OVERFLOW if the IP address would not fit in buffer
667  * - LE_FAULT for all other errors
668  *
669  * @note
670  * - If only one DNS address is available, then it will be returned, and an empty string will
671  * be returned for the unavailable address
672  * - The process exits, if an invalid profile object is given
673  */
674 //--------------------------------------------------------------------------------------------------
676 (
677  le_mdc_ProfileRef_t profileRef,
678  ///< [IN] Query this profile object
679  char* dns1AddrStr,
680  ///< [OUT] The primary DNS IP address in dotted format
681  size_t dns1AddrStrSize,
682  ///< [IN]
683  char* dns2AddrStr,
684  ///< [OUT] The secondary DNS IP address in dotted format
685  size_t dns2AddrStrSize
686  ///< [IN]
687 );
688 
689 //--------------------------------------------------------------------------------------------------
690 /**
691  * Get the IPv6 address for the given profile, if the data session is connected and has an IPv6
692  * address.
693  *
694  * @return
695  * - LE_OK on success
696  * - LE_OVERFLOW if the IP address would not fit in ipAddrStr
697  * - LE_FAULT for all other errors
698  *
699  * @note
700  * The process exits, if an invalid profile object is given
701  */
702 //--------------------------------------------------------------------------------------------------
704 (
705  le_mdc_ProfileRef_t profileRef,
706  ///< [IN] Query this profile object
707  char* ipAddr,
708  ///< [OUT] The IP address in dotted format
709  size_t ipAddrSize
710  ///< [IN]
711 );
712 
713 //--------------------------------------------------------------------------------------------------
714 /**
715  * Get the gateway IPv6 address for the given profile, if the data session is connected and has an
716  * IPv6 address.
717  *
718  * @return
719  * - LE_OK on success
720  * - LE_OVERFLOW if the IP address would not fit in gatewayAddrStr
721  * - LE_FAULT for all other errors
722  *
723  * @note
724  * The process exits, if an invalid profile object is given
725  */
726 //--------------------------------------------------------------------------------------------------
728 (
729  le_mdc_ProfileRef_t profileRef,
730  ///< [IN] Query this profile object
731  char* gatewayAddr,
732  ///< [OUT] The gateway IP address in dotted format
733  size_t gatewayAddrSize
734  ///< [IN]
735 );
736 
737 //--------------------------------------------------------------------------------------------------
738 /**
739  * Get the primary/secondary DNS v6 addresses, if the data session is connected and has an IPv6
740  * address.
741  *
742  * @return
743  * - LE_OK on success
744  * - LE_OVERFLOW if the IP address can't fit in buffer
745  * - LE_FAULT for all other errors
746  *
747  * @note
748  * - If only one DNS address is available, it will be returned, and an empty string will
749  * be returned for the unavailable address.
750  * - The process exits, if an invalid profile object is given
751  */
752 //--------------------------------------------------------------------------------------------------
754 (
755  le_mdc_ProfileRef_t profileRef,
756  ///< [IN] Query this profile object
757  char* dns1AddrStr,
758  ///< [OUT] The primary DNS IP address in dotted format
759  size_t dns1AddrStrSize,
760  ///< [IN]
761  char* dns2AddrStr,
762  ///< [OUT] The secondary DNS IP address in dotted format
763  size_t dns2AddrStrSize
764  ///< [IN]
765 );
766 
767 //--------------------------------------------------------------------------------------------------
768 /**
769  * Allow the caller to know if the given profile is actually supporting IPv4, if the data session
770  * is connected.
771  *
772  * @return TRUE if PDP type is IPv4, FALSE otherwise.
773  *
774  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
775  * function will not return.
776  */
777 //--------------------------------------------------------------------------------------------------
778 bool le_mdc_IsIPv4
779 (
780  le_mdc_ProfileRef_t profileRef
781  ///< [IN] Query this profile object
782 );
783 
784 //--------------------------------------------------------------------------------------------------
785 /**
786  * Allow the caller to know if the given profile is actually supporting IPv6, if the data session
787  * is connected.
788  *
789  * @return TRUE if PDP type is IPv6, FALSE otherwise.
790  *
791  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
792  * function will not return.
793  */
794 //--------------------------------------------------------------------------------------------------
795 bool le_mdc_IsIPv6
796 (
797  le_mdc_ProfileRef_t profileRef
798  ///< [IN] Query this profile object
799 );
800 
801 //--------------------------------------------------------------------------------------------------
802 /**
803  * Get the Data Bearer Technology for the given profile, if the data session is connected.
804  *
805  * @return
806  * - LE_OK on success
807  * - LE_FAULT for all other errors
808  *
809  * @note
810  * The process exits, if an invalid profile object is given
811  */
812 //--------------------------------------------------------------------------------------------------
814 (
815  le_mdc_ProfileRef_t profileRef,
816  ///< [IN] Query this profile object
817  le_mdc_DataBearerTechnology_t* downlinkDataBearerTechPtrPtr,
818  ///< [OUT] downlink data bearer technology
819  le_mdc_DataBearerTechnology_t* uplinkDataBearerTechPtrPtr
820  ///< [OUT] uplink data bearer technology
821 );
822 
823 //--------------------------------------------------------------------------------------------------
824 /**
825  * Get number of bytes received/transmitted without error since the last reset.
826  *
827  * @return
828  * - LE_OK on success
829  * - LE_FAULT for all other errors
830  *
831  * @note
832  * - The process exits, if an invalid pointer is given
833  */
834 //--------------------------------------------------------------------------------------------------
836 (
837  uint64_t* rxBytesPtr,
838  ///< [OUT] bytes amount received since the last counter reset
839  uint64_t* txBytesPtr
840  ///< [OUT] bytes amount transmitted since the last counter reset
841 );
842 
843 //--------------------------------------------------------------------------------------------------
844 /**
845  * Reset received/transmitted data flow statistics
846  *
847  * @return
848  * - LE_OK on success
849  * - LE_FAULT for all other errors
850  */
851 //--------------------------------------------------------------------------------------------------
853 (
854  void
855 );
856 
857 //--------------------------------------------------------------------------------------------------
858 /**
859  * Stop collecting received/transmitted data flow statistics
860  *
861  * @return
862  * - LE_OK on success
863  * - LE_FAULT for all other errors
864  */
865 //--------------------------------------------------------------------------------------------------
867 (
868  void
869 );
870 
871 //--------------------------------------------------------------------------------------------------
872 /**
873  * Start collecting received/transmitted data flow statistics
874  *
875  * @return
876  * - LE_OK on success
877  * - LE_FAULT for all other errors
878  */
879 //--------------------------------------------------------------------------------------------------
881 (
882  void
883 );
884 
885 //--------------------------------------------------------------------------------------------------
886 /**
887  * Set the Packet Data Protocol (PDP) for the given profile.
888  *
889  * @return
890  * - LE_OK on success
891  * - LE_BAD_PARAMETER if the PDP is not supported
892  * - LE_FAULT if the data session is currently connected for the given profile
893  *
894  * @note
895  * The process exits, if an invalid profile object is given
896  */
897 //--------------------------------------------------------------------------------------------------
899 (
900  le_mdc_ProfileRef_t profileRef,
901  ///< [IN] Query this profile object
902  le_mdc_Pdp_t pdp
903  ///< [IN] The Packet Data Protocol
904 );
905 
906 //--------------------------------------------------------------------------------------------------
907 /**
908  * Get the Packet Data Protocol (PDP) for the given profile.
909  *
910  * @return
911  * - packet data protocol value
912  *
913  * @note
914  * The process exits, if an invalid profile object is given
915  */
916 //--------------------------------------------------------------------------------------------------
917 le_mdc_Pdp_t le_mdc_GetPDP
918 (
919  le_mdc_ProfileRef_t profileRef
920  ///< [IN] Query this profile object
921 );
922 
923 //--------------------------------------------------------------------------------------------------
924 /**
925  * Set the Access Point Name (APN) for the given profile.
926  *
927  * The APN must be an ASCII string.
928  *
929  * @return
930  * - LE_OK on success
931  * - LE_BAD_PARAMETER if an input parameter is not valid
932  * - LE_FAULT if the data session is currently connected for the given profile
933  *
934  * @note If APN is too long (max APN_NAME_MAX_LEN digits), it is a fatal error, the
935  * function will not return.
936  *
937  * @warning The maximum APN length might be limited by the platform.
938  * Please refer to the platform documentation @ref platformConstraintsMdc.
939  *
940  * @note
941  * The process exits, if an invalid profile object is given
942  */
943 //--------------------------------------------------------------------------------------------------
945 (
946  le_mdc_ProfileRef_t profileRef,
947  ///< [IN] Query this profile object
948  const char* LE_NONNULL apnStr
949  ///< [IN] The Access Point Name
950 );
951 
952 //--------------------------------------------------------------------------------------------------
953 /**
954  * Set the Access Point Name (APN) for the given profile according to the SIM identification
955  * number (ICCID). If no APN is found using the ICCID, fall back on the home network (MCC/MNC)
956  * to determine the default APN.
957  *
958  * @return
959  * - LE_OK on success
960  * - LE_BAD_PARAMETER if an input parameter is not valid
961  * - LE_FAULT for all other errors
962  *
963  * @note
964  * The process exits if an invalid profile object is given
965  */
966 //--------------------------------------------------------------------------------------------------
968 (
969  le_mdc_ProfileRef_t profileRef
970  ///< [IN] Query this profile object
971 );
972 
973 //--------------------------------------------------------------------------------------------------
974 /**
975  * Get the Access Point Name (APN) for the given profile.
976  *
977  * @return
978  * - LE_OK on success
979  * - LE_BAD_PARAMETER if an input parameter is not valid
980  * - LE_OVERFLOW if the APN is is too long
981  * - LE_FAULT on failed
982  *
983  * @note
984  * The process exits, if an invalid profile object is given
985  */
986 //--------------------------------------------------------------------------------------------------
988 (
989  le_mdc_ProfileRef_t profileRef,
990  ///< [IN] Query this profile object
991  char* apnStr,
992  ///< [OUT] The Access Point Name
993  size_t apnStrSize
994  ///< [IN]
995 );
996 
997 //--------------------------------------------------------------------------------------------------
998 /**
999  * Set authentication property
1000  *
1001  * @return
1002  * - LE_OK on success
1003  *
1004  * @note
1005  * - The process exits, if userName or password are NULL when type is not PA_MDC_AUTH_NONE
1006  * - The process exits, if an invalid profile object is given
1007  * @note If userName is too long (max USER_NAME_MAX_LEN digits), it is a fatal error, the
1008  * function will not return.
1009  * @note If password is too long (max PASSWORD_NAME_MAX_LEN digits), it is a fatal error, the
1010  * function will not return.
1011  * @note Both PAP and CHAP authentication can be set for 3GPP network: in this case, the device
1012  * decides which authentication procedure is performed. For example, the device can have a
1013  * policy to select the most secure authentication mechanism.
1014  *
1015  */
1016 //--------------------------------------------------------------------------------------------------
1018 (
1019  le_mdc_ProfileRef_t profileRef,
1020  ///< [IN] Query this profile object
1021  le_mdc_Auth_t type,
1022  ///< [IN] Authentication type
1023  const char* LE_NONNULL userName,
1024  ///< [IN] UserName used by authentication
1025  const char* LE_NONNULL password
1026  ///< [IN] Password used by authentication
1027 );
1028 
1029 //--------------------------------------------------------------------------------------------------
1030 /**
1031  * Get authentication property
1032  *
1033  * @return
1034  * - LE_OK on success
1035  * - LE_BAD_PARAMETER if an input parameter is not valid
1036  * - LE_OVERFLOW userName or password are too small
1037  * - LE_FAULT on failed
1038  *
1039  * @note
1040  * The process exits, if an invalid profile object is given
1041  */
1042 //--------------------------------------------------------------------------------------------------
1044 (
1045  le_mdc_ProfileRef_t profileRef,
1046  ///< [IN] Query this profile object
1047  le_mdc_Auth_t* typePtr,
1048  ///< [OUT] Authentication type
1049  char* userName,
1050  ///< [OUT] UserName used by authentication
1051  size_t userNameSize,
1052  ///< [IN]
1053  char* password,
1054  ///< [OUT] Password used by authentication
1055  size_t passwordSize
1056  ///< [IN]
1057 );
1058 
1059 //--------------------------------------------------------------------------------------------------
1060 /**
1061  * Get the number of profiles on the modem.
1062  *
1063  * @return
1064  * - number of profiles existing on modem
1065  */
1066 //--------------------------------------------------------------------------------------------------
1067 uint32_t le_mdc_NumProfiles
1068 (
1069  void
1070 );
1071 
1072 //--------------------------------------------------------------------------------------------------
1073 /**
1074  * Get a profile selected by its APN
1075  *
1076  * @return
1077  * - LE_OK on success
1078  * - LE_BAD_PARAMETER if an input parameter is not valid
1079  * - LE_NOT_FOUND if the requested APN is not found
1080  */
1081 //--------------------------------------------------------------------------------------------------
1083 (
1084  const char* LE_NONNULL apnStr,
1085  ///< [IN] The Access Point Name
1086  le_mdc_ProfileRef_t* profileRefPtr
1087  ///< [OUT] profile reference
1088 );
1089 
1090 //--------------------------------------------------------------------------------------------------
1091 /**
1092  * Called to get the disconnection reason.
1093  *
1094  * @return The disconnection reason.
1095  *
1096  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
1097  * function will not return.
1098  *
1099  * @deprecated This function is deprecated, le_mdc_GetDisconnectionReasonExt should be used for the
1100  * new code.
1101  */
1102 //--------------------------------------------------------------------------------------------------
1103 le_mdc_DisconnectionReason_t le_mdc_GetDisconnectionReason
1104 (
1105  le_mdc_ProfileRef_t profileRef
1106  ///< [IN] profile reference
1107 );
1108 
1109 //--------------------------------------------------------------------------------------------------
1110 /**
1111  * Called to get the platform specific disconnection code.
1112  *
1113  * Refer to @ref platformConstraintsSpecificErrorCodes for platform specific
1114  * disconnection code description.
1115  *
1116  * @return The platform specific disconnection code.
1117  *
1118  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
1119  * function will not return.
1120  *
1121  * @deprecated This function is deprecated, le_mdc_GetPlatformSpecificDisconnectionCodeExt should
1122  * be used for the new code.
1123  */
1124 //--------------------------------------------------------------------------------------------------
1126 (
1127  le_mdc_ProfileRef_t profileRef
1128  ///< [IN] profile reference
1129 );
1130 
1131 //--------------------------------------------------------------------------------------------------
1132 /**
1133  * Called to get the platform specific connection failure reason.
1134  *
1135  * Refer to @ref platformConstraintsSpecificErrorCodes for platform specific
1136  * connection failure types and code descriptions.
1137  *
1138  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
1139  * function will not return.
1140  *
1141  * @deprecated This function is deprecated, le_mdc_GetPlatformSpecificFailureConnectionReasonExt
1142  * should be used for new code.
1143  */
1144 //--------------------------------------------------------------------------------------------------
1146 (
1147  le_mdc_ProfileRef_t profileRef,
1148  ///< [IN] profile reference
1149  int32_t* failureTypePtr,
1150  ///< [OUT] platform specific failure type
1151  int32_t* failureCodePtr
1152  ///< [OUT] platform specific failure code
1153 );
1154 
1155 //--------------------------------------------------------------------------------------------------
1156 /**
1157  * Called to get the disconnection reason.
1158  *
1159  * @return The disconnection reason.
1160  *
1161  * @warning The return value le_mdc_DisconnectionReason_t might be limited by the platform.
1162  * Please refer to the platform documentation @ref platformConstraintsMdc.
1163  *
1164  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
1165  * function will not return.
1166  * @note For IPv4v6 mode, pdpType specifies which session's disconnect reason to get(IPv4 or IPv6
1167  * session). For IPv4 and IPv6 mode, pdpType is ignored because there is only one session for
1168  * IPv4 and IPv6 mode.
1169  */
1170 //--------------------------------------------------------------------------------------------------
1171 le_mdc_DisconnectionReason_t le_mdc_GetDisconnectionReasonExt
1172 (
1173  le_mdc_ProfileRef_t profileRef,
1174  ///< [IN] profile reference
1175  le_mdc_Pdp_t pdpType
1176  ///< [IN] pdp type of session
1177 );
1178 
1179 //--------------------------------------------------------------------------------------------------
1180 /**
1181  * Called to get the platform specific disconnection code.
1182  *
1183  * Refer to @ref platformConstraintsSpecificErrorCodes for platform specific
1184  * disconnection code description.
1185  *
1186  * @return The platform specific disconnection code.
1187  *
1188  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
1189  * function will not return.
1190  * @note For IPv4v6 mode, pdpType specifies which session's disconnect reason to get(IPv4 or IPv6
1191  * session). For IPv4 and IPv6 mode, pdpType is ignored because there is only one session for
1192  * IPv4 and IPv6 mode.
1193  */
1194 //--------------------------------------------------------------------------------------------------
1196 (
1197  le_mdc_ProfileRef_t profileRef,
1198  ///< [IN] profile reference
1199  le_mdc_Pdp_t pdpType
1200  ///< [IN] pdp type of session
1201 );
1202 
1203 //--------------------------------------------------------------------------------------------------
1204 /**
1205  * Called to get the platform specific connection failure reason.
1206  *
1207  * Refer to @ref platformConstraintsSpecificErrorCodes for platform specific connection failure
1208  * types and code descriptions.
1209  *
1210  * @note If the caller is passing a bad pointer into this function, it is a fatal error, the
1211  * function will not return.
1212  * @note For IPv4v6 mode, pdpType specifies which session's disconnect reason to get(IPv4 or IPv6
1213  * session). For IPv4 and IPv6 mode, pdpType is ignored because there is only one session for
1214  * IPv4 and IPv6 mode.
1215  */
1216 //--------------------------------------------------------------------------------------------------
1218 (
1219  le_mdc_ProfileRef_t profileRef,
1220  ///< [IN] profile reference
1221  le_mdc_Pdp_t pdpType,
1222  ///< [IN] pdp type of session
1223  int32_t* failureTypePtr,
1224  ///< [OUT] platform specific failure type
1225  int32_t* failureCodePtr
1226  ///< [OUT] platform specific failure code
1227 );
1228 
1229 //--------------------------------------------------------------------------------------------------
1230 /**
1231  * Map a profile on a network interface
1232  *
1233  * * @return
1234  * - LE_OK on success
1235  * - LE_UNSUPPORTED if not supported by the target
1236  * - LE_FAULT for all other errors
1237  *
1238  */
1239 //--------------------------------------------------------------------------------------------------
1241 (
1242  le_mdc_ProfileRef_t profileRef,
1243  ///< [IN] Profile reference
1244  const char* LE_NONNULL interfaceName
1245  ///< [IN] Network interface name
1246 );
1247 
1248 //--------------------------------------------------------------------------------------------------
1249 /**
1250  * Get the list of available profiles
1251  *
1252  * @return
1253  * - list of available profiles
1254  * - LE_OK if the retrieval is successful; otherwise, some error code
1255  */
1256 //--------------------------------------------------------------------------------------------------
1258 (
1259  le_mdc_ProfileInfo_t* profileListPtr,
1260  ///< [OUT] list of available profiles
1261  size_t* profileListSizePtr
1262  ///< [INOUT]
1263 );
1264 
1265 #endif // LE_MDC_INTERFACE_H_INCLUDE_GUARD
le_result_t le_mdc_GetSessionState(le_mdc_ProfileRef_t profileRef, le_mdc_ConState_t *connectionStatePtr)
le_mdc_SessionStateHandlerRef_t le_mdc_AddSessionStateHandler(le_mdc_ProfileRef_t profileRef, le_mdc_SessionStateHandlerFunc_t handlerPtr, void *contextPtr)
le_mdc_Pdp_t le_mdc_GetPDP(le_mdc_ProfileRef_t profileRef)
void le_mdc_StartSessionAsync(le_mdc_ProfileRef_t profileRef, le_mdc_SessionHandlerFunc_t handlerPtr, void *contextPtr)
le_result_t le_mdc_GetDataBearerTechnology(le_mdc_ProfileRef_t profileRef, le_mdc_DataBearerTechnology_t *downlinkDataBearerTechPtrPtr, le_mdc_DataBearerTechnology_t *uplinkDataBearerTechPtrPtr)
le_result_t le_mdc_SetAPN(le_mdc_ProfileRef_t profileRef, const char *LE_NONNULL apnStr)
le_result_t
Definition: le_basics.h:35
bool le_mdc_IsIPv4(le_mdc_ProfileRef_t profileRef)
le_result_t le_mdc_GetIPv4GatewayAddress(le_mdc_ProfileRef_t profileRef, char *gatewayAddr, size_t gatewayAddrSize)
le_result_t le_mdc_StopSession(le_mdc_ProfileRef_t profileRef)
le_result_t le_mdc_GetAPN(le_mdc_ProfileRef_t profileRef, char *apnStr, size_t apnStrSize)
le_result_t le_mdc_GetIPv4DNSAddresses(le_mdc_ProfileRef_t profileRef, char *dns1AddrStr, size_t dns1AddrStrSize, char *dns2AddrStr, size_t dns2AddrStrSize)
le_result_t le_mdc_GetIPv6Address(le_mdc_ProfileRef_t profileRef, char *ipAddr, size_t ipAddrSize)
int32_t le_mdc_GetPlatformSpecificDisconnectionCodeExt(le_mdc_ProfileRef_t profileRef, le_mdc_Pdp_t pdpType)
void le_mdc_ConnectService(void)
void le_mdc_StopSessionAsync(le_mdc_ProfileRef_t profileRef, le_mdc_SessionHandlerFunc_t handlerPtr, void *contextPtr)
le_result_t le_mdc_GetInterfaceName(le_mdc_ProfileRef_t profileRef, char *interfaceName, size_t interfaceNameSize)
le_result_t le_mdc_GetProfileList(le_mdc_ProfileInfo_t *profileListPtr, size_t *profileListSizePtr)
le_result_t le_mdc_SetPDP(le_mdc_ProfileRef_t profileRef, le_mdc_Pdp_t pdp)
bool le_mdc_IsIPv6(le_mdc_ProfileRef_t profileRef)
le_result_t le_mdc_GetBytesCounters(uint64_t *rxBytesPtr, uint64_t *txBytesPtr)
le_mdc_DisconnectionReason_t le_mdc_GetDisconnectionReason(le_mdc_ProfileRef_t profileRef)
void(* le_mdc_DisconnectHandler_t)(void *)
Definition: le_mdc_interface.h:209
le_result_t le_mdc_GetAuthentication(le_mdc_ProfileRef_t profileRef, le_mdc_Auth_t *typePtr, char *userName, size_t userNameSize, char *password, size_t passwordSize)
void le_mdc_GetPlatformSpecificFailureConnectionReason(le_mdc_ProfileRef_t profileRef, int32_t *failureTypePtr, int32_t *failureCodePtr)
void le_mdc_RemoveSessionStateHandler(le_mdc_SessionStateHandlerRef_t handlerRef)
void le_mdc_RemoveMtPdpSessionStateHandler(le_mdc_MtPdpSessionStateHandlerRef_t handlerRef)
le_result_t le_mdc_TryConnectService(void)
void le_mdc_GetPlatformSpecificFailureConnectionReasonExt(le_mdc_ProfileRef_t profileRef, le_mdc_Pdp_t pdpType, int32_t *failureTypePtr, int32_t *failureCodePtr)
le_mdc_ProfileRef_t le_mdc_GetProfile(uint32_t index)
int32_t le_mdc_GetPlatformSpecificDisconnectionCode(le_mdc_ProfileRef_t profileRef)
#define LE_FULL_API
Definition: le_apiFeatures.h:40
le_result_t le_mdc_StartSession(le_mdc_ProfileRef_t profileRef)
LE_FULL_API void le_mdc_SetServerDisconnectHandler(le_mdc_DisconnectHandler_t disconnectHandler, void *contextPtr)
le_result_t le_mdc_ResetBytesCounter(void)
void le_mdc_DisconnectService(void)
le_result_t le_mdc_GetIPv4Address(le_mdc_ProfileRef_t profileRef, char *ipAddr, size_t ipAddrSize)
le_result_t le_mdc_StartBytesCounter(void)
le_mdc_MtPdpSessionStateHandlerRef_t le_mdc_AddMtPdpSessionStateHandler(le_mdc_SessionStateHandlerFunc_t handlerPtr, void *contextPtr)
le_result_t le_mdc_GetIPv6GatewayAddress(le_mdc_ProfileRef_t profileRef, char *gatewayAddr, size_t gatewayAddrSize)
le_result_t le_mdc_SetAuthentication(le_mdc_ProfileRef_t profileRef, le_mdc_Auth_t type, const char *LE_NONNULL userName, const char *LE_NONNULL password)
le_result_t le_mdc_GetProfileFromApn(const char *LE_NONNULL apnStr, le_mdc_ProfileRef_t *profileRefPtr)
uint32_t le_mdc_GetProfileIndex(le_mdc_ProfileRef_t profileRef)
uint32_t le_mdc_NumProfiles(void)
le_result_t le_mdc_SetDefaultAPN(le_mdc_ProfileRef_t profileRef)
le_result_t le_mdc_StopBytesCounter(void)
le_result_t le_mdc_RejectMtPdpSession(le_mdc_ProfileRef_t profileRef)
le_result_t le_mdc_MapProfileOnNetworkInterface(le_mdc_ProfileRef_t profileRef, const char *LE_NONNULL interfaceName)
le_result_t le_mdc_GetIPv6DNSAddresses(le_mdc_ProfileRef_t profileRef, char *dns1AddrStr, size_t dns1AddrStrSize, char *dns2AddrStr, size_t dns2AddrStrSize)
le_mdc_DisconnectionReason_t le_mdc_GetDisconnectionReasonExt(le_mdc_ProfileRef_t profileRef, le_mdc_Pdp_t pdpType)