A data session is useful for applications that need to send or receive data over a network where SMS messages are insufficient. To start a data session, a data profile must be configured as specified by the target network.

The Modem Data Control (mdc) API is used to manage data profiles and data sessions.

IPC interfaces binding

All the functions of this API are provided by the modemService service.

Here's a code sample binding to modem services:

bindings:
{
   clientExe.clientComponent.le_mdc -> modemService.le_mdc
}

Data Profiles

If a pre-defined data profile has been configured then this profile can be loaded using le_mdc_GetProfile(). le_mdc_GetProfile() must be called with LE_MDC_DEFAULT_PROFILE to retrieve the default index used by the modem for data connection. le_mdc_GetProfile() must be called with LE_MDC_SIMTOOLKIT_BIP_DEFAULT_PROFILE to retrieve the default index used by the modem for Bearer Independent Protocol (BIP). The maximum number of data profiles supported is modem dependent and can be retrieved with le_mdc_NumProfiles(). The list of supported PDP context identifiers (CID) are modem dependent and can be retrieved by calling le_mdc_GetCidList().

Note: le_mdc_GetProfile() creates a new profile if the profile's index can't be found.

Warning: 0 is not a valid index.

A pre-defined data profile can be retrieved using le_mdc_GetProfileFromApn() thanks to its APN.

A default APN can be set for a defined profile with le_mdc_SetDefaultAPN(), based on the SIM identification number (ICCID). If no match is found in the database using the ICCID, the search falls back on the home network (MCC/MNC) to determine the default APN.

Warning: Ensure to check the list of supported data profiles for your specific platform.

The following data profile parameters can be retrieved:

Packet Data Protocol using le_mdc_GetPDP().
Access Point Name using le_mdc_GetAPN().
Authentication settings using le_mdc_GetAuthentication().

The following data profile parameters can be set:

Packet Data Protocol using le_mdc_SetPDP().
Access Point Name using le_mdc_SetAPN().
Authentication settings using le_mdc_SetAuthentication().

Warning: The maximum APN length might be limited by the platform. Please refer to the platform documentation.

A sample code can be seen in the following page:

Sample code for Data Profiles

Data Sessions

Mobile Originated (MO-PDP context activation)

le_mdc_MapProfileOnNetworkInterface() may be used to map a data session with a network interface. To take effect, this API has to be called before starting the data session. Otherwise, the mapping will be taken into account at the next start of the data profile.

A data session can be started using le_mdc_StartSession(). It is a blocking function with a maximum timeout set to 155 seconds. To start a data session, a data profile must be created and written to the modem, or an existing data profile can be used. A data session can be stopped using le_mdc_StopSession(). The number of simultaneous data sessions supported is dependent on the modem, but cannot be more than the maximum number of supported profiles.

A data session can be started using le_mdc_StartSessionAsync() and stopped using le_mdc_StopSessionAsync(). These functions are not blocking. The response will be returned with the le_mdc_SessionHandlerFunc_t handler function.

The current state of a data session can be queried using le_mdc_GetSessionState(). An application can also a register handler to be notified when the session state changes. The handler can be managed using le_mdc_AddSessionStateHandler() and le_mdc_RemoveSessionStateHandler().

Mobile Terminated (MT-PDP context activation)

To be notified by the MT-PDP context request, the application has to subscribe to the state handler using le_mdc_AddMtPdpSessionStateHandler(). When the incoming MT-PDP context request is notified, the application takes responsibility to trigger the data session for that MT PDP request using le_mdc_StartSession(). That data session can be stopped using le_mdc_StopSession().

The network interface settings of that MT-PDP context can be retrieved using the provided Data Profile. Please refer to Network interface settings.

A data session can be rejected using le_mdc_RejectMtPdpSession(). The number of simultaneous data sessions supported is dependent on the modem, but cannot be more than the maximum number of supported profiles.

The handler can be released using le_mdc_RemoveMtPdpSessionStateHandler().

Warning: The MT-PDP context activation feature is not supported on all platforms. Please refer to Mobile Terminated PDP context section for full details.

Network interface settings

Once a data session starts, a Linux network interface is created. It's the application's responsibility to configure the network interface, usually through a DHCP client. Query the interface name using le_mdc_GetInterfaceName(). The IP Preference can be checked with le_mdc_IsIPv4() or le_mdc_IsIPv6() when the profile is connected. The IP address for the current data session can be retrieved by le_mdc_GetIPv4Address() or le_mdc_GetIPv6Address(). The Gateway and DNS addresses can be retrieved using le_mdc_GetIPv4GatewayAddress(), le_mdc_GetIPv4DNSAddresses() or le_mdc_GetIPv6GatewayAddress(), le_mdc_GetIPv6DNSAddresses(). The Access Point Name can be retrieved by le_mdc_GetAPN(). The Data bearer Technology can be retrieved by le_mdc_GetDataBearerTechnology().

le_mdc_GetDisconnectionReasonExt() or le_mdc_GetPlatformSpecificDisconnectionCodeExt() let you get the reason for disconnection of data session by retrieving the call end failure code from le_mdc_ProfileRef_t.

le_mdc_GetPlatformSpecificFailureConnectionReasonExt() let you get the data session connection failure reason by retrieving the call connection failure code and type from le_mdc_ProfileRef_t.

Please refer to Platform specific error codes for platform specific disconnection code description.

A sample code can be seen in the following page:

Sample code for network interface settings

Data Statistics

The amount of received and transmitted data can be retrieved through le_mdc_GetBytesCounters(). The returned values correspond to the number of received and transmitted bytes since the last call to le_mdc_ResetBytesCounter().

The data statistics collection can be enabled with le_mdc_StartBytesCounter() and disabled without resetting the counters with le_mdc_StopBytesCounter().

Note: The data statistics collection activation and the data counters are persistent even after a reboot of the platform.

A sample code can be seen in the following page:

Sample code for Data Statistics