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