Class MbglOfflineManager

Namespace

MapLibreNative.Maui

Manages offline region downloads and the ambient cache. Wraps mbgl_offline_manager_t. Dispose when done; in-flight operations complete safely after disposal.

public sealed class MbglOfflineManager : IDisposable

Inheritance

object

MbglOfflineManager

Constructors

MbglOfflineManager(string?, string?, string?, ulong)

public MbglOfflineManager(string? cachePath = null, string? assetPath = null, string? apiKey = null, ulong maxCacheSizeBytes = 0)

Parameters

cachePath string

Path of the cache database — use the same value the map was created with. Defaults to DefaultPath, which the map views also use by default, so the database is shared.

assetPath string

Asset path matching the map's, or null.

apiKey string

API key matching the map's, or null.

maxCacheSizeBytes ulong

Maximum cache database size, or 0 for the default.

Fields

TileCountLimitReason

Reason value meaning the Mapbox tile count limit was exceeded.

public const int TileCountLimitReason = 100

Field Value

int

Methods

ClearAmbientCacheAsync()

Erases the ambient cache. Offline regions are not affected.

public Task ClearAmbientCacheAsync()

Returns

Task

CreateRegionAsync(string, double, double, double, double, double, double, float, bool, byte[]?)

Creates a tile-pyramid offline region (style + lat/lng bounds + zoom range). The region starts inactive — call SetDownloadState(long, bool) to begin downloading, optionally after ObserveRegion(long).

public Task<MbglOfflineRegion> CreateRegionAsync(string styleUrl, double latSw, double lonSw, double latNe, double lonNe, double minZoom, double maxZoom, float pixelRatio = 1, bool includeIdeographs = true, byte[]? metadata = null)

Parameters

styleUrl string

latSw double

lonSw double

latNe double

lonNe double

minZoom double

maxZoom double

pixelRatio float

includeIdeographs bool

metadata byte[]

Returns

Task<MbglOfflineRegion>

CreateRegionAsync(string, string, double, double, float, bool, byte[]?)

Creates an offline region covering a GeoJSON geometry (a Geometry, Feature, or single-feature FeatureCollection).

public Task<MbglOfflineRegion> CreateRegionAsync(string styleUrl, string geometryGeoJson, double minZoom, double maxZoom, float pixelRatio = 1, bool includeIdeographs = true, byte[]? metadata = null)

Parameters

styleUrl string

geometryGeoJson string

minZoom double

maxZoom double

pixelRatio float

includeIdeographs bool

metadata byte[]

Returns

Task<MbglOfflineRegion>

DeleteRegionAsync(long)

Deletes a region and evicts its resources.

public Task DeleteRegionAsync(long regionId)

Parameters

regionId long

Returns

Task

Dispose()

public void Dispose()

GetRegionMetadata(long)

Reads a region's metadata from the manager's cache — the region must have been returned by a previous list/create/merge on this manager. Returns the metadata as of that call (an UpdateRegionMetadataAsync(long, byte[]) is reflected after the next ListRegionsAsync()).

public byte[]? GetRegionMetadata(long regionId)

Parameters

regionId long

Returns

byte[]

GetRegionStatusAsync(long)

Queries the current download status of a region. Note: if a required resource permanently 404s (e.g. a glyph range the server doesn't have), Complete from this query can stay false even though the download has finished — the RegionProgress observer's Complete flag is the authoritative completion signal.

public Task<MbglOfflineRegionStatus> GetRegionStatusAsync(long regionId)

Parameters

regionId long

Returns

Task<MbglOfflineRegionStatus>

InvalidateAmbientCacheAsync()

Forces revalidation of ambient-cache resources with the server.

public Task InvalidateAmbientCacheAsync()

Returns

Task

InvalidateRegionAsync(long)

Forces revalidation of the region's tiles with the server.

public Task InvalidateRegionAsync(long regionId)

Parameters

regionId long

Returns

Task

ListRegionsAsync()

Lists all offline regions in the database.

public Task<MbglOfflineRegion[]> ListRegionsAsync()

Returns

Task<MbglOfflineRegion[]>

MergeDatabaseAsync(string)

Merges regions from a secondary cache database file into this one (side-loading). The side database may be upgraded in place.

public Task<MbglOfflineRegion[]> MergeDatabaseAsync(string sideDbPath)

Parameters

sideDbPath string

Returns

Task<MbglOfflineRegion[]>

ObserveRegion(long)

Installs a progress/error observer for the region, routed to RegionProgress and RegionError (raised on the database thread). Replaces any previous observer for the region.

public void ObserveRegion(long regionId)

Parameters

regionId long

PackDatabaseAsync()

Vacuums the database file to reclaim disk space.

public Task PackDatabaseAsync()

Returns

Task

ResetDatabaseAsync()

Deletes and re-initialises the database — regions AND ambient cache.

public Task ResetDatabaseAsync()

Returns

Task

SetDownloadState(long, bool)

Starts (true) or pauses (false) downloading the region's resources.

public void SetDownloadState(long regionId, bool active)

Parameters

regionId long

active bool

SetMaximumAmbientCacheSizeAsync(ulong)

Caps the ambient (non-region) cache size in bytes.

public Task SetMaximumAmbientCacheSizeAsync(ulong bytes)

Parameters

bytes ulong

Returns

Task

SetPackDatabaseAutomatically(bool)

Enables/disables automatic packing after deletions (default on).

public void SetPackDatabaseAutomatically(bool enabled)

Parameters

enabled bool

SetTileCountLimit(ulong)

Sets the Mapbox tile count limit (does not affect non-Mapbox sources).

public void SetTileCountLimit(ulong limit)

Parameters

limit ulong

StopObservingRegion(long)

Removes the region's observer.

public void StopObservingRegion(long regionId)

Parameters

regionId long

UpdateRegionMetadataAsync(long, byte[])

Replaces the region's opaque binary metadata.

public Task UpdateRegionMetadataAsync(long regionId, byte[] metadata)

Parameters

regionId long

metadata byte[]

Returns

Task

Events

RegionError

Raised (on the database thread) when an observed region hits a download error. Errors are usually recoverable — the downloader retries with backoff.

public event Action<MbglOfflineError>? RegionError

Event Type

Action<MbglOfflineError>?

RegionProgress

Raised (on the database thread) when an observed region's download progresses.

public event Action<MbglOfflineProgress>? RegionProgress

Event Type

Action<MbglOfflineProgress>?