Tune the local cache
A layer that reads over a network can keep the tiles it has fetched on local disk. That is what makes a network-backed map usable on a slow link — and usable at all once the link is gone. The cache is off by default and is enabled in two places: once for the device, then per layer.
Enable the cache
On the device. IMcMapDevice::SInitParams carries two fields, and both must be set:
| Field | Meaning |
|---|---|
strMapLayersLocalCacheFolder | Path to the folder holding the cache. NULL, the default, means no cache |
uMapLayersLocalCacheSizeInMB | Maximum size in MB. 0, the default, disables the cache; UINT_MAX means unlimited |
Leaving either at its default means there is no cache to opt into later — every per-layer request
then fails with IMcErrors::LOCAL_CACHE_NOT_INIT.
Per layer. Not every layer can cache, and the pattern is not the one you would guess — see
Which layers can cache below. Where it is supported, Create() takes a
final pLocalCacheLayerParams argument: pass an IMcMapLayer::SLocalCacheLayerParams whose
strLocalCacheSubFolder names this layer's own sub-folder of the device cache folder:
IMcMapLayer::SLocalCacheLayerParams CacheParams;
CacheParams.strLocalCacheSubFolder = "orthophoto";
IMcNativeRasterMapLayer *pLayer = NULL;
IMcErrors::ECode eCode = IMcNativeRasterMapLayer::Create(
&pLayer, "http://server/maps/orthophoto", UINT_MAX, false, 0, false,
&ReadCallback, &CacheParams);
The sub-folder is the cache's identity: two layers must not share one, and a second layer
naming an occupied sub-folder fails with IMcErrors::LAYER_ALREADY_EXISTS. Conversely, the same
layer reopened with the same sub-folder finds its previous contents, which is the whole point — the
cache survives the process.
The other field of the struct, strOriginalFolder, is output-only. It is filled when you read
parameters back and ignored when you pass them in.
Which layers can cache
Caching is a property of the layer interface, not of whether the layer happens to read over a network — and the split is counter-intuitive enough to check before you design around it:
| Layer | Takes pLocalCacheLayerParams |
|---|---|
| Raster, elevation, material and traversability — converted, raw and web-service forms | Yes |
| Vector — converted | Yes |
| Vector — raw | Only a rasterized (MAPNIK:) layer; any other returns IMcErrors::NOT_IMPLEMENTED |
| Every native-server layer | No |
| 3D model and vector-extrusion layers | No |
The two entries worth reading twice are the last two. A native-server layer talks to the Map Layer Server over HTTP and has no cache parameter at all — the most network-dependent layer in the SDK is the one you cannot give a disk cache. And a raw 3D-model or extrusion layer accepts a URL as its source directory, again with nowhere to pass cache parameters.
So "this layer reads over the network, therefore I can cache it" is not a safe inference. Check the
interface's Create() signature.
Read the cache back
IMcMapLayer::GetLocalCacheLayerParams() reports one layer's cache settings. It distinguishes two
cases that are easy to conflate: if the device has no cache it fails with
IMcErrors::LOCAL_CACHE_NOT_INIT, whereas if the device has one and only this layer was created
without it, the call succeeds with NULL strings.
IMcMapDevice::GetMapLayersLocalCacheParams() reports the whole cache: its folder, its maximum size
and its current size in MB, and optionally an array of per-layer parameters. It succeeds even
when there is no cache — the folder comes back NULL — so it is also the way to ask whether caching
is on without provoking an error.
Current size against maximum size is the number worth surfacing in an application that runs for a long time offline, because it is the one that predicts the next trim.
Resize and clear
IMcMapDevice::SetMapLayersLocalCacheSize() changes the maximum. Lowering it forces an immediate
trim, and that is the one call whose failure has a lasting consequence: if the cache cannot be
trimmed to the new size, it returns IMcErrors::LOCAL_CACHE_CANT_BE_TRIMMED and deactivates
itself. It does not carry on at the old size.
Two calls clear it:
| Call | Removes |
|---|---|
IMcMapDevice::RemoveMapLayerFromLocalCache() | One layer's sub-folder — or every layer, given NULL. Caching stays on |
IMcMapDevice::RemoveMapLayersLocalCache() | The cache folder itself, and it stops creating or using a local cache at all |
Those two are not "one layer" versus "all layers" — the per-layer call with NULL already empties
everything while leaving caching enabled. The second turns the feature off. Use it only when that
is what you mean.
Both refuse while a cached layer is open, returning IMcErrors::LOCAL_CACHE_HAS_ACTIVE_LAYER.
Remove the layers from their terrains first and let them be destroyed; then clear.
Failure modes and their codes
The first four surface from the layer's Create(), which is why a layer that creates fine
without a cache can fail with one. The last two come from the device calls above — a trim that
cannot fit, and a removal attempted while a cached layer is still open.
| Code | Cause | What to do |
|---|---|---|
IMcErrors::LOCAL_CACHE_NOT_INIT | The device was initialised without a cache folder or with size 0 | Set both SInitParams fields |
IMcErrors::LAYER_ALREADY_EXISTS | Another layer already uses this sub-folder | Give the layer its own |
IMcErrors::LOCAL_CACHE_CANT_CREATE_DIR | The sub-folder could not be created | Check the path and write permissions |
IMcErrors::CANT_READ_FILE | The cache's own files could not be read | The cache is damaged; remove that layer's sub-folder |
IMcErrors::LOCAL_CACHE_CANT_BE_TRIMMED | The cache cannot be reduced to its maximum size | The cache is now deactivated; raise the limit or clear it |
IMcErrors::LOCAL_CACHE_HAS_ACTIVE_LAYER | A removal was attempted while a cached layer is open | Destroy the layers first |
Treat all of these as non-fatal in application code. A failed cache is a slower map, not a broken one, and a layer that cannot cache is still worth creating without one.
Related network settings
Caching is one of four things that decide how a networked layer behaves. The others:
- Requests per fetch.
SetNumTilesInNativeServerRequest()sets how many tiles are asked of MapCore's Map Layer Server in a single request;0or1mean one tile per request, and the default is chosen by MapCore from the layer's type and properties. Native-server layers only. - Credentials.
IMcMapLayer::SetNativeServerCredentials()sets the token and session ID sent to the Map Layer Server when it requires them. It is static — the credentials are process-wide, not per layer — andGetNativeServerCredentials()reads them back, returning empty strings if they were never set. - Retries and concurrency.
SInitParams::uWebRequestRetryCount(default 10,0to disable) anduAsyncQueryTilesMaxActiveWebRequests(default 10) bound how hard the client retries and how many tile requests for asynchronous queries are in flight at once.