runtime.h File Reference
Go to the source code of this file.
Data Structures | |
| struct | mln_offline_region_status |
| struct | mln_runtime_options |
| struct | mln_rendering_stats |
| struct | mln_runtime_event_render_frame |
| struct | mln_runtime_event_render_map |
| 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 |
| union | mln_runtime_event_payload |
| struct | mln_runtime_event |
| struct | mln_event_batch_view |
| struct | mln_runtime_event_handler |
| struct | mln_resource_route |
| struct | mln_http_header |
| struct | mln_http_header_rule |
| struct | mln_resource_transform |
| struct | mln_http_header_transform |
| struct | mln_resource_range |
| struct | mln_resource_response |
| struct | mln_resource_request_cancel_handler |
| struct | mln_resource_provider |
Typedefs | |
| typedef struct mln_offline_region_status | mln_offline_region_status |
| typedef enum mln_runtime_event_type | mln_runtime_event_type |
| typedef enum mln_runtime_event_mask | mln_runtime_event_mask |
| typedef enum mln_runtime_event_source_type | mln_runtime_event_source_type |
| typedef enum mln_runtime_event_payload_type | mln_runtime_event_payload_type |
| typedef enum mln_camera_change_mode | mln_camera_change_mode |
| typedef enum mln_render_mode | mln_render_mode |
| typedef enum mln_tile_operation | mln_tile_operation |
| typedef enum mln_resource_response_status | mln_resource_response_status |
| typedef struct mln_runtime_options | mln_runtime_options |
| typedef struct mln_rendering_stats | mln_rendering_stats |
| typedef struct mln_runtime_event_render_frame | mln_runtime_event_render_frame |
| typedef struct mln_runtime_event_render_map | mln_runtime_event_render_map |
| typedef struct mln_tile_id | mln_tile_id |
| typedef struct mln_runtime_event_tile_action | mln_runtime_event_tile_action |
| typedef struct mln_runtime_event_offline_region_status | mln_runtime_event_offline_region_status |
| typedef struct mln_runtime_event_offline_region_response_error | mln_runtime_event_offline_region_response_error |
| typedef struct mln_runtime_event_offline_region_tile_count_limit | mln_runtime_event_offline_region_tile_count_limit |
| typedef union mln_runtime_event_payload | mln_runtime_event_payload |
| typedef struct mln_runtime_event | mln_runtime_event |
| typedef struct mln_event_batch_view | mln_event_batch_view |
| typedef void(*) | mln_runtime_event_callback(void *user_data, const mln_event_batch_view *events) |
| typedef struct mln_runtime_event_handler | mln_runtime_event_handler |
| typedef enum mln_resource_kind_mask | mln_resource_kind_mask |
| typedef enum mln_url_match_flags | mln_url_match_flags |
| typedef struct mln_resource_route | mln_resource_route |
| typedef struct mln_http_header | mln_http_header |
| typedef struct mln_http_header_rule | mln_http_header_rule |
| typedef void(*) | mln_resource_transform_callback(void *user_data, uint32_t kind, const char *url, mln_resource_transform_request request) |
| typedef struct mln_resource_transform | mln_resource_transform |
| typedef mln_status(*) | mln_http_header_transform_callback(void *user_data, uint32_t kind, const char *url, mln_http_header_transform_response *out_response) |
| typedef struct mln_http_header_transform | mln_http_header_transform |
| typedef struct mln_resource_range | mln_resource_range |
| typedef enum mln_resource_request_field | mln_resource_request_field |
| typedef enum mln_resource_response_field | mln_resource_response_field |
| typedef struct mln_resource_response | mln_resource_response |
| typedef uint32_t(*) | mln_resource_provider_callback(void *user_data, const mln_resource_request_info *request, mln_resource_request handle) |
| typedef void(*) | mln_resource_request_cancel_callback(void *user_data, mln_resource_request handle) |
| typedef struct mln_resource_request_cancel_handler | mln_resource_request_cancel_handler |
| typedef struct mln_resource_provider | mln_resource_provider |
Enumerations | |
| enum | mln_runtime_event_type : uint32_t |
| enum | mln_runtime_event_mask : uint64_t { MLN_RUNTIME_EVENT_MASK_NONE = 0 , MLN_RUNTIME_EVENT_MASK_MAP_CAMERA_WILL_CHANGE , MLN_RUNTIME_EVENT_MASK_MAP_CAMERA_IS_CHANGING , MLN_RUNTIME_EVENT_MASK_MAP_CAMERA_DID_CHANGE , MLN_RUNTIME_EVENT_MASK_MAP_STYLE_LOADED , MLN_RUNTIME_EVENT_MASK_MAP_LOADING_STARTED , MLN_RUNTIME_EVENT_MASK_MAP_LOADING_FINISHED , MLN_RUNTIME_EVENT_MASK_MAP_LOADING_FAILED , MLN_RUNTIME_EVENT_MASK_MAP_IDLE = 1ULL << MLN_RUNTIME_EVENT_MAP_IDLE , MLN_RUNTIME_EVENT_MASK_MAP_RENDER_ERROR , MLN_RUNTIME_EVENT_MASK_MAP_RENDER_FRAME_STARTED , MLN_RUNTIME_EVENT_MASK_MAP_RENDER_FRAME_FINISHED , MLN_RUNTIME_EVENT_MASK_MAP_RENDER_MAP_STARTED , MLN_RUNTIME_EVENT_MASK_MAP_RENDER_MAP_FINISHED , MLN_RUNTIME_EVENT_MASK_MAP_STYLE_IMAGE_MISSING , MLN_RUNTIME_EVENT_MASK_MAP_TILE_ACTION , MLN_RUNTIME_EVENT_MASK_OFFLINE_REGION_STATUS_CHANGED , MLN_RUNTIME_EVENT_MASK_OFFLINE_REGION_RESPONSE_ERROR , MLN_RUNTIME_EVENT_MASK_OFFLINE_REGION_TILE_COUNT_LIMIT_EXCEEDED , MLN_RUNTIME_EVENT_MASK_MAP_SOURCE_CHANGED , MLN_RUNTIME_EVENT_MASK_ALL_MAP_EVENTS , MLN_RUNTIME_EVENT_MASK_ALL_RUNTIME_EVENTS , MLN_RUNTIME_EVENT_MASK_ALL } |
| enum | mln_runtime_event_source_type : uint32_t |
| enum | mln_runtime_event_payload_type : uint32_t |
| enum | mln_camera_change_mode : uint32_t { MLN_CAMERA_CHANGE_MODE_IMMEDIATE = 0 , MLN_CAMERA_CHANGE_MODE_ANIMATED = 1 } |
| enum | mln_render_mode : uint32_t |
| enum | mln_tile_operation : uint32_t |
| enum | mln_resource_response_status : uint32_t |
| enum | mln_resource_kind_mask : uint32_t |
| enum | mln_url_match_flags : uint32_t { } |
| enum | mln_resource_request_field : uint32_t { MLN_RESOURCE_REQUEST_RANGE = 1U << 0U , MLN_RESOURCE_REQUEST_PRIOR_MODIFIED = 1U << 1U , MLN_RESOURCE_REQUEST_PRIOR_EXPIRES = 1U << 2U } |
| enum | mln_resource_response_field : uint32_t { MLN_RESOURCE_RESPONSE_MODIFIED = 1U << 0U , MLN_RESOURCE_RESPONSE_EXPIRES = 1U << 1U , MLN_RESOURCE_RESPONSE_RETRY_AFTER = 1U << 2U } |
Detailed Description
Public C API declarations for runtime, resources, and events.
Typedef Documentation
◆ mln_camera_change_mode
| typedef enum mln_camera_change_mode mln_camera_change_mode |
Camera change kinds reported by camera will-change and did-change events.
◆ mln_event_batch_view
| typedef struct mln_event_batch_view mln_event_batch_view |
A borrowed span of runtime events in one delivery.
Step through events by event_size. The event and message pointers remain valid during the callback, or until the delivery batch is released in queue mode.
◆ mln_http_header
| typedef struct mln_http_header mln_http_header |
One HTTP header that a header rule supplies.
◆ mln_http_header_rule
| typedef struct mln_http_header_rule mln_http_header_rule |
One rule of a native HTTP header transform.
The first rule whose kind and URL match supplies all its headers, including an empty header list that stops the search.
◆ mln_http_header_transform
| typedef struct mln_http_header_transform mln_http_header_transform |
HTTP header transform state: a callback, or native header rules.
The struct itself is borrowed for the registering call, which copies every rule, header, and string before it returns. With a null callback, the first rule that matches a request supplies all its headers. A transform requires a callback or at least one rule; clear it through mln_runtime_clear_http_header_transform(). A rules transform carries no user_data or release_user_data.
◆ mln_http_header_transform_callback
| typedef mln_status(*) mln_http_header_transform_callback(void *user_data, uint32_t kind, const char *url, mln_http_header_transform_response *out_response) |
Adds end-to-end headers to one outgoing HTTP request attempt.
MapLibre invokes the callback synchronously on a worker or network thread after resource URL transformation and immediately before the platform HTTP transport starts the attempt. kind is one mln_resource_kind value and url is the transformed URL that the transport will request.
The callback and user_data must be thread-safe. The C API invokes release_user_data after the final callback returns. url and out_response are borrowed for the callback duration. Callbacks return promptly and must not wait for work that only their own thread can advance. A non-OK result discards every header collected during the invocation and lets the request proceed unchanged.
◆ mln_offline_region_status
| typedef struct mln_offline_region_status mln_offline_region_status |
Offline region status snapshot.
◆ mln_render_mode
| typedef enum mln_render_mode mln_render_mode |
Render modes reported by render observer events.
◆ mln_rendering_stats
| typedef struct mln_rendering_stats mln_rendering_stats |
Rendering statistics reported in MLN_RUNTIME_EVENT_PAYLOAD_RENDER_FRAME.
mln_event_batch_view.event_size covers the whole event, including these statistics.
◆ mln_resource_kind_mask
| typedef enum mln_resource_kind_mask mln_resource_kind_mask |
The resource kinds that a route or rule matches, one bit per mln_resource_kind value. Registration requires at least one known bit. MLN_RESOURCE_KIND_MASK_ALL selects every resource kind.
◆ mln_resource_provider
| typedef struct mln_resource_provider mln_resource_provider |
Resource provider state.
The struct itself is borrowed for the registering call, which copies every route and string before it returns. Exactly one of callback and queue is set. Routes apply in both modes: with routes, a request that matches none passes through to native loading without reaching the provider. Without routes, every network request reaches the provider.
◆ mln_resource_provider_callback
| typedef uint32_t(*) mln_resource_provider_callback(void *user_data, const mln_resource_request_info *request, mln_resource_request handle) |
Intercepts a network resource request.
The callback runs synchronously on a MapLibre thread.
Request handling follows these rules:
- request and its pointed-to fields are borrowed for the callback duration.
- MLN_RESOURCE_PROVIDER_DECISION_PASS_THROUGH uses the built-in network loader.
- After returning PASS_THROUGH, the provider must not retain, complete, or release the handle.
- A request that the callback completes or passes through before returning is answered whatever the callback returns. The return value then decides only whether the provider still holds the handle.
- MLN_RESOURCE_PROVIDER_DECISION_HANDLE lets the provider complete the request through the handle inline or later.
- A callback that returns HANDLE may release the handle during the callback. A request released without a response fails once the callback returns.
- 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 and return quickly. It may call the C API, but must not wait for runtime work that only its own thread can advance.
- The C API invokes release_user_data after the final callback returns.
A provider in queue mode answers MLN_RESOURCE_PROVIDER_DECISION_HANDLE without a callback and queues a copy of the request with its handle as an mln_resource_request_delivery, for the host to complete later.
◆ mln_resource_range
| typedef struct mln_resource_range mln_resource_range |
Inclusive byte range of a resource request.
◆ mln_resource_request_cancel_callback
| typedef void(*) mln_resource_request_cancel_callback(void *user_data, mln_resource_request handle) |
Reports that MapLibre cancelled a C API resource provider request.
The callback runs at most once per request, on the thread that discards the request, and only for a request the provider has not completed. That thread is the runtime's native scheduler thread when a committed map or runtime command discards the request, such as a style change or map destruction, and a MapLibre worker thread otherwise; it is never a host thread. The callback must be thread-safe and return quickly. It may call the C API, including mln_resource_request_release(), but must not wait for runtime work that only its own thread can advance.
handle is the cancelled request, borrowed for the callback; the provider's own reference to it is unchanged.
A handler in queue mode queues a copy as an mln_resource_request_cancel_delivery instead.
◆ mln_resource_request_cancel_handler
| typedef struct mln_resource_request_cancel_handler mln_resource_request_cancel_handler |
Cancel callback or queue state for one handled resource request.
The struct itself is borrowed for the registering call. Exactly one of callback and queue is set.
◆ mln_resource_request_field
| typedef enum mln_resource_request_field mln_resource_request_field |
Field mask values for mln_resource_request_info.
◆ mln_resource_response
| typedef struct mln_resource_response mln_resource_response |
A resource provider's answer to one request.
A fields value with bits outside mln_resource_response_field is malformed, and mln_resource_request_complete() converts it to a provider error response.
◆ mln_resource_response_field
| typedef enum mln_resource_response_field mln_resource_response_field |
Field mask values for mln_resource_response.
◆ mln_resource_response_status
| typedef enum mln_resource_response_status mln_resource_response_status |
How a resource provider answered a request.
- OK carries the resource's bytes.
- ERROR fails the request with mln_resource_response.error_reason. A tile whose reason is NOT_FOUND renders as an empty tile; any other failed tile, and any failed style, reaches the map as a loading error.
- NO_CONTENT reports a resource that exists but is empty. A tile renders as an empty tile.
- NOT_MODIFIED answers a revalidation, a request that carries prior_etag or prior_modified, and keeps the cached copy. When the request also carries prior_data, the map has not received that copy yet, and this answer delivers those bytes.
◆ mln_resource_route
| typedef struct mln_resource_route mln_resource_route |
One request pattern that a resource provider claims.
Routes compare the normalized resolved URL that native loading fetches.
◆ mln_resource_transform
| typedef struct mln_resource_transform mln_resource_transform |
Resource transform state.
The struct itself is borrowed for the registering call. Exactly one of callback and queue is set.
◆ mln_resource_transform_callback
| typedef void(*) mln_resource_transform_callback(void *user_data, uint32_t kind, const char *url, mln_resource_transform_request request) |
Asks the host for the URL of one network resource request.
MapLibre waits for the answer before it schedules the request. The host answers through request, inline or later from any thread: mln_resource_transform_request_complete() replaces the URL, and releasing request without completing it keeps the URL. The callback owns request and releases it exactly once, after answering or to keep the URL.
The callback runs on a MapLibre network thread. It must be thread-safe and return promptly, and must not wait for runtime work. url is borrowed for the callback. The C API invokes release_user_data after the final callback returns.
A transform in queue mode queues a copy as an mln_resource_transform_delivery instead.
◆ mln_runtime_event
| typedef struct mln_runtime_event mln_runtime_event |
One delivered runtime event.
Message bytes are borrowed for the callback or delivery batch lifetime.
Step through an array of these by mln_event_batch_view.event_size rather than by the size of this struct: a later version may add a member to mln_runtime_event_payload and widen the stride. Every field below, payload included, keeps its offset across versions.
◆ mln_runtime_event_callback
| typedef void(*) mln_runtime_event_callback(void *user_data, const mln_event_batch_view *events) |
Receives selected events after their snapshots have been published.
Map events run on the runtime's native scheduler thread. Offline events may run on a MapLibre worker thread. The callback must be thread-safe and return promptly. It may call any-thread C APIs, but must not wait for runtime or graphics-driver work that can only progress on its current thread.
◆ mln_runtime_event_handler
| typedef struct mln_runtime_event_handler mln_runtime_event_handler |
Runtime and map event delivery. Set either callback or queue.
Callback mode borrows the events for the call and releases user_data after replacement, clear, or runtime teardown. Queue mode copies events into MLN_DELIVERY_TYPE_RUNTIME_EVENTS deliveries carrying user_data, followed by MLN_DELIVERY_TYPE_RETIRED when the registration retires. Queue mode requires release_user_data to be null.
◆ mln_runtime_event_mask
| typedef enum mln_runtime_event_mask mln_runtime_event_mask |
Bit values for the map and runtime event subscription masks.
Each bit is 1ULL shifted left by the mln_runtime_event_type value it selects, so a host can compute a bit from a type value it decoded from an event.
mln_map_set_event_mask() reads the bits in MLN_RUNTIME_EVENT_MASK_ALL_MAP_EVENTS and ignores the rest. mln_runtime_set_event_mask() reads the bits in MLN_RUNTIME_EVENT_MASK_ALL_RUNTIME_EVENTS and ignores the rest. Both entry points accept MLN_RUNTIME_EVENT_MASK_ALL and reject bits outside it. A host that reads a mask, sets one bit, and writes it back keeps every other bit.
◆ mln_runtime_event_offline_region_response_error
| typedef struct mln_runtime_event_offline_region_response_error mln_runtime_event_offline_region_response_error |
Payload for MLN_RUNTIME_EVENT_OFFLINE_REGION_RESPONSE_ERROR.
A download skips a resource that fails with MLN_RESOURCE_ERROR_REASON_NOT_FOUND and continues with the rest of the region. A resource that fails for another reason stays outstanding.
◆ mln_runtime_event_offline_region_status
| typedef struct mln_runtime_event_offline_region_status mln_runtime_event_offline_region_status |
Payload for MLN_RUNTIME_EVENT_OFFLINE_REGION_STATUS_CHANGED.
◆ mln_runtime_event_offline_region_tile_count_limit
| typedef struct mln_runtime_event_offline_region_tile_count_limit mln_runtime_event_offline_region_tile_count_limit |
Payload for MLN_RUNTIME_EVENT_OFFLINE_REGION_TILE_COUNT_LIMIT_EXCEEDED.
◆ mln_runtime_event_payload
| typedef union mln_runtime_event_payload mln_runtime_event_payload |
Typed event payload carried inline by every event.
mln_runtime_event.payload_type selects the member. An event whose payload type is MLN_RUNTIME_EVENT_PAYLOAD_NONE carries zeroed payload bytes.
A host that decodes a payload type this version does not define treats the payload as opaque bytes and forwards them unchanged. Those bytes run from the payload's offset within mln_runtime_event to mln_event_batch_view.event_size.
◆ mln_runtime_event_payload_type
Payload kinds used by mln_runtime_event.payload_type.
Values 3, 8, and 9 are retired and stay unused.
◆ mln_runtime_event_render_frame
| typedef struct mln_runtime_event_render_frame mln_runtime_event_render_frame |
Payload for MLN_RUNTIME_EVENT_MAP_RENDER_FRAME_FINISHED.
◆ mln_runtime_event_render_map
| typedef struct mln_runtime_event_render_map mln_runtime_event_render_map |
Payload for MLN_RUNTIME_EVENT_MAP_RENDER_MAP_FINISHED.
◆ mln_runtime_event_source_type
Source kinds used by mln_runtime_event.source_type.
Value 2 is retired and stays unused.
◆ mln_runtime_event_tile_action
| typedef struct mln_runtime_event_tile_action mln_runtime_event_tile_action |
Payload for MLN_RUNTIME_EVENT_MAP_TILE_ACTION.
The event message carries the source ID.
◆ mln_runtime_event_type
| typedef enum mln_runtime_event_type mln_runtime_event_type |
Runtime event types carried by mln_runtime_event.type.
The event type selects the meaning of mln_runtime_event.code and the mln_runtime_event_payload member behind mln_runtime_event.payload_type. Event type names below omit their MLN_RUNTIME_EVENT_ prefix and payload type names omit their MLN_RUNTIME_EVENT_PAYLOAD_ prefix.
Each value is also a bit index in the subscription masks: the bit for an event type is 1ULL shifted left by the type value. See mln_runtime_event_mask.
- MAP_CAMERA_WILL_CHANGE: code is an mln_camera_change_mode; payload NONE.
- MAP_CAMERA_IS_CHANGING: code is 0; payload NONE.
- MAP_CAMERA_DID_CHANGE: code is an mln_camera_change_mode; payload NONE. Each MapLibre transition reports its own as it ends, so a camera delta that pans and also zooms, rotates, or pitches ends with two, and other transitions may still be animating; see mln_map_snapshot.transition_in_progress.
- MAP_STYLE_LOADED: code is 0; payload NONE.
- MAP_LOADING_STARTED: code is 0; payload NONE.
- MAP_LOADING_FINISHED: code is 0; payload NONE.
- MAP_LOADING_FAILED: code identifies the kind of failure, or is 0, and has no named values; message carries the failure text; payload NONE.
- MAP_IDLE: code is 0; payload NONE.
- MAP_RENDER_ERROR: code is 0; message carries the error text; payload NONE. MapLibre reports a failure that it renders past, and a render session reports the failure that lost its target; see MLN_RENDER_SESSION_STATE_TARGET_LOST.
- MAP_RENDER_FRAME_STARTED: code is 0; payload NONE.
- MAP_RENDER_FRAME_FINISHED: code is 0; payload RENDER_FRAME.
- MAP_RENDER_MAP_STARTED: code is 0; payload NONE.
- MAP_RENDER_MAP_FINISHED: code is 0; payload RENDER_MAP.
- MAP_STYLE_IMAGE_MISSING: code is 0; message carries the image ID; payload NONE.
- MAP_TILE_ACTION: code is 0; message carries the source ID; payload TILE_ACTION.
- MAP_SOURCE_CHANGED: a style source changed its description, such as when its TileJSON arrives with new attribution or tile URLs, or its GeoJSON data is replaced; code is 0; message carries the source ID; payload NONE. A style query submitted after the event observes the change.
- OFFLINE_REGION_STATUS_CHANGED: code is 0; payload OFFLINE_REGION_STATUS.
- OFFLINE_REGION_RESPONSE_ERROR: code is 0; message carries the resource error text; payload OFFLINE_REGION_RESPONSE_ERROR.
- OFFLINE_REGION_TILE_COUNT_LIMIT_EXCEEDED: code is 0; payload OFFLINE_REGION_TILE_COUNT_LIMIT.
Values 9, 11, 12, and 22 are retired and stay unused.
◆ mln_runtime_options
| typedef struct mln_runtime_options mln_runtime_options |
Options used when creating a runtime.
◆ mln_tile_id
| typedef struct mln_tile_id mln_tile_id |
Overscaled tile identity reported in tile observer events.
◆ mln_tile_operation
| typedef enum mln_tile_operation mln_tile_operation |
Tile operations reported by tile observer events.
◆ mln_url_match_flags
| typedef enum mln_url_match_flags mln_url_match_flags |
How a rule or route compares its url against a request URL.
With no flags, a rule compares the complete URL byte for byte. MLN_URL_MATCH_GLOB reads the url as a glob pattern instead:
- * matches a run of any length that contains no /, including an empty run.
- ** matches a run of any length, including one that contains /.
- ? matches one character other than /.
- \\endiskip matches the next character literally, and a trailing \\endiskip matches itself.
Every other byte compares literally. A pattern matches the complete URL, so a pattern that describes a suffix opens with a wildcard. Comparison is case-sensitive either way, and applies no URL parsing or normalization.
A glob accepts at most 4096 tokens. Each literal byte, escaped byte, ?, or consecutive run of * bytes counts as one token. Registering a longer glob returns MLN_STATUS_INVALID_ARGUMENT. Exact URL matches have no token limit.
Confining * to one path segment is what makes a host pattern hold: https://*.example.com/** matches every subdomain of example.com and never https://attacker.example/x.example.com/tile. Use ** wherever a pattern spans path segments, as in https://tiles.example.com/** for one host.
Enumeration Type Documentation
◆ mln_camera_change_mode
| enum mln_camera_change_mode : uint32_t |
◆ mln_render_mode
| enum mln_render_mode : uint32_t |
Render modes reported by render observer events.
◆ mln_resource_kind_mask
| enum mln_resource_kind_mask : uint32_t |
The resource kinds that a route or rule matches, one bit per mln_resource_kind value. Registration requires at least one known bit. MLN_RESOURCE_KIND_MASK_ALL selects every resource kind.
◆ mln_resource_request_field
| enum mln_resource_request_field : uint32_t |
Field mask values for mln_resource_request_info.
◆ mln_resource_response_field
| enum mln_resource_response_field : uint32_t |
Field mask values for mln_resource_response.
◆ mln_resource_response_status
| enum mln_resource_response_status : uint32_t |
How a resource provider answered a request.
- OK carries the resource's bytes.
- ERROR fails the request with mln_resource_response.error_reason. A tile whose reason is NOT_FOUND renders as an empty tile; any other failed tile, and any failed style, reaches the map as a loading error.
- NO_CONTENT reports a resource that exists but is empty. A tile renders as an empty tile.
- NOT_MODIFIED answers a revalidation, a request that carries prior_etag or prior_modified, and keeps the cached copy. When the request also carries prior_data, the map has not received that copy yet, and this answer delivers those bytes.
◆ mln_runtime_event_mask
| enum mln_runtime_event_mask : uint64_t |
Bit values for the map and runtime event subscription masks.
Each bit is 1ULL shifted left by the mln_runtime_event_type value it selects, so a host can compute a bit from a type value it decoded from an event.
mln_map_set_event_mask() reads the bits in MLN_RUNTIME_EVENT_MASK_ALL_MAP_EVENTS and ignores the rest. mln_runtime_set_event_mask() reads the bits in MLN_RUNTIME_EVENT_MASK_ALL_RUNTIME_EVENTS and ignores the rest. Both entry points accept MLN_RUNTIME_EVENT_MASK_ALL and reject bits outside it. A host that reads a mask, sets one bit, and writes it back keeps every other bit.
◆ mln_runtime_event_payload_type
| enum mln_runtime_event_payload_type : uint32_t |
Payload kinds used by mln_runtime_event.payload_type.
Values 3, 8, and 9 are retired and stay unused.
◆ mln_runtime_event_source_type
| enum mln_runtime_event_source_type : uint32_t |
Source kinds used by mln_runtime_event.source_type.
Value 2 is retired and stays unused.
◆ mln_runtime_event_type
| enum mln_runtime_event_type : uint32_t |
Runtime event types carried by mln_runtime_event.type.
The event type selects the meaning of mln_runtime_event.code and the mln_runtime_event_payload member behind mln_runtime_event.payload_type. Event type names below omit their MLN_RUNTIME_EVENT_ prefix and payload type names omit their MLN_RUNTIME_EVENT_PAYLOAD_ prefix.
Each value is also a bit index in the subscription masks: the bit for an event type is 1ULL shifted left by the type value. See mln_runtime_event_mask.
- MAP_CAMERA_WILL_CHANGE: code is an mln_camera_change_mode; payload NONE.
- MAP_CAMERA_IS_CHANGING: code is 0; payload NONE.
- MAP_CAMERA_DID_CHANGE: code is an mln_camera_change_mode; payload NONE. Each MapLibre transition reports its own as it ends, so a camera delta that pans and also zooms, rotates, or pitches ends with two, and other transitions may still be animating; see mln_map_snapshot.transition_in_progress.
- MAP_STYLE_LOADED: code is 0; payload NONE.
- MAP_LOADING_STARTED: code is 0; payload NONE.
- MAP_LOADING_FINISHED: code is 0; payload NONE.
- MAP_LOADING_FAILED: code identifies the kind of failure, or is 0, and has no named values; message carries the failure text; payload NONE.
- MAP_IDLE: code is 0; payload NONE.
- MAP_RENDER_ERROR: code is 0; message carries the error text; payload NONE. MapLibre reports a failure that it renders past, and a render session reports the failure that lost its target; see MLN_RENDER_SESSION_STATE_TARGET_LOST.
- MAP_RENDER_FRAME_STARTED: code is 0; payload NONE.
- MAP_RENDER_FRAME_FINISHED: code is 0; payload RENDER_FRAME.
- MAP_RENDER_MAP_STARTED: code is 0; payload NONE.
- MAP_RENDER_MAP_FINISHED: code is 0; payload RENDER_MAP.
- MAP_STYLE_IMAGE_MISSING: code is 0; message carries the image ID; payload NONE.
- MAP_TILE_ACTION: code is 0; message carries the source ID; payload TILE_ACTION.
- MAP_SOURCE_CHANGED: a style source changed its description, such as when its TileJSON arrives with new attribution or tile URLs, or its GeoJSON data is replaced; code is 0; message carries the source ID; payload NONE. A style query submitted after the event observes the change.
- OFFLINE_REGION_STATUS_CHANGED: code is 0; payload OFFLINE_REGION_STATUS.
- OFFLINE_REGION_RESPONSE_ERROR: code is 0; message carries the resource error text; payload OFFLINE_REGION_RESPONSE_ERROR.
- OFFLINE_REGION_TILE_COUNT_LIMIT_EXCEEDED: code is 0; payload OFFLINE_REGION_TILE_COUNT_LIMIT.
Values 9, 11, 12, and 22 are retired and stay unused.
◆ mln_tile_operation
| enum mln_tile_operation : uint32_t |
Tile operations reported by tile observer events.
◆ mln_url_match_flags
| enum mln_url_match_flags : uint32_t |
How a rule or route compares its url against a request URL.
With no flags, a rule compares the complete URL byte for byte. MLN_URL_MATCH_GLOB reads the url as a glob pattern instead:
- * matches a run of any length that contains no /, including an empty run.
- ** matches a run of any length, including one that contains /.
- ? matches one character other than /.
- \\endiskip matches the next character literally, and a trailing \\endiskip matches itself.
Every other byte compares literally. A pattern matches the complete URL, so a pattern that describes a suffix opens with a wildcard. Comparison is case-sensitive either way, and applies no URL parsing or normalization.
A glob accepts at most 4096 tokens. Each literal byte, escaped byte, ?, or consecutive run of * bytes counts as one token. Registering a longer glob returns MLN_STATUS_INVALID_ARGUMENT. Exact URL matches have no token limit.
Confining * to one path segment is what makes a host pattern hold: https://*.example.com/** matches every subdomain of example.com and never https://attacker.example/x.example.com/tile. Use ** wherever a pattern spans path segments, as in https://tiles.example.com/** for one host.
| Enumerator | |
|---|---|
| MLN_URL_MATCH_GLOB | Reads url as a glob pattern. |
Function Documentation
◆ mln_http_header_rule_default()
| mln_http_header_rule mln_http_header_rule_default | ( | void | ) |
Returns an exact-match header rule for every resource kind, with no headers.
◆ mln_http_header_transform_response_set_header()
| mln_status mln_http_header_transform_response_set_header | ( | mln_http_header_transform_response * | response, |
| mln_buffer_view | name, | ||
| mln_buffer_view | value, | ||
| mln_diagnostic * | out_diagnostic ) |
Sets one outgoing HTTP request header for the current transform invocation.
The function copies name and value before returning. A later call using the same case-insensitive name replaces the earlier value.
A diagnostic for a rejected header names the header but never includes its value.
Returns:
- MLN_STATUS_OK when the header was recorded.
- MLN_STATUS_INVALID_ARGUMENT when response is null, response->size is too small, a view has null data with a nonzero size, name is not a valid HTTP field name, value is not valid UTF-8, value contains a disallowed control byte, or name identifies a header managed by MapLibre or the platform transport.
- MLN_STATUS_INVALID_STATE when called outside an active HTTP header transform callback.
- MLN_STATUS_NATIVE_ERROR when native allocation fails.
◆ mln_network_get_status()
| mln_status mln_network_get_status | ( | uint32_t * | out_status, |
| mln_diagnostic * | out_diagnostic ) |
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 native code fails.
◆ mln_network_set_status()
| mln_status mln_network_set_status | ( | uint32_t | status, |
| mln_diagnostic * | out_diagnostic ) |
Sets MapLibre Native's process-global network status.
MLN_NETWORK_STATUS_ONLINE allows network requests. MLN_NETWORK_STATUS_OFFLINE stops new network requests until the status returns to online. 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 native code fails.
◆ mln_resource_request_complete()
| mln_status mln_resource_request_complete | ( | mln_resource_request | handle, |
| const mln_resource_response * | response, | ||
| mln_diagnostic * | out_diagnostic ) |
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. Invalid string views are rejected before the completion is consumed.
Returns:
- MLN_STATUS_OK when the response was accepted for asynchronous delivery.
- MLN_STATUS_INVALID_ARGUMENT when handle is an invalid handle, response is null, or a response string has null data with a nonzero size or embedded NUL.
- MLN_STATUS_INVALID_STATE when handle has been released, or the request was cancelled, already completed, passed through, or can no longer accept a response.
- MLN_STATUS_NATIVE_ERROR when native code fails.
◆ mln_resource_request_is_cancelled()
| mln_status mln_resource_request_is_cancelled | ( | mln_resource_request | handle, |
| bool * | out_cancelled, | ||
| mln_diagnostic * | out_diagnostic ) |
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. A request the provider already completed is never reported as cancelled, even after MapLibre discards it.
Returns:
- MLN_STATUS_OK on success.
- MLN_STATUS_INVALID_ARGUMENT when handle is an invalid handle, or out_cancelled is null.
- MLN_STATUS_INVALID_STATE when handle has been released.
◆ mln_resource_request_pass_through()
| mln_status mln_resource_request_pass_through | ( | mln_resource_request | handle, |
| mln_diagnostic * | out_diagnostic ) |
Hands an outstanding provider request to the built-in network loader.
Call from any thread, inline in a callback that returns HANDLE or after that callback returns, or after taking a queued request. Native loading starts on the requesting MapLibre thread and applies the current native transforms. The request bypasses the provider when it resumes.
Passing through is one-shot and shares the terminal decision with completion. Completion, cancellation, release, and pass-through are serialized: only an outstanding request can pass through. Cancellation that wins first returns MLN_STATUS_INVALID_STATE; cancellation after acceptance cancels native loading as usual. The provider's cancel callback no longer runs after acceptance. The host still releases its handle, which retires any cancel registration; releasing it after pass-through does not cancel native loading.
Returns:
- MLN_STATUS_OK when native loading was scheduled.
- MLN_STATUS_INVALID_ARGUMENT when handle is invalid.
- MLN_STATUS_INVALID_STATE when the request is cancelled, released, completed, or already passed through.
- MLN_STATUS_NATIVE_ERROR when scheduling fails; the request stays outstanding.
◆ mln_resource_request_release()
| void mln_resource_request_release | ( | mln_resource_request | handle | ) |
Releases the provider's reference to a resource request handle.
Release the handle exactly once after completing the request or deciding not to complete it. A provider callback that returns MLN_RESOURCE_PROVIDER_DECISION_HANDLE may release the handle inline. Releasing a handled request that is neither completed nor cancelled fails it with an MLN_RESOURCE_ERROR_REASON_OTHER error, which reaches the map asynchronously. A request handle is not a child of its runtime, whether the provider still holds it or its failure is still queued, so it never makes mln_runtime_release() or mln_map_release() return MLN_STATUS_INVALID_STATE. Passing MLN_HANDLE_NULL is a no-op, as is passing a handle this call already released. A released handle reports MLN_STATUS_INVALID_STATE from every other request entry point, including from a copy another thread holds.
◆ mln_resource_request_set_cancel_callback()
| mln_status mln_resource_request_set_cancel_callback | ( | mln_resource_request | handle, |
| const mln_resource_request_cancel_handler * | handler, | ||
| bool * | out_cancelled, | ||
| mln_diagnostic * | out_diagnostic ) |
Registers a callback that runs when MapLibre cancels a C API resource provider request.
This function may be called from any thread while the provider still owns the handle. A request accepts one registration: a later call fails and leaves the first registration in place.
MLN_STATUS_OK with out_cancelled false transfers the handler's callback, user_data, and release_user_data to the C API. The callback runs at most once. The handler struct itself is borrowed for the call.
A request that is already cancelled and not completed stores nothing and reports true through out_cancelled. The caller keeps user_data and handles the cancellation itself, and neither callback runs. Any other request reports false. This function never invokes either callback.
mln_resource_request_release() waits for a cancel callback running on another thread to return, so the callback and user_data are unused once release returns. Called from inside the callback, release returns without waiting.
Returns:
- MLN_STATUS_OK on success.
- MLN_STATUS_INVALID_ARGUMENT when handle is an invalid handle, when handler or out_cancelled is null, when handler->size is too small, when handler sets neither or both of callback and queue, or when handler->queue is an invalid handle.
- MLN_STATUS_INVALID_STATE when handle or handler->queue has been released, or the request already has a cancel callback.
◆ mln_resource_route_default()
| mln_resource_route mln_resource_route_default | ( | void | ) |
Returns an exact-match route for every resource kind.
◆ mln_resource_transform_request_complete()
| mln_status mln_resource_transform_request_complete | ( | mln_resource_transform_request | request, |
| mln_buffer_view | url, | ||
| mln_diagnostic * | out_diagnostic ) |
Answers a resource transform request with a replacement URL.
Call from any thread, inline in the transform callback or later. The C API copies url before returning. A request takes one answer, and the caller still releases it afterward. A request that MapLibre cancelled while it waited accepts the answer and discards it.
Returns:
- MLN_STATUS_OK when the answer was accepted.
- MLN_STATUS_INVALID_ARGUMENT when request is an invalid handle, url is empty, or url has null data with a nonzero size or contains embedded NUL.
- MLN_STATUS_INVALID_STATE when request has been released or already answered.
- MLN_STATUS_NATIVE_ERROR when native code fails.
◆ mln_resource_transform_request_release()
| void mln_resource_transform_request_release | ( | mln_resource_transform_request | request | ) |
Releases a resource transform request.
Release each request exactly once. A request released without an answer keeps its URL. Passing MLN_HANDLE_NULL is a no-op, as is passing a handle this call already released.
◆ mln_runtime_clear_event_handler()
| mln_status mln_runtime_clear_event_handler | ( | mln_runtime | runtime, |
| const mln_completion * | completion, | ||
| mln_diagnostic * | out_diagnostic ) |
Stops event delivery and retires the previous handler.
Returns:
- MLN_STATUS_OK when the command is accepted.
- MLN_STATUS_INVALID_ARGUMENT when runtime or completion is invalid.
- MLN_STATUS_INVALID_STATE when runtime is released.
- MLN_STATUS_NATIVE_ERROR when command acceptance fails.
◆ mln_runtime_clear_http_header_transform()
| mln_status mln_runtime_clear_http_header_transform | ( | mln_runtime | runtime, |
| const mln_completion * | completion, | ||
| mln_diagnostic * | out_diagnostic ) |
Clears the runtime-scoped outgoing HTTP header transform.
The function accepts the change from any thread and orders it with every other command for this runtime. The completion reports the terminal command disposition. The C API invokes the previous transform's release_user_data after every in-flight callback returns.
Returns:
- MLN_STATUS_OK when the command is accepted.
- MLN_STATUS_INVALID_ARGUMENT when runtime is an invalid handle, or completion is invalid.
- MLN_STATUS_INVALID_STATE when runtime has been released or is closing.
- MLN_STATUS_NATIVE_ERROR when command acceptance fails.
◆ mln_runtime_clear_resource_provider()
| mln_status mln_runtime_clear_resource_provider | ( | mln_runtime | runtime, |
| const mln_completion * | completion, | ||
| mln_diagnostic * | out_diagnostic ) |
Clears the runtime-scoped network resource provider.
The function accepts the change from any thread and orders it with every other command for this runtime. The completion reports the terminal command disposition. The C API invokes the previous provider's release_user_data after every in-flight callback returns. Later requests use the built-in network loader. Requests that the previous provider already handled retain their handles.
Returns:
- MLN_STATUS_OK when the command is accepted.
- MLN_STATUS_INVALID_ARGUMENT when runtime is an invalid handle, or completion is invalid.
- MLN_STATUS_INVALID_STATE when runtime has been released or is closing.
- MLN_STATUS_NATIVE_ERROR when command acceptance fails.
◆ mln_runtime_clear_resource_transform()
| mln_status mln_runtime_clear_resource_transform | ( | mln_runtime | runtime, |
| const mln_completion * | completion, | ||
| mln_diagnostic * | out_diagnostic ) |
Clears the runtime-scoped URL transform for network resources.
The function accepts the change from any thread and orders it with every other command for this runtime. The completion reports the terminal command disposition. The C API invokes the previous transform's release_user_data after every in-flight callback returns. Later network resource URLs pass through unchanged; requests the previous transform already received wait for their answers.
Returns:
- MLN_STATUS_OK when the command is accepted.
- MLN_STATUS_INVALID_ARGUMENT when runtime is an invalid handle, or completion is invalid.
- MLN_STATUS_INVALID_STATE when runtime has been released or is closing.
- MLN_STATUS_NATIVE_ERROR when command acceptance fails.
◆ mln_runtime_create()
| mln_status mln_runtime_create | ( | const mln_runtime_options * | options, |
| mln_runtime * | out_runtime, | ||
| mln_diagnostic * | out_diagnostic ) |
Creates a runtime.
The call blocks until initialization completes. In the browser, call from a Web Worker; the main thread cannot block. The output must point to the null handle and receives ownership of the runtime on success.
Returns:
- MLN_STATUS_OK when out_runtime receives an owned runtime.
- MLN_STATUS_INVALID_ARGUMENT when options is null, options->size is too small, a path view has null data with a nonzero size or embedded NUL, or out_runtime is null or does not point to the null handle.
- MLN_STATUS_WRONG_THREAD when called on the browser main thread.
- MLN_STATUS_NATIVE_ERROR when runtime initialization fails.
◆ mln_runtime_dispose()
| mln_status mln_runtime_dispose | ( | mln_runtime | runtime, |
| mln_diagnostic * | out_diagnostic ) |
Consumes a runtime handle without observing its asynchronous retirement.
A successful call consumes the handle before returning. A failed call retains caller ownership. Retirement waits for live and pending children and accepted work. Existing children retain their own cleanup obligations; dispose or release them to let the runtime finish retiring. Teardown may allocate; allocation failure after acceptance terminates the process.
Returns:
- MLN_STATUS_OK when the handle was consumed.
- MLN_STATUS_INVALID_ARGUMENT when runtime is an invalid handle.
- MLN_STATUS_INVALID_STATE when runtime has been released or is already closing.
◆ mln_runtime_get_event_mask()
| mln_status mln_runtime_get_event_mask | ( | mln_runtime | runtime, |
| uint64_t * | out_mask, | ||
| mln_diagnostic * | out_diagnostic ) |
Reports which runtime-scoped event types this runtime queues.
The value is the mask last set, including bits outside MLN_RUNTIME_EVENT_MASK_ALL_RUNTIME_EVENTS that this runtime ignores. A runtime that has not been narrowed reports MLN_RUNTIME_EVENT_MASK_ALL as this library defines it.
Returns:
- MLN_STATUS_OK on success.
- MLN_STATUS_INVALID_ARGUMENT when runtime is an invalid handle, or out_mask is null.
- MLN_STATUS_INVALID_STATE when runtime has been released or is closing.
- MLN_STATUS_NATIVE_ERROR when native code fails.
◆ mln_runtime_options_default()
| mln_runtime_options mln_runtime_options_default | ( | void | ) |
Returns runtime options initialized for this C API version.
◆ mln_runtime_release()
| mln_status mln_runtime_release | ( | mln_runtime | runtime, |
| const mln_completion * | completion, | ||
| mln_diagnostic * | out_diagnostic ) |
Starts release of a runtime after checking its children.
The call rejects a runtime that has live or pending children and leaves it open. A runtime's children are its maps, including a map whose creation was accepted but has not completed. Resource request handles are not children: one that a provider still holds, or has released with its failure still queued, leaves this call free to succeed. A successful call consumes the public handle before returning. Previously accepted work and native teardown continue in submission order; callback user data remains native-owned until its release callback runs. This function may be called from any thread.
The completion runs after every earlier accepted submission, including released maps' teardown and each submission's completion and release callback, has finished. The runtime's worker has exited, including its thread-local cleanup, and runtime-owned callback and resource state has retired. The completion must not block. Shared native services remain outside this guarantee; release completion does not permit unloading the library. A host that outlives its runtimes may pass a discarding completion.
Items that the runtime's registrations already pushed to a delivery queue stay in that queue, so the completion can run before the host drains them.
Teardown may allocate. Allocation failure after acceptance terminates the process. A runtime whose teardown is slow delays other runtimes' release completions.
A process may exit at any point, including while runtimes and maps are live and their work is in flight. Render sessions may stay live too, once their graphics calls have ended as described below. Native work may continue until the operating system ends the process. Once exit begins, native code dispatches no further callback that the host registered through this API, release callbacks included. A callback that native code dispatched before exit began may still start or be running after it. A completion or release callback that is still pending when exit begins never runs, so code that runs after exit begins must not wait for one. Plugin code is native code, not a host callback in this sense; see plugin.h.
When exit begins depends on the platform. On Windows, it begins when the operating system ends the process's other threads, after every exit handler and static destructor that the host registered has run. Elsewhere, it begins when the C runtime runs the exit handler that the library registers when it first creates a runtime or installs the log callback; exit handlers and static destructors that the host registered before that run after it. A process that ends without running exit handlers, such as through _exit(), ends native threads with it.
A host that tears down state its callbacks use before exit begins must stop native callbacks into that state first. That covers a language runtime that shuts down before the C runtime's exit handlers run, such as an interpreter that finalizes first; on Windows, every exit handler and static destructor that the host registered; and elsewhere, those that the host registered after the library's exit handler. Releasing each runtime and waiting for its release completion stops its callbacks.
Before the process calls exit() or returns from main, the host must end the graphics calls of every render session it attached. To end them, abandon the session, or detach it and wait for the detach completion. A host that drives a session on its own graphics thread stops driver service first. Abandon returns once the session's in-flight driver call has ended, so an exit path can end a session that is mid-frame. A disposed session's graphics calls have ended once its wake release callbacks have run. A browser WebGPU readback whose copy is still mapping is the one exception to both paths: the library releases its own staging buffer when the graphics thread's event loop delivers the map; see mln_render_session_abandon().
Returns:
- MLN_STATUS_OK when the handle was consumed.
- MLN_STATUS_INVALID_ARGUMENT when runtime is an invalid handle, or completion is invalid.
- MLN_STATUS_INVALID_STATE when runtime has been released, or the runtime has a live or pending child or is already closing.
- MLN_STATUS_NATIVE_ERROR when the completion could not be allocated.
◆ mln_runtime_run_ambient_cache_operation()
| mln_status mln_runtime_run_ambient_cache_operation | ( | mln_runtime | runtime, |
| uint32_t | operation, | ||
| const mln_completion * | completion, | ||
| mln_diagnostic * | out_diagnostic ) |
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. The completion reports the terminal status and carries no value.
Returns:
- MLN_STATUS_OK when the operation is accepted.
- MLN_STATUS_INVALID_ARGUMENT when runtime is an invalid handle, operation is not an mln_ambient_cache_operation value, or completion is invalid.
- MLN_STATUS_INVALID_STATE when runtime has been released or is closing.
- MLN_STATUS_NATIVE_ERROR when acceptance fails.
Completes with:
- MLN_STATUS_OK when the maintenance operation finished.
- MLN_STATUS_NATIVE_ERROR when the database reports a failure.
◆ mln_runtime_set_event_handler()
| mln_status mln_runtime_set_event_handler | ( | mln_runtime | runtime, |
| const mln_runtime_event_handler * | handler, | ||
| const mln_completion * | completion, | ||
| mln_diagnostic * | out_diagnostic ) |
Selects how runtime and map events reach the host.
MLN_STATUS_OK transfers the handler's user_data to the runtime. A rejected call leaves it with the caller. Events queued before replacement stay on their original queue. Before a handler is set, events are dropped. Set a handler before creating maps or observing offline regions to receive their first events.
Returns:
- MLN_STATUS_OK when the command is accepted.
- MLN_STATUS_INVALID_ARGUMENT when runtime or handler is invalid, or the completion is invalid.
- MLN_STATUS_INVALID_STATE when runtime or the handler's queue is released.
- MLN_STATUS_NATIVE_ERROR when command acceptance fails.
◆ mln_runtime_set_event_mask()
| mln_status mln_runtime_set_event_mask | ( | mln_runtime | runtime, |
| uint64_t | mask, | ||
| mln_diagnostic * | out_diagnostic ) |
Selects which runtime-scoped event types this runtime queues.
A runtime queues an offline event when this mask selects its type. Region status, response error, and tile count limit events also require the region to be observed with mln_runtime_set_offline_region_observed(), so this mask narrows that subscription rather than replacing it.
A runtime that has not been narrowed selects every runtime-scoped event type this library reports, which covers types a caller's header may not declare. A new mask applies to later events and keeps the events already queued.
This call accepts only bits in MLN_RUNTIME_EVENT_MASK_ALL. It reads the bits in MLN_RUNTIME_EVENT_MASK_ALL_RUNTIME_EVENTS and ignores map-originated bits. mln_runtime_get_event_mask() reports the value last set, so a host reads it, changes one bit, and writes it back.
Changing this mask does not affect one-shot completion or result ownership.
Returns:
- MLN_STATUS_OK on success.
- MLN_STATUS_INVALID_ARGUMENT when runtime is an invalid handle, or mask holds a bit outside MLN_RUNTIME_EVENT_MASK_ALL.
- MLN_STATUS_INVALID_STATE when runtime has been released or is closing.
- MLN_STATUS_NATIVE_ERROR when native code fails.
◆ mln_runtime_set_http_header_transform()
| mln_status mln_runtime_set_http_header_transform | ( | mln_runtime | runtime, |
| const mln_http_header_transform * | transform, | ||
| const mln_completion * | completion, | ||
| mln_diagnostic * | out_diagnostic ) |
Registers or replaces the runtime-scoped outgoing HTTP header transform.
The transform applies only to requests that reach the built-in HTTP client, including online and offline requests and nested network-backed PMTiles range requests. Cache hits, non-HTTP schemes, and provider-handled requests do not invoke it.
The function copies the transform shape and accepts the change from any thread. Execution is ordered with every other command for this runtime. The completion reports the terminal command disposition. With a non-null release_user_data, MLN_STATUS_OK transfers responsibility for releasing user_data to the C API. With a null release_user_data, the caller keeps user_data valid until a committed replacement or clear command, or until native runtime teardown finishes.
A transform without a callback adds headers through its rules, so a host that cannot run code on a MapLibre thread can use it.
Returns:
- MLN_STATUS_OK when the command is accepted.
- MLN_STATUS_INVALID_ARGUMENT when runtime is an invalid handle, transform is null, transform->size is too small, neither a callback nor rules are set, a callback comes with rules, a rules transform carries user_data or release_user_data, a rule is invalid, or completion is invalid. A rule is invalid when rules is null with a nonzero rule_count, its url is null, its kinds are zero or hold unknown bits, its flags hold an unknown bit, its headers are null with a nonzero header_count, or a header breaks a rule of mln_http_header_transform_response_set_header(). The diagnostic names the rule's index and never includes a header value.
- MLN_STATUS_UNSUPPORTED on OpenHarmony and in the browser, whose HTTP clients cannot prevent transformed headers from following a cross-origin redirect. A resource provider serves those requests instead.
- MLN_STATUS_INVALID_STATE when runtime has been released or is closing.
- MLN_STATUS_NATIVE_ERROR when command acceptance fails.
◆ mln_runtime_set_maximum_ambient_cache_size()
| mln_status mln_runtime_set_maximum_ambient_cache_size | ( | mln_runtime | runtime, |
| uint64_t | size, | ||
| const mln_completion * | completion, | ||
| mln_diagnostic * | out_diagnostic ) |
Starts a change to this runtime's maximum ambient cache size.
size is the ambient cache budget in bytes. MapLibre evicts ambient resources to fit the new budget, so lowering it discards cached resources. Offline regions are not ambient and are unaffected.
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. The completion reports the terminal status and carries no value.
Returns:
- MLN_STATUS_OK when the operation is accepted.
- MLN_STATUS_INVALID_ARGUMENT when runtime is an invalid handle, or completion is invalid.
- MLN_STATUS_INVALID_STATE when runtime has been released or is closing.
- MLN_STATUS_NATIVE_ERROR when acceptance fails.
Completes with:
- MLN_STATUS_OK when the budget was applied.
- MLN_STATUS_NATIVE_ERROR when the database reports a failure.
◆ mln_runtime_set_resource_provider()
| mln_status mln_runtime_set_resource_provider | ( | mln_runtime | runtime, |
| const mln_resource_provider * | provider, | ||
| const mln_completion * | completion, | ||
| mln_diagnostic * | out_diagnostic ) |
Registers or replaces a runtime-scoped network resource provider.
The provider handles network requests. Built-in non-network schemes such as file, asset, mbtiles, and pmtiles bypass it.
The provider sees every network request, including one the ambient cache holds a fresh copy of. MapLibre delivers the cached copy first, then asks the provider to revalidate it, with prior_etag, prior_modified, and prior_expires describing that copy, even before the copy expires. The provider answers NOT_MODIFIED to keep it.
The function copies the provider shape and accepts the change from any thread. Execution is ordered with every other command for this runtime. The completion reports the terminal command disposition.
With a non-null release_user_data, MLN_STATUS_OK transfers responsibility for releasing user_data to the C API. With a null release_user_data, the caller keeps user_data valid until a committed replacement or clear command, or until native runtime teardown finishes. Requests that the previous provider already handled retain their request handles.
A URL with an unrecognized scheme, such as jar:file:, reaches this callback and completes as an HTTP error when the provider passes it through.
In queue mode, no host code runs on the requesting thread: each request reaches the provider's queue, and the host completes it or passes it through after draining.
Returns:
- MLN_STATUS_OK when the command is accepted.
- MLN_STATUS_INVALID_ARGUMENT when runtime is an invalid handle, provider is null, provider->size is too small, neither or both of callback and queue are set, release_user_data is set in queue mode, queue is an invalid handle, a route is invalid, or completion is invalid. A route is invalid when routes is null with a nonzero route_count, or the route's url is null or its kinds are zero or hold unknown bits, or its flags hold an unknown bit; the diagnostic names the route's index.
- MLN_STATUS_INVALID_STATE when runtime or queue has been released, or runtime is closing.
- MLN_STATUS_NATIVE_ERROR when command acceptance fails.
◆ mln_runtime_set_resource_transform()
| mln_status mln_runtime_set_resource_transform | ( | mln_runtime | runtime, |
| const mln_resource_transform * | transform, | ||
| const mln_completion * | completion, | ||
| mln_diagnostic * | out_diagnostic ) |
Registers or updates a runtime-scoped URL transform for network resources.
The transform applies to built-in network loading, including nested PMTiles network range requests. It does not apply to file, asset, database, MBTiles, or requests handled by a registered C API provider.
The function copies the transform shape and accepts the change from any thread. Execution is ordered with every other command for this runtime. The completion reports the terminal command disposition. With a non-null release_user_data, MLN_STATUS_OK transfers responsibility for releasing user_data to the C API. With a null release_user_data, the caller keeps user_data valid until a committed replacement or clear command, or until native runtime teardown finishes.
In queue mode, no host code runs on a MapLibre thread: each request reaches the transform's queue, and the host answers its handle after draining.
Returns:
- MLN_STATUS_OK when the command is accepted.
- MLN_STATUS_INVALID_ARGUMENT when runtime is an invalid handle, transform is null, transform->size is too small, neither or both of callback and queue are set, release_user_data is set in queue mode, queue is an invalid handle, or completion is invalid.
- MLN_STATUS_INVALID_STATE when runtime or queue has been released, or runtime is closing.
- MLN_STATUS_NATIVE_ERROR when command acceptance fails.
Generated by
1.18.0