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_camera_transition_finished |
| 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 |
| union | mln_runtime_event_payload |
| struct | mln_runtime_event |
| struct | mln_runtime_event_batch |
Typedefs | |
| typedef uint64_t | mln_offline_operation_id |
| typedef enum mln_offline_operation_kind | mln_offline_operation_kind |
| typedef enum mln_offline_operation_result_kind | mln_offline_operation_result_kind |
| 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 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_camera_transition_finished | mln_runtime_event_camera_transition_finished |
| 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 struct mln_runtime_event_offline_operation_completed | mln_runtime_event_offline_operation_completed |
| typedef union mln_runtime_event_payload | mln_runtime_event_payload |
| typedef struct mln_runtime_event | mln_runtime_event |
| typedef struct mln_runtime_event_batch | mln_runtime_event_batch |
| typedef mln_status(* | mln_resource_transform_callback) (void *user_data, uint32_t kind, const char *url, mln_resource_transform_response *out_response) |
| 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 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_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_UPDATE_AVAILABLE , MLN_RUNTIME_EVENT_MASK_MAP_RENDER_ERROR , MLN_RUNTIME_EVENT_MASK_MAP_STILL_IMAGE_FINISHED , MLN_RUNTIME_EVENT_MASK_MAP_STILL_IMAGE_FAILED , 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_MAP_CAMERA_TRANSITION_FINISHED , 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_OFFLINE_OPERATION_COMPLETED , 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 |
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_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 and remain valid until the transform is replaced, cleared, or the runtime is destroyed. Those calls wait for in-flight callbacks before returning. url and out_response are borrowed for the callback duration. Callback implementations call only mln_http_header_transform_response_set() and return promptly. A non-OK result discards every header collected during the invocation and lets the request proceed unchanged.
◆ mln_offline_operation_id
| typedef uint64_t mln_offline_operation_id |
Offline database operation token. Zero is never a valid operation ID.
◆ mln_offline_operation_kind
| typedef enum mln_offline_operation_kind mln_offline_operation_kind |
Offline database operation kinds reported by completion events.
◆ mln_offline_operation_result_kind
Offline database operation result kinds reported by completion events.
◆ 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.
This struct has no size field, because it is a member of mln_runtime_event_payload. mln_runtime_event_batch.event_size covers the whole event, including its payload.
◆ 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.
- A callback that returns HANDLE may release the handle during the callback. The C API defers that release until 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, 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.
◆ mln_runtime_event
| typedef struct mln_runtime_event mln_runtime_event |
One drained runtime event.
Events have a fixed stride and hold no pointers, so a host can copy a whole batch with one memory copy.
Step through an array of these by mln_runtime_event_batch.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_batch
| typedef struct mln_runtime_event_batch mln_runtime_event_batch |
A drained batch of runtime events.
A caller zero-initializes this struct, sets size, and passes it to mln_runtime_drain_events(). mln_runtime_event_batch_default() returns such a struct.
◆ mln_runtime_event_camera_transition_finished
| typedef struct mln_runtime_event_camera_transition_finished mln_runtime_event_camera_transition_finished |
Payload for MLN_RUNTIME_EVENT_MAP_CAMERA_TRANSITION_FINISHED.
See mln_animation_options.transition_id for how a caller stamps an identity onto a camera transition and what terminal outcomes this event covers.
◆ 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 therefore accept MLN_RUNTIME_EVENT_MASK_ALL, and a host that reads a mask, sets one bit, and writes it back keeps every other bit.
◆ mln_runtime_event_offline_operation_completed
| typedef struct mln_runtime_event_offline_operation_completed mln_runtime_event_offline_operation_completed |
Payload for MLN_RUNTIME_EVENT_OFFLINE_OPERATION_COMPLETED.
◆ 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.
◆ 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_runtime_event_batch.event_size.
◆ mln_runtime_event_payload_type
Payload kinds used by mln_runtime_event.payload_type.
Value 3 is retired and no version reuses it. It was a style-image-missing payload whose only content was the image ID that the event message carries.
◆ 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.
◆ 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.
- 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 is the ordinal of MapLibre Native's internal map load error kind, which this API does not name as an enum, and is 0 when the failure came from a style-loading exception raised inside a C API call. Read message for the failure text in both cases; payload NONE.
- MAP_IDLE: code is 0; payload NONE.
- MAP_RENDER_UPDATE_AVAILABLE: code is 0; payload NONE.
- MAP_RENDER_ERROR: code is 0; message carries the error text; payload NONE.
- MAP_STILL_IMAGE_FINISHED: code is 0; payload NONE.
- MAP_STILL_IMAGE_FAILED: code is 0; message carries the error text; payload NONE.
- 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.
- 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.
- OFFLINE_OPERATION_COMPLETED: code is the operation result as an mln_status value, the same value the payload reports in result_status; message carries the failure text when the operation failed; payload OFFLINE_OPERATION_COMPLETED.
◆ 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.
Enumeration Type Documentation
◆ mln_camera_change_mode
| enum mln_camera_change_mode : uint32_t |
◆ 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_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 therefore accept MLN_RUNTIME_EVENT_MASK_ALL, and 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.
Value 3 is retired and no version reuses it. It was a style-image-missing payload whose only content was the image ID that the event message carries.
◆ 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 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.
- 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 is the ordinal of MapLibre Native's internal map load error kind, which this API does not name as an enum, and is 0 when the failure came from a style-loading exception raised inside a C API call. Read message for the failure text in both cases; payload NONE.
- MAP_IDLE: code is 0; payload NONE.
- MAP_RENDER_UPDATE_AVAILABLE: code is 0; payload NONE.
- MAP_RENDER_ERROR: code is 0; message carries the error text; payload NONE.
- MAP_STILL_IMAGE_FINISHED: code is 0; payload NONE.
- MAP_STILL_IMAGE_FAILED: code is 0; message carries the error text; payload NONE.
- 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.
- 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.
- OFFLINE_OPERATION_COMPLETED: code is the operation result as an mln_status value, the same value the payload reports in result_status; message carries the failure text when the operation failed; payload OFFLINE_OPERATION_COMPLETED.
◆ mln_tile_operation
| enum mln_tile_operation : uint32_t |
Tile operations reported by tile observer events.
Function Documentation
◆ mln_http_header_transform_response_set()
| mln_status mln_http_header_transform_response_set | ( | mln_http_header_transform_response * | response, |
| const char * | name, | ||
| size_t | name_size, | ||
| const char * | value, | ||
| size_t | value_size ) |
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.
Returns MLN_STATUS_INVALID_ARGUMENT when response is null, response->size is too small, a pointer is null with a non-zero 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. A diagnostic for a rejected header names the header but never includes its value. Returns MLN_STATUS_INVALID_STATE when called outside an active HTTP header transform callback. Returns MLN_STATUS_NATIVE_ERROR when native allocation fails.
◆ 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 | ( | 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.
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. Passing MLN_HANDLE_NULL is a no-op, as is passing a handle this call already released. A released handle reports MLN_STATUS_INVALID_ARGUMENT from every other request entry point, including from a copy another thread holds.
◆ mln_resource_request_wait_until_retired()
| mln_status mln_resource_request_wait_until_retired | ( | mln_resource_request_handle | handle | ) |
Blocks until a resource request is completed or released.
Hosts that hand a request to another execution context use this to drain outstanding requests during teardown. Call it from a context that is not responsible for retiring the request.
Returns:
- MLN_STATUS_OK once the request is retired, including when it already was.
- MLN_STATUS_INVALID_ARGUMENT when handle is MLN_HANDLE_NULL.
◆ 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_http_header_transform()
| mln_status mln_runtime_clear_http_header_transform | ( | mln_runtime | runtime | ) |
Clears the runtime-scoped outgoing HTTP header transform.
When this call returns, no in-flight request can still invoke the previous callback and the C API holds no reference to its user_data.
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_clear_resource_provider()
| mln_status mln_runtime_clear_resource_provider | ( | mln_runtime | runtime | ) |
Clears the runtime-scoped network resource provider.
After this call succeeds, requests that reach the C API network file source go to MapLibre's online file source. When it returns, no in-flight request can still invoke the previous provider, and the C API holds no further reference to its callback or user_data. Requests the previous provider already took a handle for keep that handle: complete and release each one as usual.
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_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, a nonzero flags value, or an event_mask bit outside MLN_RUNTIME_EVENT_MASK_ALL.
- 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.
This call waits for in-flight resource transform, HTTP header transform, and resource provider callbacks before returning, the same way the corresponding set and clear functions do. Each callback and its user_data stay valid until that point and are unreferenced once this call returns, so a host frees callback-owned state only after it does.
Do not call this while holding a host lock that one of those callbacks also acquires; the callback cannot finish, and this call cannot return.
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_drain_events()
| mln_status mln_runtime_drain_events | ( | mln_runtime | runtime, |
| size_t | max_events, | ||
| mln_runtime_event_batch * | out_batch ) |
Drains this runtime's queued runtime events into one borrowed batch.
Events arrive in queue order. Map-originated events set source_type to MLN_RUNTIME_EVENT_SOURCE_MAP and source to the source map; runtime-originated events set source_type to MLN_RUNTIME_EVENT_SOURCE_RUNTIME and source to this runtime.
max_events bounds the drain. Zero drains every queued event. A positive value drains at most that many events and reports the number that stayed queued in out_batch->remaining_count. A drain also stops when one more message would take the message arena past 4 GiB, so read out_batch->remaining_count after an unbounded drain too.
Read a payload as the mln_runtime_event_payload member that event.payload_type selects. Read a message as event.message_size bytes at out_batch->messages plus event.message_offset. Every offset and size pair this call writes lies inside the arena.
Copy any value a host keeps, because out_batch->events and out_batch->messages point at runtime-owned storage that stays readable only until the next mln_runtime_drain_events() call for the same runtime or until the runtime is destroyed. Every other C API call leaves the batch readable, including calls on the maps this runtime owns and mln_map_destroy() for a map whose events the batch carries. Every drain invalidates the batch before it, including a drain that finds no events.
Destroying a map discards that map's queued events, so this call reports events only for maps that were live when the events were queued. Read the state a host mirrors from events before destroying the map that produces them.
The map and runtime subscription masks decide which events reach the queue. An event of an unselected type is never built and never queued, so it reaches no batch and raises no wake flag. See mln_map_set_event_mask() and mln_runtime_set_event_mask().
Draining is a queue operation: it runs no owner-thread work and never parks. Call mln_runtime_pump() to advance the runtime, then drain the events that pump produced.
This function clears the calling thread's diagnostic message, so read mln_thread_last_error_message() for a failed call before draining.
Returns:
- MLN_STATUS_OK when the drain completed, including when it found no events.
- MLN_STATUS_INVALID_ARGUMENT when runtime is null or not a live runtime handle, out_batch is null, or out_batch->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_event_batch_default()
| mln_runtime_event_batch mln_runtime_event_batch_default | ( | void | ) |
Returns a zeroed mln_runtime_event_batch with size filled in.
◆ mln_runtime_get_event_mask()
| mln_status mln_runtime_get_event_mask | ( | mln_runtime | runtime, |
| uint64_t * | out_mask ) |
Reports which runtime-originated 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 null or not a live runtime handle, or out_mask 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_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_pump()
| mln_status mln_runtime_pump | ( | mln_runtime | runtime, |
| int64_t | timeout_ms, | ||
| int64_t | budget_ms ) |
Advances this runtime.
The call parks the owner thread when timeout_ms allows it, then drains the owner-thread task queues. Drain the queued runtime events with mln_runtime_drain_events() afterwards.
timeout_ms sets the park bound:
- Zero drains and returns. Hosts pumping from a frame callback pass zero.
- A positive value parks for up to that many milliseconds, then drains.
- A negative value parks until a wake arrives, then drains.
The drain runs every task queued when it begins plus every task those tasks enqueue, and services expired timers and ready file descriptors for the runtime's own network and database work.
budget_ms bounds the drain:
- A negative value drains without a bound. One unbounded drain can span a full style parse, so budget for it as variable work.
- Zero or a positive value stops the drain at the first task boundary after that many milliseconds, measured from the start of the drain. The first queued task always runs, so a bounded pump always makes progress. Tasks left behind set the wake flag, so the next pump returns without parking and continues them.
The budget bounds the task queues alone. Expired timers and ready file descriptors are serviced regardless, and a single task runs to completion once started, so one long task can overrun the budget.
The runtime holds a wake flag. These set it:
- the owner-thread run loop receiving queued work from any thread, which covers style, tile, offline database, and resource responses;
- the runtime queueing a runtime event that a subscription mask selects;
- mln_wake_source_signal() from any thread.
A parking call returns as soon as the flag is set, and clears the flag before it returns. Work that arrives during the drain sets the flag again, so the next call returns right away and may find that work already done.
A call also returns without parking while unread runtime events are queued. A narrowed subscription leaves the queue empty more often, so a parking call parks where it previously returned immediately.
Timers and file descriptors set the flag only when they queue owner-thread work, and the runtime registers none of its own on the owner-thread run loop. Pass a positive timeout_ms so a call returns even when nothing sets the flag.
A non-zero timeout_ms makes this a blocking query. Call it outside any host lock that a thread signalling a wake source acquires, and outside C API callbacks. Acquire a wake source with mln_runtime_wake_source_acquire() to release the owner thread for host-driven work such as submitted tasks or shutdown.
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_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_set_event_mask()
| mln_status mln_runtime_set_event_mask | ( | mln_runtime | runtime, |
| uint64_t | mask ) |
Selects which runtime-originated 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_offline_region_set_observed_start(), so this mask narrows that subscription rather than replacing it.
A runtime that has not been narrowed selects every runtime-originated 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 reads the bits in MLN_RUNTIME_EVENT_MASK_ALL_RUNTIME_EVENTS and ignores the rest, so MLN_RUNTIME_EVENT_MASK_ALL selects every runtime-originated type. mln_runtime_get_event_mask() reports the value last set, so a host reads it, changes one bit, and writes it back.
A host that clears MLN_RUNTIME_EVENT_MASK_OFFLINE_OPERATION_COMPLETED still takes each result with the matching take-result entry point, and still reads a failed operation's error text from that call's thread diagnostic. An offline operation records its result before this mask is consulted.
Returns:
- MLN_STATUS_OK on success.
- MLN_STATUS_INVALID_ARGUMENT when runtime is null or not a live runtime handle, or mask holds a bit outside MLN_RUNTIME_EVENT_MASK_ALL.
- 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_http_header_transform()
| mln_status mln_runtime_set_http_header_transform | ( | mln_runtime | runtime, |
| const mln_http_header_transform * | transform ) |
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. Replacement waits for in-flight callbacks before the old callback and user_data become unreferenced.
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_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_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_maximum_ambient_cache_size_start()
| mln_status mln_runtime_set_maximum_ambient_cache_size_start | ( | mln_runtime | runtime, |
| uint64_t | size, | ||
| mln_offline_operation_id * | out_operation_id ) |
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. 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 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_set_resource_provider()
| mln_status mln_runtime_set_resource_provider | ( | mln_runtime | runtime, |
| const mln_resource_provider * | provider ) |
Registers or replaces a runtime-scoped network resource provider.
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.
This call may replace an existing provider while maps exist. The callback and user_data are stored by reference and must remain valid until this call returns having replaced them, mln_runtime_clear_resource_provider() returns, or the runtime is destroyed. When this call returns, no in-flight request can still invoke the previous provider. Requests the previous provider already took a handle for keep that handle: complete and release each one as usual. Native OnlineFileSource claims every remaining scheme, so a URL with a scheme MapLibre does not recognize, such as jar:file:, reaches this callback and completes as an HTTP error when the provider passes it through.
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_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.
◆ mln_runtime_wake_source_acquire()
| mln_status mln_runtime_wake_source_acquire | ( | mln_runtime | runtime, |
| mln_wake_source * | out_source ) |
Acquires a wake source that releases this runtime's parked owner thread.
Each call returns a distinct handle the host destroys with mln_wake_source_destroy(). A wake source holds its own reference to the runtime's wake state, so it stays valid after the runtime is destroyed and hosts tear the two down in either order.
Returns:
- MLN_STATUS_OK on success.
- MLN_STATUS_INVALID_ARGUMENT when runtime is null or not a live runtime handle, out_source is null, or *out_source is not 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_wake_source_destroy()
| void mln_wake_source_destroy | ( | mln_wake_source | source | ) |
Destroys a wake source.
This function may be called from any thread. Null is a no-op. Destroy each handle exactly once, once every thread that signals it has finished.
◆ mln_wake_source_signal()
| mln_status mln_wake_source_signal | ( | mln_wake_source | source | ) |
Sets the runtime's wake flag and releases the parked owner thread.
This function may be called from any thread.
A signal raised while the owner thread is running sets the wake flag, so the next mln_runtime_pump() call returns without parking. Signalling a wake source whose runtime is destroyed succeeds and does nothing, so hosts shut the two down in either order.
Returns:
- MLN_STATUS_OK on success, including after the runtime is destroyed.
- MLN_STATUS_INVALID_ARGUMENT when source is null.
- MLN_STATUS_NATIVE_ERROR when an internal exception is converted to status.
Generated by
1.13.2