6.2 App-to-MSDC connection setup
6.2.2 MSDC manager module connection initialization
After Add MSDC manager module event listener (section 6.2.1), the app has to initialize the connection to the MSDC manager module using the initializeMSDC function. The app provides the following through this function:
■ App id – The unique ID of the App which the MSDC uses to authenticate it.
■ Reception Reporting Opt in – This informs the MSDC if the app is interested in opting in for reception reporting. If the app wants to opt in, the value should be set to TRUE, which means that the MSDC can collect some or all of the following reception-related information:
□ Streaming service
● Client id – The Mobile Directory Number of the device, or a randomly generated ID
● Service id – Identifies the service to which the session belongs
● Session start and end time – Needed to identify logging start and stop times
● Number of objects received or lost – The middleware periodically collects the number of objects that failed to be decoded and the number of objects that it attempted to decode within each measurement period
● Network Cell id - The global cell ID where the device is camped; it is collected once per measurement period
□ File delivery service
● Client id – The Mobile Directory Number of the device, or a randomly generated ID
● Service id – Identifies the service to which the session belongs
● Session start and end times – Needed to identify logging start and stop times
● File URI – The identifier of the files that the app has tried to download/capture
● URLs and delivery status of objects – The middleware logs the URLs and the delivery status of objects for which reception succeeded or failed
● Network Cell id – Global cell ID where the device is camped; it is collected once per measurement period
An app which is interested only in GroupCall Service must set this flag to FALSE as it cannot opt for reception reporting feature of MSDC.
Unless defined by the app, the MSDC considers the reception reporting opt-in value to be FALSE.
■ Targeted MSDC middleware package name – This optional parameter identifies the targeted package name in case multiple MSDC middleware is installed on the device. If no package name is specified, the default is com.qualcomm.ltebc which is the released Qualcomm MSDC middleware APK package name.
■ MSDC middleware connection mode – This optional parameter identifies the connection preference.
● Local only – This is the default value. The assumption is the MSDC middleware is on the same device as the UI client and the UI application is interested only in using the MSDC middleware on the device. The app may select this mode when no remote MSDC middleware running on mobile broadband product exists.
● Remote only – Indicates the UI application is interested in connecting to remote MSDC middleware running on mobile broadband product. The app may select this mode when it can leverage remote MSDC middleware running on mobile broadband product at the home/office.
● Remote preferred: Indicates the UI application prefers connection to remote MSDC middleware running on mobile broadband product. However, if the remote MSDC is not available, the UI application can connect to local MSDC middleware on the same device as UI until the remote MSDC middleware becomes available again.
■ Remote Retry timer in millisecond – This optional parameter is only
applicable in Remote or Remote Preferred connection mode. It specifies the retry period for connecting to remote MSDC middleware when the connection is lost. The default value is 5000 milliseconds.
If the MSDC API accepts the request, and if the connection initialization is successful, the MSDC API responds with initializeMSDCConfirmation.
6.2.2.2 Prerequisite
Add MSDC manager module event listener (section 6.2.1) should be complete.
RECOMMENDATION
The App should call initializeMSDC as early as possible to reduce the startup time
6.2.2.3.1 Connection initialization succeeds – Ideal condition
Figure 6-5 is the call flow sequence for MSDC manager module connection initialization.
App MSDC API
initializeMSDC()
initializeMSDCConfirmation() MSDC Initialize Parameters Initialize the
connection
Figure 6-5 MSDC – Connection initialization succeeds, Ideal condition
6.2.2.3.2 Connection initialization fails due to version mismatch
If a connection initialization fails because the version of MSDC API used by the app is not supported by the MSDC, the MSDC API responds with msdcError with error code
ERROR_MSDC_VERSION_INCOMPATIBLE.
Figure 6-6 is the corresponding call flow.
App MSDC API
initializeMSDC()
msdcError()
MSDC Initialize Parameters Initialize the
connection MSDC API version is
not supported by MSDC
Error code =
ERROR_MSDC_VERSION_INCOMPATIBLE, Error message = <error message>
Figure 6-6 MSDC – connection initialization fails - version mismatch See Code Example in Section 5.2.2
6.2.2.3.3 Connection initialization succeeds with limited feature set support
The connection initialization may succeed even with a supported version mismatch of the MSDC API between the app and MSDC. This can typically happen when the app is using a version of MSDC API which is later than the version used by the MSDC. In such a case, the MSDC would support only limited features.
When such a condition arises, the MSDC API notifies the app with a Warning in the msdcWarning with warning code WARNING_MSDC_REDUCED_FEATURE_SET.
Figure 6-7 is the corresponding call flow.
App MSDC API
initializeMSDC()
msdcWarning() MSDC Initialize Parameters Initialize the
connection
Initialization successful.
However, due to a MSDC API version mismatch, MSDC would support a limited feature set
Warning code =
WARNING_MSDC_REDUCED_
FEATURE_SET
message = <message>
initializeMSDCConfirmation()
Figure 6-7 MSDC – Connection initialization succeeds with limited feature set support
6.2.2.3.4 Connection initialization fails due to carrier change not allowed
If the MSDC middleware has been configured so it runs only in a certain carrier network, the connection initialization fails, if the device is operating in a network other than the one for which the MSDC middleware is configured. As a result, the application receives the
ERROR_MSDC_CARRIER_CHANGE_NOT_ALLOWED error.
App
initializeMSDC()
msdcError() MSDC Initialize Parameters Initialize the
connection
Error code =
ERROR_MSDC_CARRIER_CHANGE_NOT_ALLOWED, Error message = <error message>
MSDC API
Figure 6-8 – Connection initialization failed due to carrier change not allowed
6.2.2.3.5 Connection initialization fails due to MSDC middleware not installed
If the application requests a specific MSDC middleware package name during the connection initialization and that MSDC middleware is not installed on the device, the application receives the ERROR_MSDC_MIDDLEWARE_NOT_INSTALLED error.
App
initializeMSDC()
msdcError() MSDC Initialize Parameters Initialize the
connection
Error code =
ERROR_MSDC_MIDDLEWARE_NOT_INSTALLED, Error message = <error message>
MSDC API
Figure 6-9 – Connection initialization failed due to MSDC middleware not installed
6.2.2.3.6 Connection initialization fails due to MSDC middleware permissions
For Android M HLOS devices, the MSDC middleware requires permissions to be granted, and there can be scenarios where the permissions are not granted by default or denied by the user. If the required permissions are denied, or are not granted during initialization, the eMBMS application receives the ERROR_MSDC_APP_PERMISSIONS_NOT_GRANTED error.
App
initializeMSDC()
msdcError() MSDC Initialize Parameters Initialize the
connection
Error code =
ERROR_MSDC_APP_PERMISSIONS_NOT_GRANTED, Error message = <error message>
MSDC API
Figure 6-10 Connection initialization failed due to MSDC middleware permissions
6.2.2.3.7 Connection initialization fails – other reasons
If a connection initialization fails for any other reason, the MSDC API responds with msdcError with error code ERROR_MSDC_UNABLE_TO_INITIALIZE.
Figure 6-11 is the corresponding call flow.
App MSDC API
initializeMSDC()
msdcError()
MSDC Initialize Parameters Initialize the
connection
Initialize connection error
Error code =
ERROR_MSDC_UNABLE_TO_INITIALIZE, Error message = <error message>
Figure 6-11 MSDC – connection initialization fails – other reason
6.2.2.4 Interface functions
■ void initializeMSDC (MSDCAppManagerInitParams params)
■ void initializeMSDCConfirmation ()
■ void msdcError (int errorCode, String message)