Update Content

The Magic Lane Maps SDK for C++ allows updating downloaded content to stay synchronized with the latest map data. New map versions are released every few weeks. The update operation supports the CT_RoadMap, CT_ViewStyleLowRes, and CT_ViewStyleHighRes content types. This article focuses on the CT_RoadMap type, as it is the most common use case. Updating styles mostly follows the same process.

The SDK requires all road map content store items to have the same version. It is not possible to have multiple CT_RoadMap items with different versions, meaning partial updates of individual items are not supported.

Based on the client's content version relative to the newest available release, it can be in one of three states, as defined by the IOffboardListener::EStatus enum:

Status	Description
`ExpiredData`	The client version is significantly outdated and no longer supports online operations. All features - such as search, route calculation, and navigation - will function exclusively on the device using downloaded regions, even if an internet connection is available. If an operation like route calculation is attempted in non-downloaded regions, it will fail with a `error::KExpired` error code. An update is mandatory to restore online functionality. Only relevant for `EContentType::CT_RoadMap` elements.
`OldData`	The client version is outdated but still supports online operations. Features will work online when a connection is available and offline when not. While offline, only downloaded regions are accessible, but online access allows operations across the entire map. An update is recommended as soon as possible. Relevant for all types of content store elements.
`UpToDate`	The client version has the latest map data. Features function online when connected and offline using downloaded regions. No updates are available. Relevant for all types of content store elements.

The Magic Lane servers support online operations for the most up-to-date version (IOffboardListener::EStatus::UpToDate) and the previous version (IOffboardListener::EStatus::OldData) of road map data.

note

After installation, the app includes a default map version of type ExpiredData, which contains no available content. Therefore, an update is required before the app can be used. Internet access is required for the initial use of the app.

Update process overview

The map update process is initiated by the API user which starts the download process.
The process downloads the newer data in background ensuring the full usability of the current ( old ) map dataset for browsing, search and navigation. The content is downloaded in a close-to-current user position order, i.e. nearby maps are downloaded first.
Once all new version data is downloaded the API user is notified and the update is applied by replacing the files is an atomic operation. (API user must call apply).

If the user's storage size does not allow the existence of the old and new dataset at the same time, the update required an additional step:

The remaining offline maps which did not download because of the out-of-space exception should be downloaded by the API user by a usual call to the ContentStoreItem::asyncDownload.

Listen for map updates

You can listen for map updates by handling the onWorldwideRoadMapSupportStatus method from IOffboardListener.

class YourOffboardListenerImpl : public IOffboardListener
{

void onWorldwideRoadMapSupportStatus(IOffboardListener::EStatus status) override
{
    switch (status) {
    case IOffboardListener::EStatus::UpToDate:
        GEM_INFO_LOG("The map version is up-to-date.");
        break;
    case IOffboardListener::EStatus::OldData:
        GEM_INFO_LOG(
            "A new map version is available. Online operation on the current map version are still supported.");
        break;
    case IOffboardListener::EStatus::ExpiredData:
        GEM_INFO_LOG(
            "The map version has expired. All operations will be executed offline.");
        break;
    }
}
};

The SDK automatically triggers the map version check at an appropriate moment. To manually force the check, you can call the checkForUpdate method from the ContentStore:

auto operationErrorCode = ContentStore().checkForUpdate(EContentType::CT_RoadMap);

The checkForUpdate method returns KNoError if the check has been initiated and error::KConnectionRequired if no internet connection is available.

note

If the checkForUpdate method is provided with the EContentType:CT_RoadMap argument, then the IOffboardListener::onWorldwideRoadMapSupportStatus will be called. If other values are supplied to the checkForUpdate method (such as map styles), then the response will be returned via the IOffboardListener::onAvailableContentUpdate callback.

Create content updater

To update the road maps, you must instantiate a ContentUpdater object. This object manages all operations related to the update process:

auto contentUpdaterResult = ContentStore().createContentUpdater(EContentType::CT_RoadMap);

if (contentUpdaterResult.second != KNoError && contentUpdaterResult.second != error::KExist){
    GEM_INFO_LOG("Error regarding the content updater creation : %d", contentUpdaterResult.second);
    return;
}

The createContentUpdater method returns a ContentUpdater instance along with an error code indicating the status of the updater creation for the specified EContentType:

If the error code is KNoError, the ContentUpdater was successfully created and is ready for use.
If the error code is error::KExist, a ContentUpdater for the specified EContentType already exists, and the existing instance is returned. This instance remains valid and can be used.
If the error code corresponds to any other error value, the ContentUpdater instantiation has failed, and the returned object is not usable.

Start the update

In order to start the update process, you must call the update method from the ContentUpdater object created earlier. The update method accepts the following parameters:

a boolean indicating whether the update can proceed on networks that may incur additional charges. If false, the update will only run on free networks, such as Wi-Fi.
a progress listener for tracking status updates, progress and completion.
an EDataSavePolicy value, for overriding the default save behavior if needed. The most common error codes are:
- KNoError if the update was successful.
- error::KInUse if the update is already running and could not be started.
- error::KNotSupported if the update operation is not supported for the given content type.
- error::KNoDiskSpace if there is not enough space on the device for the update.
- error::KIo if an error regarding file operations occurred.

Content updater status

The EContentUpdaterStatus enum provided by the notifyStatusChanged method has the following values:

Enum Value	Description
`Idle`	The update process has not started. It's the default state of the `ContentUpdater`
`WaitConnection`	Waiting for an internet connection to proceed (Wi-Fi or mobile).
`WaitWIFIConnection`	Waiting for a Wi-Fi connection before continuing. Available if the `update` method has been called with `false` value for the `allowChargeNetwork` parameter.
`CheckForUpdate`	Checking for available updates.
`Download`	Downloading the updated content. The overall progress and the per-item progress is available.
`FullyReady`	The update is fully downloaded and ready to be applied. The `ContentUpdater::getItems` list will contain the target items for the update. An `apply` call is required for the update to be applied
`PartiallyReady`	The update is partially downloaded but can still be applied. The content available offline that wasn't yet updated will be deleted if the update is applied and the remaining items will be updated.
`DownloadRemainingContent`	Downloading any remaining content after applying the update. If the `apply` method is called while the `PartiallyReady` status is set, then this will be the new status. The user must get the list of remaining content items from the updater and start normal download operation.
`DownloadPendingContent`	Downloads any pending content that has not yet been retrieved. If a new item starts downloading during an update, it will complete after the update finishes (at the latest version). This value is provided while these downloads are in progress.
`Complete`	The update process has finished successfully. The `notifyComplete` callback is also triggered with `KNoError`
`Error`	The update process encountered an error. The `notifyComplete` callback is also triggered with the appropriate error code

ContentStore details

Details about the ContentUpdater objects can be got via the provided getters:

EContentUpdaterStatus status = contentUpdater->getStatus();
int progress = contentUpdater->getProgress();
bool isStarted = contentUpdater->isStarted();
bool canApplyUpdate =  contentUpdater->canApply();
bool isUpdateStarted = contentUpdater->isStarted();

Finish the update process

Once notifyStatusChanged is called with a EContentUpdaterStatus value of FullyReady or PartiallyReady, the update can be applied using the apply method of the ContentUpdater class.

if the status is FullyReady, all items have been downloaded.
if the status is PartiallyReady, only a subset of the items has been downloaded. Applying the update will remove outdated items that were not fully downloaded, restricting offline functionality to the updated content only. The remaining items will continue downloading.

class YourProgressListenerImpl : public ProgressListenerImpl
{

    void notifyStatusChanged (int status) override 
    {
        GEM_INFO_LOG("OnStatusUpdated with code %d", status);

        if (status == (int)EContentUpdaterStatus::FullyReady ||
            status == (int)EContentUpdaterStatus::PartiallyReady) 
        {

            if (!contentUpdater->canApply()){
                GEM_INFO_LOG("Cannot apply content update");
                return;
            }
            auto applyError = contentUpdater->apply();
            GEM_INFO_LOG("Apply resolved with code %d", applyError);
        }
    }
};

The apply method returns:

KNoError if the update was applied successfully.
error::KUpToDate if the update is already up to date and no changes were made.
error::KInvalidated if the update operation has not been started successfully via the update method.
error::KIo if an error regarding the file system occurred while updating the content.

The notifyComplete will also be triggered with the appropriate error code.

Update resources

The Magic Lane Maps SDK for C++ includes built-in resources such as icons and translations. Automatic update for these resources is enabled by default in IOffboardListener::isResourcesUpdateAllowed. It can be disabled by overriding this function and returning false.

Once the resources update is ready to be applied, the API user is notified via IOffboardListener::onResourcesReadyToDeploy. The API user doesn't have to do anything to apply the update, the update is going to be applied on the next SDK initialization.

Update process overview​

Listen for map updates​

Create content updater​

Start the update​

Content updater status​

ContentStore details​

Finish the update process​

Update resources​