Manage Content

The Maps SDK for C++ offers comprehensive functionality for managing offline content.

The supported downloadable content types are defined in the EContentType enum:

CT_ViewStyleHighRes: High-dpi screen optimized map styles that can be applied offline. These include both a selection of default styles and user-created styles from the studio, based on the API key.
CT_ViewStyleLowRes: Low-dpi screen map styles, optimized for smaller file sizes while maintaining essential details.
CT_RoadMap : Offline maps covering countries and regions. Within a downloaded region, users can perform searches, calculate routes, and navigate without an internet connection.
CT_HumanVoice: Pre-recorded voice files used to deliver spoken navigation instructions and warnings.

tip

For most use cases, the high-resolution map styles option is recommended over its low-resolution counterpart.

The ContentStore class is responsible for managing and providing a list of downloadable items. Each item is represented by the ContentStoreItem class, which encapsulates details such as name, image, type, version, and size. Additionally, it offers operations for downloading and deleting content.

warning

Ensure that the API token is both set and valid. Some operations might return error::KBusy if no valid API key is set.

warning

Modifying downloaded maps (download, delete, update) may interrupt ongoing operations such as search, route calculation, or navigation. If this occurs, the notifyComplete callback will be triggered with a error::KInvalidated value.

List Online Content

To retrieve a list of available content from the Magic Lane servers, use the asyncGetStoreContentList method from the ContentStore class. This method accepts a ProgressListener, which allows the operation to be stopped if needed. If the operation fails to start, it returns an error.

auto listener = StrongPointerFactory<YourProgressListenerImpl>();

auto err = ContentStore().asyncGetStoreContentList(EContentType::CT_RoadMap, listener);
if (err != KNoError)
{
    GEM_INFO_LOG("Failed to request the list of content store items: %d", err);
}

// after the above operation completes, call `getLocalContentList`

note

The asyncGetStoreContentList method should be called only when an active internet connection is available and the current offline version is not expired. If no internet connection is available or if the current offline map version is expired, use the getLocalContentList method to retrieve the offline content list instead.

List Local Content

The getLocalContentList method can be used to get the list of local content available offline.

auto ContentStoreItemList items = ContentStore().getLocalContentList(EContentType::CT_RoadMap);
/// Do something with the items

Note

The getLocalContentList method returns content store items that are either ready for use or currently downloading, as well as those pending download.

Filter Content

To obtain a filtered list of available content from the Magic Lane servers, use the asyncGetStoreFilteredList method from the ContentStore class. You can filter content by specifying country ISO 3166-3 codes and by geographic area using a RectangleGeographicArea.

auto listener = StrongPointerFactory<YourProgressListenerImpl>();

EContentType filteredContentType = EContentType::CT_RoadMap;
StringList filteredCountries;
RectangleGeographicArea filteredArea(
    Coordinates(53.7731, -1.7990),
    Coordinates(38.4549, 21.1696)
);

ContentStore().asyncGetStoreFilteredList( filteredContentType, filteredCountries, filteredArea, listener );

Note

The getStoreFilteredList method returns the filtered content store items that were last requested via asyncGetStoreFilteredList method.

Method behaviour

Condition	`notifyComplete` Result
The `countries` list contains invalid ISO 3166-3 codes	`KNoError` with an empty `ContentStoreItem` list.
The `countries` list includes countries incompatible with the specified `RectangleGeographicArea`	`KNoError` with an empty `ContentStoreItem` list.
Insufficient memory to complete the operation	`error::KNoMemory` with an empty `ContentStoreItem` list.
Invalid `GeographicArea` (e.g., invalid coordinates)	`KNoError` with a full list of `ContentStoreItem`; behaves as if no filter was applied.
The `area` parameter is an empty `TilesCollectionGeographicArea`	`error::KInvalidInput` with an empty `ContentStoreItem` list.
HTTP request failed	`error::KGeneral` with an empty `ContentStoreItem` list.

Content Store Item Fields

Fields Containing General Information

Getters	Description
`getName`	The name of the associated product, automatically translated.
`getId`	The unique ID of the item in the content store.
`getType`	The type of the product as a `EContentType` value.
`getFileName`	The full path to the content data file.
`getTotalSize`	The total size of the content in bytes.
`getAvailableSize`	The downloaded size of the content.
`getUpdateSize`	The update size if an update is available.
`getStatus`	The current status of the item as a `EContentStoreItemStatus`.
`getContentParameters`	Additional information about an item is the form of a `SearchableParameterList` object
`getImagePreview`	The image associated with the content store item. The user is responsible to check if the image is valid

tip

For checking if a ContentStoreItem is downloaded/available/downloading/updating use the status field value:

CIS_Unavailable: The content store item is not downloaded and cannot be used.
CIS_Completed: The content store item has been downloaded and is ready to be used.
CIS_Paused: The download operation has been paused by the user.
CIS_DownloadQueued: The download is queued and will proceed once resources are available.
CIS_DownloadWaitingNetwork: No internet connection is established, and the download will proceed once a network connection is available.
CIS_DownloadWaitingFreeNetwork: The SDK is waiting for a free network connection to continue the download.
CIS_DownloadRunning: The download is actively in progress.
CIS_UpdateWaiting: An update operation is underway.

The contentParameters field provides information such as:

For CT_RoadMap type:
- Copyright : value of type String containing the copyright information for the road map
- MapData provider : value of type String containing the name of the map data provider
- Release date : value of type String containing the release date for the road map in DD.MM.YYYY format
- Default name : value of type String containing the name of the item
For CT_ViewStyleHighRes type:
- Background-Color : value of type String containing the background color in decimal format (ex: 4294957738 which when converted to hex corresponds with #FFFFDAAA). Can be used to check if a style is a dark-mode or light-mode recommended style by checking the brightness of this value
For CT_HumanVoice type:
- language : value of type String containing the BCP 47 language code (e.g., eng_IRL)
- gender : value of type String indicating the speaker's gender (e.g., Female)
- type : value of type String specifying the type of voice used (e.g., human)
- native_language : value of type String containing the name of the language in its native form (e.g., English)

The image can be got via the imagePreview getter:

bool isImagePreviewAvailable = contentStoreItem.isImagePreviewAvailable();
if (isImagePreviewAvailable) 
{
    Image previewImage = contentStoreItem.getImagePreview();
);
// Do something with the preview image.
}

warning

Content store items of type CT_RoadMap do not have an image preview. The MapDetails::getCountryFlag method can be used to get the flag image associated with a country code instead.

Use the getCountryCodes getter to obtain the country codes associated with a content store item of type CT_RoadMap.

Fields Containing Download and Update Information

Field Name / Methods	Description
`getClientVersion`	The client version of the content.
`getUpdateVersion`	The update version if an update is available. Returns a dummy object with fields set to 0 if no new version is available
`getDownloadProgress`	The current download progress as a percentage.
`getUpdateItem`	The corresponding update item if an update is in progress.
`isCompleted`	Checks if the item has been completely downloaded.
`isUpdatable`	Checks if the item has a newer version available.
`canDeleteContent`	Checks if the content can be deleted.

While the download is in progress, you can retrieve details about the downloaded content:

isCompleted: Returns true if the download is completed; otherwise, returns false (indicating that the download has not started or has started but not yet completed).
getDownloadProgress: Returns the download progress as an integer between 0 and 100. It returns 0 if the download has not started.
getStatus: Returns the current status of the content store item.

Fields Relevant to `EContentType::CT_RoadMap` Type Items

Field Name	Description
`getChapterName`	Some large countries are divided into multiple content store items (e.g., the USA is split into states). All items within the same country share the same chapter. This chapter is empty if the item is not of the `RoadMap` type or if the country is not divided into multiple items.
`getCountryCodes`	A list of country codes (ISO 3166-1 alpha-3) associated with the product.
`getLanguage`	The full language details for the product.

Fields Relevant to `ContentType.CT_HumanVoice` Type Items

Field Name	Description
`getCountryCodes`	A list of country codes (ISO 3166-1 alpha-3) associated with the product.
`getLanguage`	The full language details for the product.

tip

Use the ISOCodeConversions class for conversions between the different types of codes. See the internationalization documentation for more details.

Download Content Store Item

For downloading a content store item, the asyncDownload method can be used:

auto listener = StrongPointerFactory<YourProgressListenerImpl>();

contentStoreItem.asyncDownload( listener );

The notifyComplete method of the given listener is invoked at the end of the operation, returning the result of the download. If the item is successfully downloaded, err is set to KNoError. In case of an error, other values may be returned (e.g., error::KIo if the item is already downloaded).

Additionally, users can implement notifyProgress method of the listener to receive real-time progress updates. This callback is triggered with the current download progress, represented as an integer between 0 and 100.

Download on Extra Charged Networks

The SDK includes functionality to restrict downloads on networks with additional charges, which may cause downloads to not work as expected.

To enable downloads on such networks, use the setAllowOffboardServiceOnExtraChargedNetwork method from the SdkSettings class.

SdkSettings().setAllowOffboardServiceOnExtraChargedNetwork(EServiceGroupType::ContentService, true);

Alternatively, the asyncDownload method can be called with allowChargedNetworks set to true, bypassing the value set via setAllowOffboardServiceOnExtraChargedNetwork.

If a download operation is requested while the user is on an extra-charged network, and setAllowOffboardServiceOnExtraChargedNetwork is set to false for the content service without passing the true value for the allowChargedNetworks optional parameter, the download will be automatically scheduled and will proceed once the user switches to a non-extra-charged network. In this case, the status field of the corresponding ContentStoreItem object will be set to EContentStoreItemStatus::CIS_DownloadQueued.

Pause download

The download can be paused using the pauseDownload method. This method causes the notifyComplete event of the supplied listener to be called with error::KSuspended. In order to resume the download call asyncDownload as shown above.

warning

No further operations should be performed on the ContentStoreItem object until the pause operation has completed and the corresponding callback has been invoked.

Delete Downloaded Content

Downloaded content can be removed from local storage by calling the deleteContent method on the corresponding ContentStoreItem object, after checking if the item can be removed:

if (contentStoreItem.canDeleteContent()){
    auto error = contentStoreItem.deleteContent();
    GEM_INFO_LOG("Item %s deletion resulted with code %d", contentStoreItem.getName(), error);
} else {
    GEM_INFO_LOG("Item cannot be deleted");
}

warning

Do not confuse the functionality provided by the ContentStore / ContentStoreItem classes with that of the MapDownloaderService class.

The ContentStore API is designed for downloading full offline content, including data required for features such as free-text search, routing, and turn-by-turn navigation.
In contrast, the MapDownloaderService is intended for caching map tiles mainly for visual display purposes. Tiles downloaded via MapDownloaderService do not support most search operations, routing or navigation while offline.

See the download individual map tiles documentation for more details about the MapDownloaderService.

Downloading overlays

Overlays can be downloaded for specific regions to enable offline functionality. To do this, you must first download a map region, after which the overlays become available for download within those offline areas. Downloading overlays for offline use is done through the grabOverlayOfflineData method of OverlayService.

auto overlayUid = ECommonOverlayId::OID_Safety; // Example overlay UID (e.g., speed cameras)
if (!OverlayService().isOverlayOfflineDataGrabberSupported(overlayUid)) 
{
    GEM_INFO_LOG("Overlay offline data grabber not supported for this overlay");
    return;
}

OverlayService().enableOverlayOfflineDataGrabber(overlayUid);

OverlayService().grabOverlayOfflineData(overlayUid, listener);
// Optionally, you can cancel the task if needed 
// OverlayService().cancelGrabOverlayOfflineData(overlayUid);

// Disable the grabber when it's no longer needed
OverlayService().disableOverlayOfflineDataGrabber(overlayUid);

warning

Not all overlays support offline data grabbing. Use the isOverlayOfflineDataGrabberSupported method to check if a specific overlay supports this feature.
After completing the download, disable the offline data grabber using disableOverlayOfflineDataGrabber to prevent unnecessary resource usage.

After downloading, the overlay items will be available in offline mode within the downloaded map regions. You can verify if the overlay data has been successfully downloaded if overlay items are visible inside the downloaded map region in offline mode.

Offline speed camera overlay item visible

tip

Ensure to enable the offline data grabber using enableOverlayOfflineDataGrabber before initiating the download process, otherwise, the the notifyComplete callback will return error::KActivation.

Call enableOverlayOfflineDataGrabber only with an overlay UID that supports offline grabbing; if the UID is unsupported, enabling will not work and will not return KNoError.

Note

Not all overlay types support offline functionality (eg. Alerts or Public Transit Stops). For instance, public transport stops will still require an internet connection to display the relevant data, thus will be rendered as landmarks instead of overlay items in offline mode.

You can check if the overlay data grabber has been enabled for a specific overlay using the isOverlayOfflineDataGrabberEnabled method.

List Online Content​

List Local Content​

Filter Content​

Method behaviour​

Content Store Item Fields​

Fields Containing General Information​

Fields Containing Download and Update Information​

Fields Relevant to EContentType::CT_RoadMap Type Items​

Fields Relevant to ContentType.CT_HumanVoice Type Items​

Download Content Store Item​

Download on Extra Charged Networks​

Pause download​

Delete Downloaded Content​

Downloading overlays​

List Online Content

List Local Content

Filter Content

Method behaviour

Content Store Item Fields

Fields Containing General Information

Fields Containing Download and Update Information

Fields Relevant to `EContentType::CT_RoadMap` Type Items

Fields Relevant to `ContentType.CT_HumanVoice` Type Items

Download Content Store Item

Download on Extra Charged Networks

Pause download

Delete Downloaded Content

Downloading overlays