Table of Contents

Class RuntimeHandle

Namespace
Maplibre.NativeFfi
Assembly
Maplibre.NativeFfi.dll

A runtime owns maps and the network and cache settings that they share.

public sealed class RuntimeHandle : IDisposable, IAsyncDisposable
Inheritance
RuntimeHandle
Implements
Inherited Members

Remarks

See mln_runtime in the C API reference.

Properties

Discarding

Submits each command without a completion. Native logs a failure as a warning, and the caller sees none.

public RuntimeHandle.DiscardingCommands Discarding { get; }

Property Value

RuntimeHandle.DiscardingCommands

Id

The native handle value, which runtime events report as their source. It stays readable after release, so events drained later still match this handle.

public ulong Id { get; }

Property Value

ulong

IsClosed

Whether a release, dispose, or discard has ended the handle.

public bool IsClosed { get; }

Property Value

bool

Methods

ClearEventHandlerAsync()

Stops sending the events of the runtime and its maps to a callback.

public Task<CommandCompletion> ClearEventHandlerAsync()

Returns

Task<CommandCompletion>

Remarks

See mln_runtime_clear_event_handler in the C API reference.

ClearHttpHeaderTransformAsync()

Stops adding headers to the runtime's HTTP requests.

public Task<CommandCompletion> ClearHttpHeaderTransformAsync()

Returns

Task<CommandCompletion>

Remarks

See mln_runtime_clear_http_header_transform in the C API reference.

ClearResourceProviderAsync()

Removes the runtime's resource provider, so the library loads every request itself.

public Task<CommandCompletion> ClearResourceProviderAsync()

Returns

Task<CommandCompletion>

Remarks

See mln_runtime_clear_resource_provider in the C API reference.

ClearResourceTransformAsync()

Stops rewriting the URLs of the runtime's network requests.

public Task<CommandCompletion> ClearResourceTransformAsync()

Returns

Task<CommandCompletion>

Remarks

See mln_runtime_clear_resource_transform in the C API reference.

Create(RuntimeOptions?)

Creates a runtime.

public static RuntimeHandle Create(RuntimeOptions? options = null)

Parameters

options RuntimeOptions?

Returns

RuntimeHandle

Remarks

A runtime holds maps and the resource loading, cache, and offline regions that they share. In a browser, create runtimes on a Web Worker, not on the main thread.

See mln_runtime_create in the C API reference.

Errors:

  • Status.InvalidArgument when the cache database file that options names can't be opened or created.

CreateMap(MapOptions)

Creates a map on runtime.

public MapHandle CreateMap(MapOptions options)

Parameters

options MapOptions

Returns

MapHandle

Remarks

Asynchronous calls on the map before the completion runs wait for it, and complete with Status.InvalidState when creation fails.

See mln_runtime_create_map in the C API reference.

CreateOfflineRegionAsync(OfflineRegionDefinition, ReadOnlySpan<byte>)

Creates an offline region in the runtime's cache file.

public Task<OfflineRegionInfo> CreateOfflineRegionAsync(OfflineRegionDefinition definition, ReadOnlySpan<byte> metadata)

Parameters

definition OfflineRegionDefinition
metadata ReadOnlySpan<byte>

Returns

Task<OfflineRegionInfo>

Remarks

metadata holds any bytes to store with the region, such as its name. The region doesn't download until RuntimeHandle.SetOfflineRegionDownloadStateAsync() makes its download active.

See mln_runtime_create_offline_region in the C API reference.

DeleteOfflineRegionAsync(long)

Deletes the offline region regionId from the runtime's cache file.

public Task DeleteOfflineRegionAsync(long regionId)

Parameters

regionId long

Returns

Task

Remarks

See mln_runtime_delete_offline_region in the C API reference.

Errors:

  • Status.NotFound when the cache file has no region regionId.

Dispose()

Releases a runtime in any state, without waiting.

public void Dispose()

Remarks

The runtime finishes its teardown after its maps are released.

See mln_runtime_dispose in the C API reference.

GetOfflineRegionAsync(long)

Reads the offline region regionId.

public Task<OfflineRegionInfo?> GetOfflineRegionAsync(long regionId)

Parameters

regionId long

Returns

Task<OfflineRegionInfo?>

Remarks

The result is null when the cache file has no region with that ID.

See mln_runtime_get_offline_region in the C API reference.

GetOfflineRegionStatusAsync(long)

Reads the download progress of the offline region regionId.

public Task<OfflineRegionStatus> GetOfflineRegionStatusAsync(long regionId)

Parameters

regionId long

Returns

Task<OfflineRegionStatus>

Remarks

While the download is active, the counts cover what it has visited. Once it's inactive, they cover every resource the region holds, including those that only earlier versions of its style listed, so the completed counts can exceed the required counts.

See mln_runtime_get_offline_region_status in the C API reference.

Errors:

  • Status.NotFound when the cache file has no region regionId.

InvalidateOfflineRegionAsync(long)

Makes maps check each resource of the offline region regionId with the server before they use it.

public Task InvalidateOfflineRegionAsync(long regionId)

Parameters

regionId long

Returns

Task

Remarks

The region keeps its resources. Starting its download again fetches the invalidated resources for offline use. If the style or a TileJSON document is then missing or invalid, the download reports an offline region response error and goes on from the stored copy. Resources that the current style no longer lists stay in the region until it's deleted.

See mln_runtime_invalidate_offline_region in the C API reference.

Errors:

  • Status.NotFound when the cache file has no region regionId.

ListOfflineRegionsAsync()

Lists the offline regions in the runtime's cache file.

public Task<OfflineRegionInfo[]> ListOfflineRegionsAsync()

Returns

Task<OfflineRegionInfo[]>

Remarks

See mln_runtime_list_offline_regions in the C API reference.

MergeOfflineRegionsAsync(string)

Copies the offline regions of another cache file into the runtime's cache file.

public Task<OfflineRegionInfo[]> MergeOfflineRegionsAsync(string sideDatabasePath)

Parameters

sideDatabasePath string

Returns

Task<OfflineRegionInfo[]>

Remarks

A region whose definition and metadata match one that the runtime's file already has isn't copied again. The result lists the runtime's copy of each region in the other file.

See mln_runtime_merge_offline_regions in the C API reference.

Errors:

  • Status.InvalidArgument when sideDatabasePath isn't a readable database file.
  • Status.NativeError when the merge would exceed the tile limit that RuntimeEventType.OfflineRegionTileCountLimitExceeded describes.

ReleaseAsync()

Releases a runtime.

public Task ReleaseAsync()

Returns

Task

Remarks

Release the runtime's maps first.

See mln_runtime_release in the C API reference.

RunCacheDatabaseOperationAsync(CacheDatabaseOperation)

Runs a maintenance action on the runtime's cache database.

public Task RunCacheDatabaseOperationAsync(CacheDatabaseOperation operation)

Parameters

operation CacheDatabaseOperation

Returns

Task

Remarks

See mln_runtime_run_cache_database_operation in the C API reference.

SetEventHandlerAsync(RuntimeEventHandler)

Sends the events of the runtime and its maps to a callback.

public Task<CommandCompletion> SetEventHandlerAsync(RuntimeEventHandler handler)

Parameters

handler RuntimeEventHandler

Returns

Task<CommandCompletion>

Remarks

The callback replaces the one set before.

See mln_runtime_set_event_handler in the C API reference.

SetHttpHeaderTransformAsync(HttpHeaderTransform)

Adds headers to the runtime's HTTP requests.

public Task<CommandCompletion> SetHttpHeaderTransformAsync(HttpHeaderTransform transform)

Parameters

transform HttpHeaderTransform

Returns

Task<CommandCompletion>

Remarks

The transform replaces the one set before. In a browser or on OpenHarmony, serve the requests with RuntimeHandle.SetResourceProviderAsync() instead.

Runs on a library thread.

See mln_runtime_set_http_header_transform in the C API reference.

Errors:

  • Status.Unsupported when the library runs in a browser or on OpenHarmony.

SetMaximumAmbientCacheSizeAsync(ulong)

Limits the size of the runtime's ambient cache.

public Task SetMaximumAmbientCacheSizeAsync(ulong size)

Parameters

size ulong

Returns

Task

Remarks

size is in bytes. Offline regions don't count toward it. It defaults to 50 MB, or to 0 in the browser when the runtime has no cache file.

See mln_runtime_set_maximum_ambient_cache_size in the C API reference.

SetOfflineRegionDownloadStateAsync(long, OfflineRegionDownloadState)

Starts or pauses the download of the offline region regionId.

public Task SetOfflineRegionDownloadStateAsync(long regionId, OfflineRegionDownloadState state)

Parameters

regionId long
state OfflineRegionDownloadState

Returns

Task

Remarks

Setting the state that the download already has does nothing. A download stops when the runtime closes.

See mln_runtime_set_offline_region_download_state in the C API reference.

Errors:

  • Status.NotFound when the cache file has no region regionId.

SetOfflineRegionObservedAsync(long, RuntimeEventFlag)

Selects the events that the runtime reports about the download of the offline region regionId.

public Task SetOfflineRegionObservedAsync(long regionId, RuntimeEventFlag events)

Parameters

regionId long
events RuntimeEventFlag

Returns

Task

Remarks

events holds bits of RuntimeEventFlag.AllRuntimeEvents and replaces the region's previous selection. RuntimeEventFlag.None stops the region's events.

See mln_runtime_set_offline_region_observed in the C API reference.

Errors:

  • Status.NotFound when the cache file has no region regionId.

SetResourceProviderAsync(ResourceProvider)

Serves the runtime's network requests through a callback.

public Task<CommandCompletion> SetResourceProviderAsync(ResourceProvider provider)

Parameters

provider ResourceProvider

Returns

Task<CommandCompletion>

Remarks

The provider receives the network requests that its routes match, and the library loads the rest as usual. A provider can serve URL schemes that the library can't load itself. The provider replaces the one set before.

See mln_runtime_set_resource_provider in the C API reference.

SetResourceTransformAsync(ResourceTransform)

Rewrites the URLs of the runtime's network requests.

public Task<CommandCompletion> SetResourceTransformAsync(ResourceTransform transform)

Parameters

transform ResourceTransform

Returns

Task<CommandCompletion>

Remarks

The transform replaces the one set before.

See mln_runtime_set_resource_transform in the C API reference.

ToString()

Names the handle's type, its Id, and whether it is closed.

public override string ToString()

Returns

string

UpdateOfflineRegionMetadataAsync(long, ReadOnlySpan<byte>)

Replaces the metadata of the offline region regionId.

public Task<OfflineRegionInfo> UpdateOfflineRegionMetadataAsync(long regionId, ReadOnlySpan<byte> metadata)

Parameters

regionId long
metadata ReadOnlySpan<byte>

Returns

Task<OfflineRegionInfo>

Remarks

See mln_runtime_update_offline_region_metadata in the C API reference.

Errors:

  • Status.NotFound when the cache file has no region regionId.