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().

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().

A sample code can be seen in the following page:

Sample code for Data Profiles

Data Sessions

Mobile Originated (MO-PDP context activation)

A data session can be started using le_mdc_StartSession(). 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().

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().

When the data session is stopped, the disconnection reason can be known using le_mdc_GetDisconnectionReason() or le_mdc_GetPlatformSpecificDisconnectionCode() (refer to your platform documentation for further details).

When the data session connection fails, the failure reason can be known using le_mdc_GetDisconnectionReason(), le_mdc_GetPlatformSpecificDisconnectionCode() or le_mdc_GetPlatformSpecificFailureConnectionReason() (refer to your platform documentation for further details).

A sample code can be seen in the following page:

Sample code for network interface settings

Data Statistics

Data bytes received/transmitted can be access through le_mdc_GetBytesCounters(). These values correspond to the number of bytes received/transmitted since the last software reset or the last le_mdc_ResetBytesCounter() called. Making these value persistent after a software reboot is the client responsibility.

A sample code can be seen in the following page:

Sample code for Data Statistics