|
MapLibre Native C API
Public C ABI for the MapLibre Native wrapper.
|
Go to the source code of this file.
Create runtimes, control how they load and cache resources, and receive their events.
| typedef enum mln_cache_database_operation mln_cache_database_operation |
A maintenance action on a runtime's cache database.
The cache database is the file that mln_runtime_options.cache_path names. It holds the ambient cache, meaning the resources that maps loaded, and the offline regions.
| typedef enum mln_camera_change_mode mln_camera_change_mode |
Whether a camera change jumps or animates.
| typedef enum mln_camera_change_source mln_camera_change_source |
What moved the camera.
| typedef struct mln_event_batch_view mln_event_batch_view |
A batch of events.
Lifetimes: Step through events by event_size bytes. A newer library's events can be larger than the mln_runtime_event in these headers.
| typedef struct mln_http_header mln_http_header |
An HTTP header.
name follows the rules of mln_http_header_transform_response_set_header().
| typedef struct mln_http_header_rule mln_http_header_rule |
Headers to add to the HTTP requests whose URL matches a pattern.
| typedef struct mln_http_header_transform mln_http_header_transform |
Headers to add to HTTP requests, for mln_runtime_set_http_header_transform().
Set either callback or rules, not both.
| typedef mln_status(*) mln_http_header_transform_callback(void *user_data, mln_resource_kind kind, mln_buffer_view url, mln_http_header_transform_response *out_response) |
Sets the headers of an HTTP request before the library sends it.
url is the request's URL after any resource transform. The request waits for the callback, so return quickly.
Threads: Runs on a library thread.
Lifetimes: url and out_response stay valid until the callback returns.
| typedef struct mln_http_header_transform_response mln_http_header_transform_response |
The headers that an HTTP header transform callback sets.
| typedef enum mln_map_load_error mln_map_load_error |
Why a map failed to load a style.
| typedef enum mln_network_status mln_network_status |
Whether the library may use the network.
The shape of an offline region.
Whether an offline region is downloading.
| typedef int64_t mln_offline_region_id |
The ID of an offline region in a runtime's database.
| typedef struct mln_offline_region_status mln_offline_region_status |
The download progress of an offline region.
| typedef enum mln_render_mode mln_render_mode |
Whether a frame drew the map complete, or lacked resources that are still loading.
| typedef struct mln_rendering_stats mln_rendering_stats |
Statistics about the frames that a map renders.
| typedef enum mln_resource_error_reason mln_resource_error_reason |
Why a resource request failed.
| typedef enum mln_resource_kind mln_resource_kind |
The kind of a resource that the library loads.
| typedef enum mln_resource_kind_flag mln_resource_kind_flag |
A resource kind, as a bit in a set.
| typedef uint32_t mln_resource_kind_flags |
A set of mln_resource_kind_flag bits.
| typedef enum mln_resource_loading_method mln_resource_loading_method |
Where a request may load its resource from.
| typedef enum mln_resource_priority mln_resource_priority |
The priority of a resource request.
| typedef struct mln_resource_provider mln_resource_provider |
A resource provider, for mln_runtime_set_resource_provider().
| typedef void(*) mln_resource_provider_callback(void *user_data, const mln_resource_request_info *request, mln_resource_request handle) |
Serves a network request in place of the library.
Answer with mln_resource_request_complete(), or hand the request back to the library with mln_resource_request_pass_through(). Either can come now or later, from any thread. A request released without an answer fails.
Lifetimes: request and the data it points to stay valid until the callback returns. The callback owns handle.
| typedef struct mln_resource_range mln_resource_range |
The bytes from start to end of a resource, both included.
| typedef void(*) mln_resource_request_cancel_callback(void *user_data, mln_resource_request handle) |
Reports that the library no longer needs a resource request.
The request no longer accepts an answer, so stop working on it and release it.
Lifetimes: The callback borrows handle from its owner.
| typedef struct mln_resource_request_cancel_handler mln_resource_request_cancel_handler |
A cancel callback, for mln_resource_request_set_cancel_callback().
| typedef enum mln_resource_request_field mln_resource_request_field |
The fields that mln_resource_request_info sets.
| typedef uint32_t mln_resource_request_fields |
A set of mln_resource_request_field bits.
| typedef struct mln_resource_request_info mln_resource_request_info |
A request that a resource provider serves.
When the cache holds an earlier copy of the resource, the prior_ fields describe it.
| typedef struct mln_resource_response mln_resource_response |
The answer to a resource request.
| typedef enum mln_resource_response_field mln_resource_response_field |
The fields that mln_resource_response sets.
| typedef uint32_t mln_resource_response_fields |
A set of mln_resource_response_field bits.
| typedef enum mln_resource_response_status mln_resource_response_status |
The outcome of a resource request.
| typedef struct mln_resource_route mln_resource_route |
The requests that a resource provider serves.
| typedef enum mln_resource_storage_policy mln_resource_storage_policy |
Whether the library keeps a loaded resource in its cache.
| typedef struct mln_resource_transform mln_resource_transform |
How to rewrite request URLs, for mln_runtime_set_resource_transform().
Set either callback or rules, not both.
| typedef void(*) mln_resource_transform_callback(void *user_data, mln_resource_kind kind, mln_buffer_view url, mln_resource_transform_request request) |
Rewrites the URL of a network request before the library sends it.
The request waits until you answer with mln_resource_transform_request_complete() or mln_resource_transform_request_fail(). To keep url, complete with it. Releasing request without an answer fails the request. You can answer now or later, from any thread.
Lifetimes: url stays valid until the callback returns. The callback owns request.
| typedef struct mln_resource_transform_error mln_resource_transform_error |
Why a resource transform fails a request.
The fields that mln_resource_transform_error sets.
| typedef uint32_t mln_resource_transform_error_fields |
A set of mln_resource_transform_error_field bits.
| typedef struct mln_resource_transform_rule mln_resource_transform_rule |
Query parameters to add to the URLs of requests that match a pattern.
The library adds the parameters, in order, at the end of the URL's query and before any fragment. It keeps the parameters that the URL already has, even one with the same name.
| typedef enum mln_resource_usage mln_resource_usage |
Whether a request loads a resource for a map or an offline region.
| typedef struct mln_runtime_event mln_runtime_event |
An event that a runtime or one of its maps raised.
| typedef void(*) mln_runtime_event_callback(void *user_data, const mln_event_batch_view *events) |
Receives a batch of events.
Lifetimes: events and the data it points to stay valid until the callback returns.
| typedef struct mln_runtime_event_camera_change mln_runtime_event_camera_change |
The details of MLN_RUNTIME_EVENT_MAP_CAMERA_WILL_CHANGE and MLN_RUNTIME_EVENT_MAP_CAMERA_DID_CHANGE.
| typedef enum mln_runtime_event_flag mln_runtime_event_flag |
An event type, as a bit in a set.
| typedef uint64_t mln_runtime_event_flags |
A set of mln_runtime_event_flag bits.
| typedef struct mln_runtime_event_glyphs mln_runtime_event_glyphs |
The details of a glyph event.
The event covers the glyphs from first to last, both included.
| typedef struct mln_runtime_event_handler mln_runtime_event_handler |
An event callback, for mln_runtime_set_event_handler().
| typedef struct mln_runtime_event_loading_failed mln_runtime_event_loading_failed |
The details of MLN_RUNTIME_EVENT_MAP_LOADING_FAILED.
| typedef struct mln_runtime_event_offline_region_response_error mln_runtime_event_offline_region_response_error |
The details of MLN_RUNTIME_EVENT_OFFLINE_REGION_RESPONSE_ERROR.
| typedef struct mln_runtime_event_offline_region_status mln_runtime_event_offline_region_status |
The details of MLN_RUNTIME_EVENT_OFFLINE_REGION_STATUS_CHANGED.
| typedef struct mln_runtime_event_offline_region_tile_count_limit mln_runtime_event_offline_region_tile_count_limit |
The details of MLN_RUNTIME_EVENT_OFFLINE_REGION_TILE_COUNT_LIMIT_EXCEEDED.
| typedef union mln_runtime_event_payload mln_runtime_event_payload |
The details of an event, in the member that its payload_type names.
The member of mln_runtime_event_payload that an event carries.
| typedef struct mln_runtime_event_render_frame mln_runtime_event_render_frame |
The details of MLN_RUNTIME_EVENT_MAP_RENDER_FRAME_FINISHED.
| typedef struct mln_runtime_event_source_changed mln_runtime_event_source_changed |
The details of MLN_RUNTIME_EVENT_MAP_SOURCE_CHANGED.
The kind of handle that raised an event.
| typedef struct mln_runtime_event_sprite mln_runtime_event_sprite |
The details of a sprite event.
id and url are both empty when the style has no sprite.
| typedef struct mln_runtime_event_style_image mln_runtime_event_style_image |
The details of MLN_RUNTIME_EVENT_MAP_STYLE_IMAGE_MISSING.
| typedef struct mln_runtime_event_tile_action mln_runtime_event_tile_action |
The details of MLN_RUNTIME_EVENT_MAP_TILE_ACTION.
| typedef enum mln_runtime_event_type mln_runtime_event_type |
The kind of an event.
Only maps in MLN_MAP_MODE_CONTINUOUS raise MLN_RUNTIME_EVENT_MAP_LOADING_FINISHED, MLN_RUNTIME_EVENT_MAP_IDLE, and the render frame and render map events. Offline region events come only for the regions and types that mln_runtime_set_offline_region_observed() selects.
| typedef struct mln_runtime_options mln_runtime_options |
Options for mln_runtime_create().
| typedef struct mln_tile_id mln_tile_id |
The ID of a tile.
canonical_x and canonical_y place the tile in the source's grid at zoom canonical_z. overscaled_z is the zoom that the map draws the tile at, and is greater when the source has no tiles that deep. wrap says which copy of the world holds the tile: zero for the main one, negative to the west, and positive to the east.
| typedef enum mln_tile_operation mln_tile_operation |
A step in loading a tile.
| typedef enum mln_url_match_flag mln_url_match_flag |
How a URL pattern matches a request's URL.
A pattern matches the whole URL, query included. Without flags, it matches only the URL that equals it exactly.
| typedef uint32_t mln_url_match_flags |
A set of mln_url_match_flag bits.
| typedef struct mln_url_query_parameter mln_url_query_parameter |
A query parameter that a resource transform rule adds to a URL.
Pass name and value unencoded. The library percent-encodes every byte of them except the letters, digits, -, ., _, and ~, and adds them as name=value.
| enum mln_cache_database_operation : uint32_t |
A maintenance action on a runtime's cache database.
The cache database is the file that mln_runtime_options.cache_path names. It holds the ambient cache, meaning the resources that maps loaded, and the offline regions.
| enum mln_camera_change_mode : uint32_t |
| enum mln_camera_change_source : uint32_t |
What moved the camera.
| enum mln_map_load_error : uint32_t |
| enum mln_network_status : uint32_t |
| enum mln_offline_region_definition_type : uint32_t |
| enum mln_offline_region_download_state : uint32_t |
| enum mln_render_mode : uint32_t |
| enum mln_resource_error_reason : uint32_t |
Why a resource request failed.
| enum mln_resource_kind : uint32_t |
| enum mln_resource_kind_flag : uint32_t |
A resource kind, as a bit in a set.
| enum mln_resource_loading_method : uint32_t |
| enum mln_resource_priority : uint32_t |
| enum mln_resource_request_field : uint32_t |
The fields that mln_resource_request_info sets.
| Enumerator | |
|---|---|
| MLN_RESOURCE_REQUEST_RANGE | |
| MLN_RESOURCE_REQUEST_PRIOR_MODIFIED | |
| MLN_RESOURCE_REQUEST_PRIOR_EXPIRES | |
| enum mln_resource_response_field : uint32_t |
The fields that mln_resource_response sets.
| Enumerator | |
|---|---|
| MLN_RESOURCE_RESPONSE_MODIFIED | |
| MLN_RESOURCE_RESPONSE_EXPIRES | |
| MLN_RESOURCE_RESPONSE_RETRY_AFTER | |
| enum mln_resource_response_status : uint32_t |
| enum mln_resource_storage_policy : uint32_t |
| enum mln_resource_transform_error_field : uint32_t |
The fields that mln_resource_transform_error sets.
| Enumerator | |
|---|---|
| MLN_RESOURCE_TRANSFORM_ERROR_RETRY_AFTER | |
| enum mln_resource_usage : uint32_t |
| enum mln_runtime_event_flag : uint64_t |
An event type, as a bit in a set.
| enum mln_runtime_event_payload_type : uint32_t |
The member of mln_runtime_event_payload that an event carries.
| enum mln_runtime_event_source_type : uint32_t |
| enum mln_runtime_event_type : uint32_t |
The kind of an event.
Only maps in MLN_MAP_MODE_CONTINUOUS raise MLN_RUNTIME_EVENT_MAP_LOADING_FINISHED, MLN_RUNTIME_EVENT_MAP_IDLE, and the render frame and render map events. Offline region events come only for the regions and types that mln_runtime_set_offline_region_observed() selects.
| enum mln_tile_operation : uint32_t |
A step in loading a tile.
| enum mln_url_match_flag : uint32_t |
How a URL pattern matches a request's URL.
A pattern matches the whole URL, query included. Without flags, it matches only the URL that equals it exactly.
| Enumerator | |
|---|---|
| MLN_URL_MATCH_GLOB | The URL matches the pattern as a glob. * matches any characters except /, ** matches any characters, and ? matches one character except /. \\endiskip makes the next character match only itself. For example, https://*.example.com/tiles/** matches every URL under /tiles/ on each subdomain of example.com. |
| 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 a header on the request that an HTTP header transform callback handles.
Header names ignore letter case, and setting a header again replaces its value. name can't be a header that the library or the platform manages: Accept-Encoding, Connection, Content-Length, Host, If-Modified-Since, If-None-Match, Keep-Alive, Proxy-Authorization, Proxy-Connection, Range, TE, Trailer, Transfer-Encoding, Upgrade, or User-Agent.
| mln_status mln_network_get_status | ( | mln_network_status * | out_status, |
| mln_diagnostic * | out_diagnostic ) |
Reads whether the library may use the network.
| mln_status mln_network_set_status | ( | mln_network_status | status, |
| mln_diagnostic * | out_diagnostic ) |
Tells the library whether it may use the network.
While the status is MLN_NETWORK_STATUS_OFFLINE, the library starts no network requests. The requests that wait start when the status returns to MLN_NETWORK_STATUS_ONLINE. The status starts as online and applies to every runtime in the process.
| mln_status mln_resource_request_complete | ( | mln_resource_request | handle, |
| const mln_resource_response * | response, | ||
| mln_diagnostic * | out_diagnostic ) |
Answers a resource request.
A failed answer fails the request with MLN_RESOURCE_ERROR_REASON_OTHER, as mln_resource_request_release() does.
Returns:
Lifetimes: The call ends handle whatever it returns.
| mln_status mln_resource_request_is_cancelled | ( | mln_resource_request | handle, |
| bool * | out_cancelled, | ||
| mln_diagnostic * | out_diagnostic ) |
Reads whether the library cancelled a resource request.
| mln_status mln_resource_request_pass_through | ( | mln_resource_request | handle, |
| mln_diagnostic * | out_diagnostic ) |
Hands a resource request back to the library to load as usual.
A failed call fails the request with MLN_RESOURCE_ERROR_REASON_OTHER, as mln_resource_request_release() does.
Returns:
Lifetimes: The call ends handle whatever it returns.
| void mln_resource_request_release | ( | mln_resource_request | handle | ) |
Releases a resource request.
Releasing a request without an answer fails it with MLN_RESOURCE_ERROR_REASON_OTHER.
| 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 ) |
Calls a callback when the library cancels a resource request.
The callback never runs after the request is answered. A request takes one cancel callback. When the library has already cancelled the request, the call reports that instead and the callback never runs.
Lifetimes: When out_cancelled is true, the library never calls the handler's release_user_data, and the caller still owns its user_data.
| 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 the URL to load instead.
url must not be empty. A failed answer fails the request with MLN_RESOURCE_ERROR_REASON_OTHER, as mln_resource_transform_request_release() does.
Lifetimes: The call ends request whatever it returns.
| mln_status mln_resource_transform_request_fail | ( | mln_resource_transform_request | request, |
| const mln_resource_transform_error * | error, | ||
| mln_diagnostic * | out_diagnostic ) |
Fails a resource transform request without sending it.
The library retries a request that failed for a reason it retries, such as MLN_RESOURCE_ERROR_REASON_CONNECTION, and the retry calls the transform again. When this call fails, the request fails with MLN_RESOURCE_ERROR_REASON_OTHER, as mln_resource_transform_request_release() does.
Lifetimes: The call ends request whatever it returns.
| void mln_resource_transform_request_release | ( | mln_resource_transform_request | request | ) |
Releases a resource transform request.
Releasing a request without an answer fails it with MLN_RESOURCE_ERROR_REASON_OTHER.
| mln_status mln_runtime_clear_event_handler | ( | mln_runtime | runtime, |
| const mln_completion * | completion, | ||
| mln_diagnostic * | out_diagnostic ) |
Stops sending the events of the runtime and its maps to a callback.
| mln_status mln_runtime_clear_http_header_transform | ( | mln_runtime | runtime, |
| const mln_completion * | completion, | ||
| mln_diagnostic * | out_diagnostic ) |
Stops adding headers to the runtime's HTTP requests.
| mln_status mln_runtime_clear_resource_provider | ( | mln_runtime | runtime, |
| const mln_completion * | completion, | ||
| mln_diagnostic * | out_diagnostic ) |
Removes the runtime's resource provider, so the library loads every request itself.
| mln_status mln_runtime_clear_resource_transform | ( | mln_runtime | runtime, |
| const mln_completion * | completion, | ||
| mln_diagnostic * | out_diagnostic ) |
Stops rewriting the URLs of the runtime's network requests.
| mln_status mln_runtime_create | ( | const mln_runtime_options * | options, |
| mln_runtime * | out_runtime, | ||
| mln_diagnostic * | out_diagnostic ) |
Creates a runtime.
A runtime holds maps and the resource loading, cache, and offline regions that they share. In a browser, create runtimes on a Web Worker, not on the main thread.
Returns:
| mln_status mln_runtime_dispose | ( | mln_runtime | runtime, |
| mln_diagnostic * | out_diagnostic ) |
Releases a runtime in any state, without waiting.
The runtime finishes its teardown after its maps are released.
| mln_status mln_runtime_release | ( | mln_runtime | runtime, |
| const mln_completion * | completion, | ||
| mln_diagnostic * | out_diagnostic ) |
Releases a runtime.
Release the runtime's maps first.
| mln_status mln_runtime_run_cache_database_operation | ( | mln_runtime | runtime, |
| mln_cache_database_operation | operation, | ||
| const mln_completion * | completion, | ||
| mln_diagnostic * | out_diagnostic ) |
Runs a maintenance action on the runtime's cache database.
| mln_status mln_runtime_set_event_handler | ( | mln_runtime | runtime, |
| const mln_runtime_event_handler * | handler, | ||
| const mln_completion * | completion, | ||
| mln_diagnostic * | out_diagnostic ) |
Sends the events of the runtime and its maps to a callback.
The callback replaces the one set before.
| 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 ) |
Adds headers to the runtime's HTTP requests.
The transform replaces the one set before. In a browser or on OpenHarmony, serve the requests with mln_runtime_set_resource_provider() instead.
Returns:
| mln_status mln_runtime_set_maximum_ambient_cache_size | ( | mln_runtime | runtime, |
| uint64_t | size, | ||
| const mln_completion * | completion, | ||
| mln_diagnostic * | out_diagnostic ) |
Limits the size of the runtime's ambient cache.
size is in bytes. Offline regions don't count toward it. It defaults to 50 MB, or to 0 in the browser when the runtime has no cache file.
| mln_status mln_runtime_set_resource_provider | ( | mln_runtime | runtime, |
| const mln_resource_provider * | provider, | ||
| const mln_completion * | completion, | ||
| mln_diagnostic * | out_diagnostic ) |
Serves the runtime's network requests through a callback.
The provider receives the network requests that its routes match, and the library loads the rest as usual. A provider can serve URL schemes that the library can't load itself. The provider replaces the one set before.
| mln_status mln_runtime_set_resource_transform | ( | mln_runtime | runtime, |
| const mln_resource_transform * | transform, | ||
| const mln_completion * | completion, | ||
| mln_diagnostic * | out_diagnostic ) |
Rewrites the URLs of the runtime's network requests.
The transform replaces the one set before.