runtime.h File Reference

Go to the source code of this file.

Data Structures
struct	mln_offline_region_status
struct	mln_rendering_stats
struct	mln_runtime_event_render_frame
struct	mln_runtime_event_render_map
struct	mln_runtime_event_style_image_missing
struct	mln_tile_id
struct	mln_runtime_event_tile_action
struct	mln_runtime_event_offline_region_status
struct	mln_runtime_event_offline_region_response_error
struct	mln_runtime_event_offline_region_tile_count_limit
struct	mln_runtime_event_offline_operation_completed
struct	mln_runtime_event

Typedefs
typedef uint64_t	mln_offline_operation_id
typedef mln_status(*	mln_resource_transform_callback) (void *user_data, uint32_t kind, const char *url, mln_resource_transform_response *out_response)
typedef uint32_t(*	mln_resource_provider_callback) (void *user_data, const mln_resource_request *request, mln_resource_request_handle *handle)

Enumerations
enum	mln_offline_operation_kind : uint32_t
enum	mln_offline_operation_result_kind : uint32_t
enum	mln_runtime_event_type : uint32_t
enum	mln_runtime_event_source_type : uint32_t
enum	mln_runtime_event_payload_type : uint32_t
enum	mln_render_mode : uint32_t
enum	mln_tile_operation : uint32_t

Functions
mln_status	mln_network_status_get (uint32_t *out_status)
mln_status	mln_network_status_set (uint32_t status)
mln_status	mln_resource_transform_response_set_url (mln_resource_transform_response *response, const char *url, size_t url_size)
mln_runtime_options	mln_runtime_options_default (void)
mln_status	mln_runtime_create (const mln_runtime_options *options, mln_runtime **out_runtime)
mln_status	mln_runtime_set_resource_provider (mln_runtime *runtime, const mln_resource_provider *provider)
mln_status	mln_resource_request_complete (mln_resource_request_handle *handle, const mln_resource_response *response)
mln_status	mln_resource_request_cancelled (const mln_resource_request_handle *handle, bool *out_cancelled)
void	mln_resource_request_release (mln_resource_request_handle *handle)
mln_status	mln_runtime_set_resource_transform (mln_runtime *runtime, const mln_resource_transform *transform)
mln_status	mln_runtime_clear_resource_transform (mln_runtime *runtime)
mln_status	mln_runtime_run_ambient_cache_operation_start (mln_runtime *runtime, uint32_t operation, mln_offline_operation_id *out_operation_id)
mln_status	mln_runtime_offline_operation_discard (mln_runtime *runtime, mln_offline_operation_id operation_id)
mln_status	mln_runtime_destroy (mln_runtime *runtime)
mln_status	mln_runtime_run_once (mln_runtime *runtime)
mln_status	mln_runtime_poll_event (mln_runtime *runtime, mln_runtime_event *out_event, bool *out_has_event)

Detailed Description

Public C API declarations for runtime, resources, and events.

Typedef Documentation

mln_offline_operation_id

typedef uint64_t mln_offline_operation_id

Offline database operation token. Zero is never a valid operation ID.

mln_resource_provider_callback

typedef uint32_t(* mln_resource_provider_callback) (void *user_data, const mln_resource_request *request, mln_resource_request_handle *handle)

Intercepts a network resource request.

The callback runs synchronously on the thread that reaches the C API network file source. That thread may be a MapLibre worker or network thread instead of the runtime owner thread.

Request handling follows these rules:

• request and its pointed-to fields are borrowed for the callback duration.
• MLN_RESOURCE_PROVIDER_DECISION_PASS_THROUGH lets native OnlineFileSource handle the request.
• After returning PASS_THROUGH, the provider must not retain, complete, or release the handle.
• MLN_RESOURCE_PROVIDER_DECISION_HANDLE lets the provider complete the request through the handle inline or later.
• Unknown decision values produce a provider error response. The C API releases the provided handle and does not pass the request through.
• The C API copies completion data, and mln_resource_request_complete() may be called from any thread.
• Providers must release handled request handles after they no longer need to complete or observe cancellation.
• The callback must be thread-safe, return quickly, and must not call map or runtime C API functions.
• The callback may call resource request handle functions for the provided handle.

mln_resource_transform_callback

typedef mln_status(* mln_resource_transform_callback) (void *user_data, uint32_t kind, const char *url, mln_resource_transform_response *out_response)

Rewrites a network resource URL.

This callback can only replace the request URL. It cannot mutate headers, bodies, cache policy, or convert a request into an error.

Callback invocations follow these rules:

• MapLibre may invoke the callback on a worker or network thread instead of the runtime owner thread.
• The callback must be thread-safe, return quickly, and must not call C API functions other than mln_resource_transform_response_set_url().
• url and out_response are borrowed for the callback duration.
• Use mln_resource_transform_response_set_url() to set a replacement URL from temporary host-language storage. The helper copies the URL into C API-managed storage for the current transform invocation.
• A non-OK return status is treated as no rewrite and does not fail the resource request.
• The callback and user_data must remain valid until the transform is replaced, cleared, or the runtime is destroyed. Those calls wait for in-flight transform callbacks before returning.

Enumeration Type Documentation

mln_offline_operation_kind

enum mln_offline_operation_kind : uint32_t

Offline database operation kinds reported by completion events.

mln_offline_operation_result_kind

enum mln_offline_operation_result_kind : uint32_t

Offline database operation result kinds reported by completion events.

mln_render_mode

enum mln_render_mode : uint32_t

Render modes reported by render observer events.

mln_runtime_event_payload_type

enum mln_runtime_event_payload_type : uint32_t

Payload kinds used by mln_runtime_event.payload_type.

mln_runtime_event_source_type

enum mln_runtime_event_source_type : uint32_t

Source kinds used by mln_runtime_event.source_type.

mln_runtime_event_type

enum mln_runtime_event_type : uint32_t

Runtime event types returned by mln_runtime_poll_event().

mln_tile_operation

enum mln_tile_operation : uint32_t

Tile operations reported by tile observer events.

Function Documentation

mln_network_status_get()

mln_status mln_network_status_get

(

uint32_t *

out_status

)

Reads MapLibre Native's process-global network status.

On success, out_status receives a mln_network_status value.

Returns:

• MLN_STATUS_OK on success.
• MLN_STATUS_INVALID_ARGUMENT when out_status is null.
• MLN_STATUS_NATIVE_ERROR when an internal exception is converted to status.

mln_network_status_set()

mln_status mln_network_status_set

(

uint32_t

status

)

Sets MapLibre Native's process-global network status.

MLN_NETWORK_STATUS_ONLINE allows HTTP and HTTPS requests and wakes native subscribers when transitioning from offline. MLN_NETWORK_STATUS_OFFLINE makes MapLibre's online source stop starting network requests until reachability returns. Runtime-scoped resource configuration is unchanged.

Returns:

• MLN_STATUS_OK on success.
• MLN_STATUS_INVALID_ARGUMENT when status is not a mln_network_status value.
• MLN_STATUS_NATIVE_ERROR when an internal exception is converted to status.

mln_resource_request_cancelled()

mln_status mln_resource_request_cancelled	(	const mln_resource_request_handle *	handle,
		bool *	out_cancelled )

Reports whether MapLibre has cancelled a C API resource provider request.

This function may be called from any thread while the provider still owns the handle. A cancelled request no longer wants a response; later completion is ignored with MLN_STATUS_INVALID_STATE.

Returns:

• MLN_STATUS_OK on success.
• MLN_STATUS_INVALID_ARGUMENT when handle or out_cancelled is null.

mln_resource_request_complete()

mln_status mln_resource_request_complete	(	mln_resource_request_handle *	handle,
		const mln_resource_response *	response )

Completes a C API resource provider request.

This function may be called inline from the provider callback or later from any thread. The C API copies all response bytes and strings before returning.

Completion is one-shot. A second completion, completion after cancellation, or completion with null arguments returns a non-OK status and does not invoke MapLibre's resource callback. Malformed response contents are converted to provider error responses and still consume the completion.

Returns:

• MLN_STATUS_OK when the response was accepted for asynchronous delivery.
• MLN_STATUS_INVALID_ARGUMENT when handle or response is null.
• MLN_STATUS_INVALID_STATE when the request was cancelled, already completed, or can no longer accept a response.
• MLN_STATUS_NATIVE_ERROR when an internal exception is converted to status.

mln_resource_request_release()

void mln_resource_request_release

(

mln_resource_request_handle *

handle

)

Releases the provider's reference to a resource request handle.

Providers own a releasable handle only after returning MLN_RESOURCE_PROVIDER_DECISION_HANDLE from the callback. Release the handle exactly once after completing the request or deciding not to complete it. Passing null is a no-op. A released handle must not be used again.

mln_resource_transform_response_set_url()

mln_status mln_resource_transform_response_set_url	(	mln_resource_transform_response *	response,
		const char *	url,
		size_t	url_size )

Copies a replacement URL into C API-managed storage for the current callback.

Use this helper inside mln_resource_transform_callback implementations to set out_response->url from temporary host-language storage. The copied URL stays valid until the current resource transform invocation finishes. Empty input clears the replacement URL.

Returns MLN_STATUS_INVALID_ARGUMENT when response is null, response->size is too small, url is null with a non-zero size, or url contains embedded NUL. Returns MLN_STATUS_INVALID_STATE when called outside a resource transform callback.

mln_runtime_clear_resource_transform()

mln_status mln_runtime_clear_resource_transform

(

mln_runtime *

runtime

)

Clears the runtime-scoped URL transform for network resources.

After this call succeeds, network resource URLs pass through unchanged. When it returns, no in-flight request can still invoke the previous transform.

Returns:

• MLN_STATUS_OK on success.
• MLN_STATUS_INVALID_ARGUMENT when runtime is null or not live.
• MLN_STATUS_WRONG_THREAD when called from a thread other than the runtime owner thread.
• MLN_STATUS_NATIVE_ERROR when an internal exception is converted to status.

mln_runtime_create()

mln_status mln_runtime_create	(	const mln_runtime_options *	options,
		mln_runtime **	out_runtime )

Creates a runtime handle.

The creating thread becomes the runtime owner thread. Each owner thread may hold one live runtime.

Returns:

• MLN_STATUS_OK on success.
• MLN_STATUS_INVALID_ARGUMENT when out_runtime is null, *out_runtime is not null, or options has an unsupported size or flags.
• MLN_STATUS_INVALID_STATE when the current thread already owns a live runtime.
• MLN_STATUS_NATIVE_ERROR when an internal exception is converted to status.

mln_runtime_destroy()

mln_status mln_runtime_destroy

(

mln_runtime *

runtime

)

Destroys a runtime handle.

The runtime must no longer own live maps.

Returns:

• MLN_STATUS_OK on success.
• MLN_STATUS_INVALID_ARGUMENT when runtime is null or not a live runtime handle.
• MLN_STATUS_INVALID_STATE when runtime still owns live maps.
• MLN_STATUS_WRONG_THREAD when called from a thread other than the creating thread.
• MLN_STATUS_NATIVE_ERROR when an internal exception is converted to status.

mln_runtime_offline_operation_discard()

mln_status mln_runtime_offline_operation_discard	(	mln_runtime *	runtime,
		mln_offline_operation_id	operation_id )

Discards runtime-owned state for an offline database operation.

Discarding does not cancel native database work. It drops stored results, removes queued completion events for the operation, and suppresses later completion delivery when the native operation is still pending.

Returns:

• MLN_STATUS_OK on success.
• MLN_STATUS_INVALID_ARGUMENT when runtime is null or not live, or operation_id is zero or unknown.
• MLN_STATUS_WRONG_THREAD when called from a thread other than the runtime owner thread.
• MLN_STATUS_NATIVE_ERROR when an internal exception is converted to status.

mln_runtime_options_default()

mln_runtime_options mln_runtime_options_default

(

void

)

Returns runtime options initialized for this C API version.

mln_runtime_poll_event()

mln_status mln_runtime_poll_event	(	mln_runtime *	runtime,
		mln_runtime_event *	out_event,
		bool *	out_has_event )

Pops the next queued runtime event.

On success, *out_event is reset and *out_has_event indicates whether an event was available. When an event is available, *out_event receives it. Map-originated events set out_event->source_type to MLN_RUNTIME_EVENT_SOURCE_MAP and out_event->source to the source map. Runtime-originated events set out_event->source_type to MLN_RUNTIME_EVENT_SOURCE_RUNTIME.

When an event is available, out_event->payload points to runtime-owned storage containing a struct selected by out_event->payload_type, or null when the payload type is MLN_RUNTIME_EVENT_PAYLOAD_NONE. String pointers inside typed payloads and out_event->message remain valid until the next mln_runtime_poll_event() call for the same runtime or until the runtime is destroyed. Copy those bytes before then when they must outlive that window. For style-image-missing and tile-action events, out_event->message contains the same ID string exposed by the typed payload.

Returns:

• MLN_STATUS_OK when the poll completed; out_has_event indicates whether an event was written to out_event.
• MLN_STATUS_INVALID_ARGUMENT when runtime is null or not live, out_event is null, out_has_event is null, or out_event->size is too small.
• MLN_STATUS_WRONG_THREAD when called from a thread other than the runtime owner thread.
• MLN_STATUS_NATIVE_ERROR when an internal exception is converted to status.

mln_runtime_run_ambient_cache_operation_start()

mln_status mln_runtime_run_ambient_cache_operation_start	(	mln_runtime *	runtime,
		uint32_t	operation,
		mln_offline_operation_id *	out_operation_id )

Starts a MapLibre ambient cache maintenance operation for this runtime.

When runtime options omit cache_path, this operates on MapLibre's default in-memory database and its effects are not durable beyond the native database lifetime. Completion is reported through MLN_RUNTIME_EVENT_OFFLINE_OPERATION_COMPLETED.

Returns:

• MLN_STATUS_OK when the operation was accepted and out_operation_id was set.
• MLN_STATUS_INVALID_ARGUMENT when runtime is null or not live, or operation is not a mln_ambient_cache_operation value, or out_operation_id is null.
• MLN_STATUS_WRONG_THREAD when called from a thread other than the runtime owner thread.
• MLN_STATUS_NATIVE_ERROR when an internal exception is converted to status.

mln_runtime_run_once()

mln_status mln_runtime_run_once

(

mln_runtime *

runtime

)

Runs one pending owner-thread task for this runtime.

If no task is pending, the call returns MLN_STATUS_OK without doing work.

Returns:

• MLN_STATUS_OK on success.
• MLN_STATUS_INVALID_ARGUMENT when runtime is null or not a live runtime handle.
• MLN_STATUS_WRONG_THREAD when called from a thread other than the runtime owner thread.
• MLN_STATUS_NATIVE_ERROR when an internal exception is converted to status.

mln_runtime_set_resource_provider()

mln_status mln_runtime_set_resource_provider	(	mln_runtime *	runtime,
		const mln_resource_provider *	provider )

Sets a runtime-scoped network resource provider.

The provider must be set before any map is created from the runtime. It is invoked for requests that reach the C API network file source. Built-in non-network schemes such as file, asset, mbtiles, and pmtiles are handled by native MainResourceLoader before this extension point. The callback and user_data are stored by reference and must remain valid until the runtime is destroyed.

Returns:

• MLN_STATUS_OK on success.
• MLN_STATUS_INVALID_ARGUMENT when runtime is null or not live, provider is null, provider->size is too small, or callback is null.
• MLN_STATUS_INVALID_STATE when runtime already owns live maps.
• MLN_STATUS_WRONG_THREAD when called from a thread other than the runtime owner thread.
• MLN_STATUS_NATIVE_ERROR when an internal exception is converted to status.

mln_runtime_set_resource_transform()

mln_status mln_runtime_set_resource_transform	(	mln_runtime *	runtime,
		const mln_resource_transform *	transform )

Registers or updates a runtime-scoped URL transform for network resources.

It is forwarded to MapLibre's OnlineFileSource, so it applies wherever native OnlineFileSource applies transforms, including nested PMTiles network range requests. It does not apply to file, asset, database, MBTiles, or registered C API provider responses intercepted before OnlineFileSource.

This call may replace an existing transform while maps exist. When it returns, no in-flight request can still invoke the previous transform.

Returns:

• MLN_STATUS_OK on success.
• MLN_STATUS_INVALID_ARGUMENT when runtime is null or not live, transform is null, transform->size is too small, or callback is null.
• MLN_STATUS_WRONG_THREAD when called from a thread other than the runtime owner thread.
• MLN_STATUS_NATIVE_ERROR when an internal exception is converted to status.