MapLibre Native C API
Public C ABI for the MapLibre Native wrapper.
Loading...
Searching...
No Matches
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_camera_change
struct  mln_runtime_event_loading_failed
struct  mln_runtime_event_style_image
struct  mln_runtime_event_source_changed
struct  mln_tile_id
struct  mln_runtime_event_tile_action
struct  mln_runtime_event_glyphs
struct  mln_runtime_event_sprite
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_error
struct  mln_url_query_parameter
struct  mln_resource_transform_rule
struct  mln_resource_transform
struct  mln_http_header_transform_response
struct  mln_http_header_transform
struct  mln_resource_range
struct  mln_resource_request_info
struct  mln_resource_response
struct  mln_resource_request_cancel_handler
struct  mln_resource_provider

Typedefs

typedef enum mln_network_status mln_network_status
typedef enum mln_cache_database_operation mln_cache_database_operation
typedef int64_t mln_offline_region_id
typedef enum mln_offline_region_definition_type mln_offline_region_definition_type
typedef enum mln_offline_region_download_state mln_offline_region_download_state
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_flag mln_runtime_event_flag
typedef uint64_t mln_runtime_event_flags
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_camera_change_source mln_camera_change_source
typedef enum mln_map_load_error mln_map_load_error
typedef enum mln_render_mode mln_render_mode
typedef enum mln_tile_operation mln_tile_operation
typedef enum mln_resource_kind mln_resource_kind
typedef enum mln_resource_loading_method mln_resource_loading_method
typedef enum mln_resource_priority mln_resource_priority
typedef enum mln_resource_usage mln_resource_usage
typedef enum mln_resource_storage_policy mln_resource_storage_policy
typedef enum mln_resource_response_status mln_resource_response_status
typedef enum mln_resource_error_reason mln_resource_error_reason
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_camera_change mln_runtime_event_camera_change
typedef struct mln_runtime_event_loading_failed mln_runtime_event_loading_failed
typedef struct mln_runtime_event_style_image mln_runtime_event_style_image
typedef struct mln_runtime_event_source_changed mln_runtime_event_source_changed
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_glyphs mln_runtime_event_glyphs
typedef struct mln_runtime_event_sprite mln_runtime_event_sprite
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_flag mln_resource_kind_flag
typedef uint32_t mln_resource_kind_flags
typedef enum mln_url_match_flag mln_url_match_flag
typedef uint32_t 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, mln_resource_kind kind, mln_buffer_view url, mln_resource_transform_request request)
typedef enum mln_resource_transform_error_field mln_resource_transform_error_field
typedef uint32_t mln_resource_transform_error_fields
typedef struct mln_resource_transform_error mln_resource_transform_error
typedef struct mln_url_query_parameter mln_url_query_parameter
typedef struct mln_resource_transform_rule mln_resource_transform_rule
typedef struct mln_resource_transform mln_resource_transform
typedef struct mln_http_header_transform_response mln_http_header_transform_response
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)
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 uint32_t mln_resource_request_fields
typedef struct mln_resource_request_info mln_resource_request_info
typedef enum mln_resource_response_field mln_resource_response_field
typedef uint32_t mln_resource_response_fields
typedef struct mln_resource_response mln_resource_response
typedef void(*) 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_network_status : uint32_t { MLN_NETWORK_STATUS_ONLINE = 1 , MLN_NETWORK_STATUS_OFFLINE = 2 }
enum  mln_cache_database_operation : uint32_t { MLN_CACHE_DATABASE_OPERATION_CLEAR = 1 , MLN_CACHE_DATABASE_OPERATION_INVALIDATE = 2 , MLN_CACHE_DATABASE_OPERATION_PACK = 3 , MLN_CACHE_DATABASE_OPERATION_RESET = 4 }
enum  mln_offline_region_definition_type : uint32_t { MLN_OFFLINE_REGION_DEFINITION_TILE_PYRAMID = 1 , MLN_OFFLINE_REGION_DEFINITION_GEOMETRY = 2 }
enum  mln_offline_region_download_state : uint32_t { MLN_OFFLINE_REGION_DOWNLOAD_INACTIVE = 0 , MLN_OFFLINE_REGION_DOWNLOAD_ACTIVE = 1 }
enum  mln_runtime_event_type : uint32_t {
  MLN_RUNTIME_EVENT_MAP_CAMERA_WILL_CHANGE = 1 , MLN_RUNTIME_EVENT_MAP_CAMERA_IS_CHANGING = 2 , MLN_RUNTIME_EVENT_MAP_CAMERA_DID_CHANGE = 3 , MLN_RUNTIME_EVENT_MAP_STYLE_LOADED = 4 ,
  MLN_RUNTIME_EVENT_MAP_LOADING_STARTED = 5 , MLN_RUNTIME_EVENT_MAP_LOADING_FINISHED = 6 , MLN_RUNTIME_EVENT_MAP_LOADING_FAILED = 7 , MLN_RUNTIME_EVENT_MAP_IDLE = 8 ,
  MLN_RUNTIME_EVENT_MAP_RENDER_ERROR = 9 , MLN_RUNTIME_EVENT_MAP_RENDER_FRAME_STARTED = 10 , MLN_RUNTIME_EVENT_MAP_RENDER_FRAME_FINISHED = 11 , MLN_RUNTIME_EVENT_MAP_RENDER_MAP_STARTED = 12 ,
  MLN_RUNTIME_EVENT_MAP_RENDER_MAP_FINISHED = 13 , MLN_RUNTIME_EVENT_MAP_STYLE_IMAGE_MISSING = 14 , MLN_RUNTIME_EVENT_MAP_TILE_ACTION = 15 , MLN_RUNTIME_EVENT_MAP_SOURCE_CHANGED = 16 ,
  MLN_RUNTIME_EVENT_OFFLINE_REGION_STATUS_CHANGED = 17 , MLN_RUNTIME_EVENT_OFFLINE_REGION_RESPONSE_ERROR = 18 , MLN_RUNTIME_EVENT_OFFLINE_REGION_TILE_COUNT_LIMIT_EXCEEDED = 19 , MLN_RUNTIME_EVENT_MAP_GLYPHS_REQUESTED = 20 ,
  MLN_RUNTIME_EVENT_MAP_GLYPHS_LOADED = 21 , MLN_RUNTIME_EVENT_MAP_GLYPHS_ERROR = 22 , MLN_RUNTIME_EVENT_MAP_SPRITE_REQUESTED = 23 , MLN_RUNTIME_EVENT_MAP_SPRITE_LOADED = 24 ,
  MLN_RUNTIME_EVENT_MAP_SPRITE_ERROR = 25
}
enum  mln_runtime_event_flag : uint64_t {
  MLN_RUNTIME_EVENT_FLAG_NONE = 0 , MLN_RUNTIME_EVENT_FLAG_MAP_CAMERA_WILL_CHANGE , MLN_RUNTIME_EVENT_FLAG_MAP_CAMERA_IS_CHANGING , MLN_RUNTIME_EVENT_FLAG_MAP_CAMERA_DID_CHANGE ,
  MLN_RUNTIME_EVENT_FLAG_MAP_STYLE_LOADED , MLN_RUNTIME_EVENT_FLAG_MAP_LOADING_STARTED , MLN_RUNTIME_EVENT_FLAG_MAP_LOADING_FINISHED , MLN_RUNTIME_EVENT_FLAG_MAP_LOADING_FAILED ,
  MLN_RUNTIME_EVENT_FLAG_MAP_IDLE = 1ULL << MLN_RUNTIME_EVENT_MAP_IDLE , MLN_RUNTIME_EVENT_FLAG_MAP_RENDER_ERROR , MLN_RUNTIME_EVENT_FLAG_MAP_RENDER_FRAME_STARTED , MLN_RUNTIME_EVENT_FLAG_MAP_RENDER_FRAME_FINISHED ,
  MLN_RUNTIME_EVENT_FLAG_MAP_RENDER_MAP_STARTED , MLN_RUNTIME_EVENT_FLAG_MAP_RENDER_MAP_FINISHED , MLN_RUNTIME_EVENT_FLAG_MAP_STYLE_IMAGE_MISSING , MLN_RUNTIME_EVENT_FLAG_MAP_TILE_ACTION ,
  MLN_RUNTIME_EVENT_FLAG_MAP_SOURCE_CHANGED , MLN_RUNTIME_EVENT_FLAG_OFFLINE_REGION_STATUS_CHANGED , MLN_RUNTIME_EVENT_FLAG_OFFLINE_REGION_RESPONSE_ERROR , MLN_RUNTIME_EVENT_FLAG_OFFLINE_REGION_TILE_COUNT_LIMIT_EXCEEDED ,
  MLN_RUNTIME_EVENT_FLAG_MAP_GLYPHS_REQUESTED , MLN_RUNTIME_EVENT_FLAG_MAP_GLYPHS_LOADED , MLN_RUNTIME_EVENT_FLAG_MAP_GLYPHS_ERROR , MLN_RUNTIME_EVENT_FLAG_MAP_SPRITE_REQUESTED ,
  MLN_RUNTIME_EVENT_FLAG_MAP_SPRITE_LOADED , MLN_RUNTIME_EVENT_FLAG_MAP_SPRITE_ERROR , MLN_RUNTIME_EVENT_FLAG_ALL_MAP_EVENTS , MLN_RUNTIME_EVENT_FLAG_ALL_RUNTIME_EVENTS ,
  MLN_RUNTIME_EVENT_FLAG_ALL
}
enum  mln_runtime_event_source_type : uint32_t { MLN_RUNTIME_EVENT_SOURCE_RUNTIME = 0 , MLN_RUNTIME_EVENT_SOURCE_MAP = 1 }
enum  mln_runtime_event_payload_type : uint32_t {
  MLN_RUNTIME_EVENT_PAYLOAD_NONE = 0 , MLN_RUNTIME_EVENT_PAYLOAD_CAMERA_CHANGE = 1 , MLN_RUNTIME_EVENT_PAYLOAD_LOADING_FAILED = 2 , MLN_RUNTIME_EVENT_PAYLOAD_RENDER_FRAME = 3 ,
  MLN_RUNTIME_EVENT_PAYLOAD_STYLE_IMAGE = 4 , MLN_RUNTIME_EVENT_PAYLOAD_TILE_ACTION = 5 , MLN_RUNTIME_EVENT_PAYLOAD_SOURCE_CHANGED = 6 , MLN_RUNTIME_EVENT_PAYLOAD_OFFLINE_REGION_STATUS = 7 ,
  MLN_RUNTIME_EVENT_PAYLOAD_OFFLINE_REGION_RESPONSE_ERROR = 8 , MLN_RUNTIME_EVENT_PAYLOAD_OFFLINE_REGION_TILE_COUNT_LIMIT = 9 , MLN_RUNTIME_EVENT_PAYLOAD_GLYPHS = 10 , MLN_RUNTIME_EVENT_PAYLOAD_SPRITE = 11
}
enum  mln_camera_change_mode : uint32_t { MLN_CAMERA_CHANGE_MODE_IMMEDIATE = 0 , MLN_CAMERA_CHANGE_MODE_ANIMATED = 1 }
enum  mln_camera_change_source : uint32_t { MLN_CAMERA_CHANGE_SOURCE_COMMAND = 0 , MLN_CAMERA_CHANGE_SOURCE_GESTURE = 1 , MLN_CAMERA_CHANGE_SOURCE_MOMENTUM = 2 }
enum  mln_map_load_error : uint32_t { MLN_MAP_LOAD_ERROR_UNKNOWN = 0 , MLN_MAP_LOAD_ERROR_STYLE_PARSE = 1 , MLN_MAP_LOAD_ERROR_STYLE_LOAD = 2 }
enum  mln_render_mode : uint32_t { MLN_RENDER_MODE_PARTIAL = 0 , MLN_RENDER_MODE_FULL = 1 }
enum  mln_tile_operation : uint32_t {
  MLN_TILE_OPERATION_REQUESTED_FROM_CACHE = 0 , MLN_TILE_OPERATION_REQUESTED_FROM_NETWORK = 1 , MLN_TILE_OPERATION_LOAD_FROM_NETWORK = 2 , MLN_TILE_OPERATION_LOAD_FROM_CACHE = 3 ,
  MLN_TILE_OPERATION_START_PARSE = 4 , MLN_TILE_OPERATION_END_PARSE = 5 , MLN_TILE_OPERATION_ERROR = 6 , MLN_TILE_OPERATION_CANCELLED = 7 ,
  MLN_TILE_OPERATION_NULL = 8
}
enum  mln_resource_kind : uint32_t {
  MLN_RESOURCE_KIND_UNKNOWN = 0 , MLN_RESOURCE_KIND_STYLE = 1 , MLN_RESOURCE_KIND_SOURCE = 2 , MLN_RESOURCE_KIND_TILE = 3 ,
  MLN_RESOURCE_KIND_GLYPHS = 4 , MLN_RESOURCE_KIND_SPRITE_IMAGE = 5 , MLN_RESOURCE_KIND_SPRITE_JSON = 6 , MLN_RESOURCE_KIND_IMAGE = 7
}
enum  mln_resource_loading_method : uint32_t { MLN_RESOURCE_LOADING_METHOD_ALL = 0 , MLN_RESOURCE_LOADING_METHOD_CACHE_ONLY = 1 , MLN_RESOURCE_LOADING_METHOD_NETWORK_ONLY = 2 }
enum  mln_resource_priority : uint32_t { MLN_RESOURCE_PRIORITY_REGULAR = 0 , MLN_RESOURCE_PRIORITY_LOW = 1 }
enum  mln_resource_usage : uint32_t { MLN_RESOURCE_USAGE_ONLINE = 0 , MLN_RESOURCE_USAGE_OFFLINE = 1 }
enum  mln_resource_storage_policy : uint32_t { MLN_RESOURCE_STORAGE_POLICY_PERMANENT = 0 , MLN_RESOURCE_STORAGE_POLICY_VOLATILE = 1 }
enum  mln_resource_response_status : uint32_t { MLN_RESOURCE_RESPONSE_STATUS_OK = 0 , MLN_RESOURCE_RESPONSE_STATUS_ERROR = 1 , MLN_RESOURCE_RESPONSE_STATUS_NO_CONTENT = 2 , MLN_RESOURCE_RESPONSE_STATUS_NOT_MODIFIED = 3 }
enum  mln_resource_error_reason : uint32_t {
  MLN_RESOURCE_ERROR_REASON_OTHER = 0 , MLN_RESOURCE_ERROR_REASON_NOT_FOUND = 1 , MLN_RESOURCE_ERROR_REASON_SERVER = 2 , MLN_RESOURCE_ERROR_REASON_CONNECTION = 3 ,
  MLN_RESOURCE_ERROR_REASON_RATE_LIMIT = 4
}
enum  mln_resource_kind_flag : uint32_t {
  MLN_RESOURCE_KIND_FLAG_UNKNOWN = 1U << MLN_RESOURCE_KIND_UNKNOWN , MLN_RESOURCE_KIND_FLAG_STYLE = 1U << MLN_RESOURCE_KIND_STYLE , MLN_RESOURCE_KIND_FLAG_SOURCE = 1U << MLN_RESOURCE_KIND_SOURCE , MLN_RESOURCE_KIND_FLAG_TILE = 1U << MLN_RESOURCE_KIND_TILE ,
  MLN_RESOURCE_KIND_FLAG_GLYPHS = 1U << MLN_RESOURCE_KIND_GLYPHS , MLN_RESOURCE_KIND_FLAG_SPRITE_IMAGE = 1U << MLN_RESOURCE_KIND_SPRITE_IMAGE , MLN_RESOURCE_KIND_FLAG_SPRITE_JSON = 1U << MLN_RESOURCE_KIND_SPRITE_JSON , MLN_RESOURCE_KIND_FLAG_IMAGE = 1U << MLN_RESOURCE_KIND_IMAGE ,
  MLN_RESOURCE_KIND_FLAG_ALL
}
enum  mln_url_match_flag : uint32_t { MLN_URL_MATCH_GLOB = 1U << 0U }
enum  mln_resource_transform_error_field : uint32_t { MLN_RESOURCE_TRANSFORM_ERROR_RETRY_AFTER = 1U << 0U }
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 }

Functions

mln_status mln_network_get_status (mln_network_status *out_status, mln_diagnostic *out_diagnostic)
mln_status mln_network_set_status (mln_network_status status, mln_diagnostic *out_diagnostic)
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)
mln_status mln_runtime_create (const mln_runtime_options *options, mln_runtime *out_runtime, mln_diagnostic *out_diagnostic)
mln_status mln_runtime_set_resource_provider (mln_runtime runtime, const mln_resource_provider *provider, const mln_completion *completion, mln_diagnostic *out_diagnostic)
mln_status mln_runtime_clear_resource_provider (mln_runtime runtime, const mln_completion *completion, mln_diagnostic *out_diagnostic)
mln_status mln_resource_request_complete (mln_resource_request handle, const mln_resource_response *response, mln_diagnostic *out_diagnostic)
mln_status mln_resource_request_pass_through (mln_resource_request handle, mln_diagnostic *out_diagnostic)
mln_status mln_resource_request_is_cancelled (mln_resource_request handle, bool *out_cancelled, mln_diagnostic *out_diagnostic)
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)
void mln_resource_request_release (mln_resource_request handle)
mln_status mln_runtime_set_resource_transform (mln_runtime runtime, const mln_resource_transform *transform, const mln_completion *completion, mln_diagnostic *out_diagnostic)
mln_status mln_runtime_clear_resource_transform (mln_runtime runtime, const mln_completion *completion, mln_diagnostic *out_diagnostic)
mln_status mln_resource_transform_request_complete (mln_resource_transform_request request, mln_buffer_view url, mln_diagnostic *out_diagnostic)
mln_status mln_resource_transform_request_fail (mln_resource_transform_request request, const mln_resource_transform_error *error, mln_diagnostic *out_diagnostic)
void mln_resource_transform_request_release (mln_resource_transform_request request)
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)
mln_status mln_runtime_clear_http_header_transform (mln_runtime runtime, const mln_completion *completion, mln_diagnostic *out_diagnostic)
mln_status mln_runtime_run_cache_database_operation (mln_runtime runtime, mln_cache_database_operation operation, const mln_completion *completion, mln_diagnostic *out_diagnostic)
mln_status mln_runtime_set_maximum_ambient_cache_size (mln_runtime runtime, uint64_t size, const mln_completion *completion, mln_diagnostic *out_diagnostic)
mln_status mln_runtime_release (mln_runtime runtime, const mln_completion *completion, mln_diagnostic *out_diagnostic)
mln_status mln_runtime_dispose (mln_runtime runtime, mln_diagnostic *out_diagnostic)
mln_status mln_runtime_set_event_handler (mln_runtime runtime, const mln_runtime_event_handler *handler, const mln_completion *completion, mln_diagnostic *out_diagnostic)
mln_status mln_runtime_clear_event_handler (mln_runtime runtime, const mln_completion *completion, mln_diagnostic *out_diagnostic)

Detailed Description

Create runtimes, control how they load and cache resources, and receive their events.

Typedef Documentation

◆ 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.

◆ mln_camera_change_mode

Whether a camera change jumps or animates.

◆ mln_camera_change_source

What moved the camera.

◆ mln_event_batch_view

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.

◆ mln_http_header

typedef struct mln_http_header mln_http_header

An HTTP header.

name follows the rules of mln_http_header_transform_response_set_header().

◆ mln_http_header_rule

typedef struct mln_http_header_rule mln_http_header_rule

Headers to add to the HTTP requests whose URL matches a pattern.

◆ mln_http_header_transform

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.

◆ mln_http_header_transform_callback

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.

◆ mln_http_header_transform_response

typedef struct mln_http_header_transform_response mln_http_header_transform_response

The headers that an HTTP header transform callback sets.

◆ mln_map_load_error

Why a map failed to load a style.

◆ mln_network_status

Whether the library may use the network.

◆ mln_offline_region_definition_type

The shape of an offline region.

◆ mln_offline_region_download_state

Whether an offline region is downloading.

◆ mln_offline_region_id

typedef int64_t mln_offline_region_id

The ID of an offline region in a runtime's database.

◆ mln_offline_region_status

typedef struct mln_offline_region_status mln_offline_region_status

The download progress of an offline region.

◆ mln_render_mode

Whether a frame drew the map complete, or lacked resources that are still loading.

◆ mln_rendering_stats

typedef struct mln_rendering_stats mln_rendering_stats

Statistics about the frames that a map renders.

◆ mln_resource_error_reason

Why a resource request failed.

◆ mln_resource_kind

The kind of a resource that the library loads.

◆ mln_resource_kind_flag

A resource kind, as a bit in a set.

◆ mln_resource_kind_flags

typedef uint32_t mln_resource_kind_flags

A set of mln_resource_kind_flag bits.

◆ mln_resource_loading_method

Where a request may load its resource from.

◆ mln_resource_priority

The priority of a resource request.

◆ mln_resource_provider

typedef struct mln_resource_provider mln_resource_provider

A resource provider, for mln_runtime_set_resource_provider().

◆ mln_resource_provider_callback

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.

◆ mln_resource_range

typedef struct mln_resource_range mln_resource_range

The bytes from start to end of a resource, both included.

◆ mln_resource_request_cancel_callback

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.

◆ mln_resource_request_cancel_handler

typedef struct mln_resource_request_cancel_handler mln_resource_request_cancel_handler

◆ mln_resource_request_field

◆ mln_resource_request_fields

◆ mln_resource_request_info

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.

◆ mln_resource_response

typedef struct mln_resource_response mln_resource_response

The answer to a resource request.

◆ mln_resource_response_field

◆ mln_resource_response_fields

◆ mln_resource_response_status

The outcome of a resource request.

◆ mln_resource_route

typedef struct mln_resource_route mln_resource_route

The requests that a resource provider serves.

◆ mln_resource_storage_policy

Whether the library keeps a loaded resource in its cache.

◆ mln_resource_transform

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.

◆ mln_resource_transform_callback

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.

◆ mln_resource_transform_error

typedef struct mln_resource_transform_error mln_resource_transform_error

Why a resource transform fails a request.

◆ mln_resource_transform_error_field

◆ mln_resource_transform_error_fields

◆ mln_resource_transform_rule

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.

◆ mln_resource_usage

Whether a request loads a resource for a map or an offline region.

◆ mln_runtime_event

typedef struct mln_runtime_event mln_runtime_event

An event that a runtime or one of its maps raised.

◆ mln_runtime_event_callback

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.

◆ mln_runtime_event_camera_change

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.

◆ mln_runtime_event_flag

An event type, as a bit in a set.

◆ mln_runtime_event_flags

typedef uint64_t mln_runtime_event_flags

A set of mln_runtime_event_flag bits.

◆ mln_runtime_event_glyphs

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.

◆ mln_runtime_event_handler

typedef struct mln_runtime_event_handler mln_runtime_event_handler

An event callback, for mln_runtime_set_event_handler().

◆ mln_runtime_event_loading_failed

typedef struct mln_runtime_event_loading_failed mln_runtime_event_loading_failed

The details of MLN_RUNTIME_EVENT_MAP_LOADING_FAILED.

◆ mln_runtime_event_offline_region_response_error

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.

◆ mln_runtime_event_offline_region_status

typedef struct mln_runtime_event_offline_region_status mln_runtime_event_offline_region_status

The details of 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

The details of MLN_RUNTIME_EVENT_OFFLINE_REGION_TILE_COUNT_LIMIT_EXCEEDED.

◆ mln_runtime_event_payload

typedef union mln_runtime_event_payload mln_runtime_event_payload

The details of an event, in the member that its payload_type names.

◆ mln_runtime_event_payload_type

◆ mln_runtime_event_render_frame

typedef struct mln_runtime_event_render_frame mln_runtime_event_render_frame

The details of MLN_RUNTIME_EVENT_MAP_RENDER_FRAME_FINISHED.

◆ mln_runtime_event_source_changed

typedef struct mln_runtime_event_source_changed mln_runtime_event_source_changed

The details of MLN_RUNTIME_EVENT_MAP_SOURCE_CHANGED.

◆ mln_runtime_event_source_type

The kind of handle that raised an event.

◆ mln_runtime_event_sprite

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.

◆ mln_runtime_event_style_image

typedef struct mln_runtime_event_style_image mln_runtime_event_style_image

The details of MLN_RUNTIME_EVENT_MAP_STYLE_IMAGE_MISSING.

◆ mln_runtime_event_tile_action

typedef struct mln_runtime_event_tile_action mln_runtime_event_tile_action

The details of MLN_RUNTIME_EVENT_MAP_TILE_ACTION.

◆ 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.

◆ mln_runtime_options

typedef struct mln_runtime_options mln_runtime_options

Options for mln_runtime_create().

◆ mln_tile_id

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.

◆ mln_tile_operation

A step in loading a tile.

◆ 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.

◆ mln_url_match_flags

typedef uint32_t mln_url_match_flags

A set of mln_url_match_flag bits.

◆ mln_url_query_parameter

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.

Enumeration Type Documentation

◆ 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.

Enumerator
MLN_CACHE_DATABASE_OPERATION_CLEAR 

Deletes the ambient cache's resources and frees the space they used. Offline regions keep their resources.

MLN_CACHE_DATABASE_OPERATION_INVALIDATE 

Keeps the ambient cache's resources, but makes maps check each one with the server before they use it again. Offline regions keep their resources as they are.

MLN_CACHE_DATABASE_OPERATION_PACK 

Compacts the whole database file to free the disk space that it no longer uses.

MLN_CACHE_DATABASE_OPERATION_RESET 

Deletes the whole database, offline regions included, and starts an empty one.

◆ mln_camera_change_mode

enum mln_camera_change_mode : uint32_t

Whether a camera change jumps or animates.

Enumerator
MLN_CAMERA_CHANGE_MODE_IMMEDIATE 
MLN_CAMERA_CHANGE_MODE_ANIMATED 

◆ mln_camera_change_source

enum mln_camera_change_source : uint32_t

What moved the camera.

Enumerator
MLN_CAMERA_CHANGE_SOURCE_COMMAND 

A camera command outside a gesture, or the map itself, as when a resize keeps the camera within its bounds.

MLN_CAMERA_CHANGE_SOURCE_GESTURE 

A camera command with a gesture phase.

MLN_CAMERA_CHANGE_SOURCE_MOMENTUM 

The momentum and bearing snap that a gesture's end started.

◆ mln_map_load_error

enum mln_map_load_error : uint32_t

Why a map failed to load a style.

Enumerator
MLN_MAP_LOAD_ERROR_UNKNOWN 
MLN_MAP_LOAD_ERROR_STYLE_PARSE 

The style document isn't a valid style.

MLN_MAP_LOAD_ERROR_STYLE_LOAD 

The style's request failed, such as with a 404 or a missing file.

◆ mln_network_status

enum mln_network_status : uint32_t

Whether the library may use the network.

Enumerator
MLN_NETWORK_STATUS_ONLINE 
MLN_NETWORK_STATUS_OFFLINE 

◆ mln_offline_region_definition_type

The shape of an offline region.

Enumerator
MLN_OFFLINE_REGION_DEFINITION_TILE_PYRAMID 
MLN_OFFLINE_REGION_DEFINITION_GEOMETRY 

◆ mln_offline_region_download_state

Whether an offline region is downloading.

Enumerator
MLN_OFFLINE_REGION_DOWNLOAD_INACTIVE 
MLN_OFFLINE_REGION_DOWNLOAD_ACTIVE 

◆ mln_render_mode

enum mln_render_mode : uint32_t

Whether a frame drew the map complete, or lacked resources that are still loading.

Enumerator
MLN_RENDER_MODE_PARTIAL 
MLN_RENDER_MODE_FULL 

◆ mln_resource_error_reason

enum mln_resource_error_reason : uint32_t

Why a resource request failed.

Enumerator
MLN_RESOURCE_ERROR_REASON_OTHER 

A reason that no other value names.

MLN_RESOURCE_ERROR_REASON_NOT_FOUND 
MLN_RESOURCE_ERROR_REASON_SERVER 

The server reported an error.

MLN_RESOURCE_ERROR_REASON_CONNECTION 

The server couldn't be reached.

MLN_RESOURCE_ERROR_REASON_RATE_LIMIT 

◆ mln_resource_kind

enum mln_resource_kind : uint32_t

The kind of a resource that the library loads.

Enumerator
MLN_RESOURCE_KIND_UNKNOWN 
MLN_RESOURCE_KIND_STYLE 
MLN_RESOURCE_KIND_SOURCE 
MLN_RESOURCE_KIND_TILE 
MLN_RESOURCE_KIND_GLYPHS 
MLN_RESOURCE_KIND_SPRITE_IMAGE 
MLN_RESOURCE_KIND_SPRITE_JSON 
MLN_RESOURCE_KIND_IMAGE 

◆ mln_resource_kind_flag

enum mln_resource_kind_flag : uint32_t

A resource kind, as a bit in a set.

Enumerator
MLN_RESOURCE_KIND_FLAG_UNKNOWN 
MLN_RESOURCE_KIND_FLAG_STYLE 
MLN_RESOURCE_KIND_FLAG_SOURCE 
MLN_RESOURCE_KIND_FLAG_TILE 
MLN_RESOURCE_KIND_FLAG_GLYPHS 
MLN_RESOURCE_KIND_FLAG_SPRITE_IMAGE 
MLN_RESOURCE_KIND_FLAG_SPRITE_JSON 
MLN_RESOURCE_KIND_FLAG_IMAGE 
MLN_RESOURCE_KIND_FLAG_ALL 

◆ mln_resource_loading_method

enum mln_resource_loading_method : uint32_t

Where a request may load its resource from.

Enumerator
MLN_RESOURCE_LOADING_METHOD_ALL 

The cache or the network.

MLN_RESOURCE_LOADING_METHOD_CACHE_ONLY 
MLN_RESOURCE_LOADING_METHOD_NETWORK_ONLY 

◆ mln_resource_priority

enum mln_resource_priority : uint32_t

The priority of a resource request.

Enumerator
MLN_RESOURCE_PRIORITY_REGULAR 
MLN_RESOURCE_PRIORITY_LOW 

◆ mln_resource_request_field

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 

◆ mln_resource_response_field

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 

◆ mln_resource_response_status

The outcome of a resource request.

Enumerator
MLN_RESOURCE_RESPONSE_STATUS_OK 
MLN_RESOURCE_RESPONSE_STATUS_ERROR 
MLN_RESOURCE_RESPONSE_STATUS_NO_CONTENT 

The resource exists and is empty.

MLN_RESOURCE_RESPONSE_STATUS_NOT_MODIFIED 

The earlier copy that the request's prior_ fields describe is current.

◆ mln_resource_storage_policy

enum mln_resource_storage_policy : uint32_t

Whether the library keeps a loaded resource in its cache.

Enumerator
MLN_RESOURCE_STORAGE_POLICY_PERMANENT 
MLN_RESOURCE_STORAGE_POLICY_VOLATILE 

◆ mln_resource_transform_error_field

The fields that mln_resource_transform_error sets.

Enumerator
MLN_RESOURCE_TRANSFORM_ERROR_RETRY_AFTER 

◆ mln_resource_usage

enum mln_resource_usage : uint32_t

Whether a request loads a resource for a map or an offline region.

Enumerator
MLN_RESOURCE_USAGE_ONLINE 
MLN_RESOURCE_USAGE_OFFLINE 

◆ mln_runtime_event_flag

enum mln_runtime_event_flag : uint64_t

An event type, as a bit in a set.

Enumerator
MLN_RUNTIME_EVENT_FLAG_NONE 
MLN_RUNTIME_EVENT_FLAG_MAP_CAMERA_WILL_CHANGE 
MLN_RUNTIME_EVENT_FLAG_MAP_CAMERA_IS_CHANGING 
MLN_RUNTIME_EVENT_FLAG_MAP_CAMERA_DID_CHANGE 
MLN_RUNTIME_EVENT_FLAG_MAP_STYLE_LOADED 
MLN_RUNTIME_EVENT_FLAG_MAP_LOADING_STARTED 
MLN_RUNTIME_EVENT_FLAG_MAP_LOADING_FINISHED 
MLN_RUNTIME_EVENT_FLAG_MAP_LOADING_FAILED 
MLN_RUNTIME_EVENT_FLAG_MAP_IDLE 
MLN_RUNTIME_EVENT_FLAG_MAP_RENDER_ERROR 
MLN_RUNTIME_EVENT_FLAG_MAP_RENDER_FRAME_STARTED 
MLN_RUNTIME_EVENT_FLAG_MAP_RENDER_FRAME_FINISHED 
MLN_RUNTIME_EVENT_FLAG_MAP_RENDER_MAP_STARTED 
MLN_RUNTIME_EVENT_FLAG_MAP_RENDER_MAP_FINISHED 
MLN_RUNTIME_EVENT_FLAG_MAP_STYLE_IMAGE_MISSING 
MLN_RUNTIME_EVENT_FLAG_MAP_TILE_ACTION 
MLN_RUNTIME_EVENT_FLAG_MAP_SOURCE_CHANGED 
MLN_RUNTIME_EVENT_FLAG_OFFLINE_REGION_STATUS_CHANGED 
MLN_RUNTIME_EVENT_FLAG_OFFLINE_REGION_RESPONSE_ERROR 
MLN_RUNTIME_EVENT_FLAG_OFFLINE_REGION_TILE_COUNT_LIMIT_EXCEEDED 
MLN_RUNTIME_EVENT_FLAG_MAP_GLYPHS_REQUESTED 
MLN_RUNTIME_EVENT_FLAG_MAP_GLYPHS_LOADED 
MLN_RUNTIME_EVENT_FLAG_MAP_GLYPHS_ERROR 
MLN_RUNTIME_EVENT_FLAG_MAP_SPRITE_REQUESTED 
MLN_RUNTIME_EVENT_FLAG_MAP_SPRITE_LOADED 
MLN_RUNTIME_EVENT_FLAG_MAP_SPRITE_ERROR 
MLN_RUNTIME_EVENT_FLAG_ALL_MAP_EVENTS 
MLN_RUNTIME_EVENT_FLAG_ALL_RUNTIME_EVENTS 
MLN_RUNTIME_EVENT_FLAG_ALL 

◆ mln_runtime_event_payload_type

The member of mln_runtime_event_payload that an event carries.

Enumerator
MLN_RUNTIME_EVENT_PAYLOAD_NONE 
MLN_RUNTIME_EVENT_PAYLOAD_CAMERA_CHANGE 
MLN_RUNTIME_EVENT_PAYLOAD_LOADING_FAILED 
MLN_RUNTIME_EVENT_PAYLOAD_RENDER_FRAME 
MLN_RUNTIME_EVENT_PAYLOAD_STYLE_IMAGE 
MLN_RUNTIME_EVENT_PAYLOAD_TILE_ACTION 
MLN_RUNTIME_EVENT_PAYLOAD_SOURCE_CHANGED 
MLN_RUNTIME_EVENT_PAYLOAD_OFFLINE_REGION_STATUS 
MLN_RUNTIME_EVENT_PAYLOAD_OFFLINE_REGION_RESPONSE_ERROR 
MLN_RUNTIME_EVENT_PAYLOAD_OFFLINE_REGION_TILE_COUNT_LIMIT 
MLN_RUNTIME_EVENT_PAYLOAD_GLYPHS 
MLN_RUNTIME_EVENT_PAYLOAD_SPRITE 

◆ mln_runtime_event_source_type

The kind of handle that raised an event.

Enumerator
MLN_RUNTIME_EVENT_SOURCE_RUNTIME 
MLN_RUNTIME_EVENT_SOURCE_MAP 

◆ mln_runtime_event_type

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.

Enumerator
MLN_RUNTIME_EVENT_MAP_CAMERA_WILL_CHANGE 
MLN_RUNTIME_EVENT_MAP_CAMERA_IS_CHANGING 
MLN_RUNTIME_EVENT_MAP_CAMERA_DID_CHANGE 
MLN_RUNTIME_EVENT_MAP_STYLE_LOADED 
MLN_RUNTIME_EVENT_MAP_LOADING_STARTED 

The map started to load a style.

MLN_RUNTIME_EVENT_MAP_LOADING_FINISHED 

The map loaded its style and everything that the current view needs, and rendered the result.

MLN_RUNTIME_EVENT_MAP_LOADING_FAILED 

The map failed to load a style.

MLN_RUNTIME_EVENT_MAP_IDLE 

The map rendered a complete frame and has nothing left to load, animate, or redraw.

MLN_RUNTIME_EVENT_MAP_RENDER_ERROR 
MLN_RUNTIME_EVENT_MAP_RENDER_FRAME_STARTED 
MLN_RUNTIME_EVENT_MAP_RENDER_FRAME_FINISHED 
MLN_RUNTIME_EVENT_MAP_RENDER_MAP_STARTED 
MLN_RUNTIME_EVENT_MAP_RENDER_MAP_FINISHED 
MLN_RUNTIME_EVENT_MAP_STYLE_IMAGE_MISSING 

The style uses an image that it doesn't have.

MLN_RUNTIME_EVENT_MAP_TILE_ACTION 

A tile moved to another step of loading.

MLN_RUNTIME_EVENT_MAP_SOURCE_CHANGED 

A source in the style changed, such as when its TileJSON loads.

MLN_RUNTIME_EVENT_OFFLINE_REGION_STATUS_CHANGED 
MLN_RUNTIME_EVENT_OFFLINE_REGION_RESPONSE_ERROR 

A resource that the region needs failed to download.

MLN_RUNTIME_EVENT_OFFLINE_REGION_TILE_COUNT_LIMIT_EXCEEDED 

The region's download became inactive because the cache file's offline regions hold as many tiles from MapLibre's demo tile server as the limit allows. Only tiles of sources with a maplibre:// URL count toward the limit.

MLN_RUNTIME_EVENT_MAP_GLYPHS_REQUESTED 
MLN_RUNTIME_EVENT_MAP_GLYPHS_LOADED 
MLN_RUNTIME_EVENT_MAP_GLYPHS_ERROR 
MLN_RUNTIME_EVENT_MAP_SPRITE_REQUESTED 
MLN_RUNTIME_EVENT_MAP_SPRITE_LOADED 
MLN_RUNTIME_EVENT_MAP_SPRITE_ERROR 

◆ mln_tile_operation

enum mln_tile_operation : uint32_t

A step in loading a tile.

Enumerator
MLN_TILE_OPERATION_REQUESTED_FROM_CACHE 
MLN_TILE_OPERATION_REQUESTED_FROM_NETWORK 
MLN_TILE_OPERATION_LOAD_FROM_NETWORK 
MLN_TILE_OPERATION_LOAD_FROM_CACHE 
MLN_TILE_OPERATION_START_PARSE 
MLN_TILE_OPERATION_END_PARSE 
MLN_TILE_OPERATION_ERROR 
MLN_TILE_OPERATION_CANCELLED 
MLN_TILE_OPERATION_NULL 

◆ mln_url_match_flag

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.

Function Documentation

◆ 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 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_network_get_status()

mln_status mln_network_get_status ( mln_network_status * out_status,
mln_diagnostic * out_diagnostic )

Reads whether the library may use the network.

◆ mln_network_set_status()

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_resource_request_complete()

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:

  • MLN_STATUS_INVALID_STATE when the library cancelled the request.

Lifetimes: The call ends handle whatever it returns.

◆ mln_resource_request_is_cancelled()

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_resource_request_pass_through()

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:

  • MLN_STATUS_INVALID_STATE when the library cancelled the request.

Lifetimes: The call ends handle whatever it returns.

◆ mln_resource_request_release()

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_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 )

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_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 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_resource_transform_request_fail()

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.

◆ mln_resource_transform_request_release()

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_runtime_clear_event_handler()

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_runtime_clear_http_header_transform()

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_runtime_clear_resource_provider()

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_runtime_clear_resource_transform()

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_runtime_create()

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_INVALID_ARGUMENT when the cache database file that options names can't be opened or created.

◆ mln_runtime_dispose()

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_runtime_release()

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_runtime_run_cache_database_operation()

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_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 )

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

The callback replaces the one set before.

◆ 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 )

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_UNSUPPORTED when the library runs in a browser or on OpenHarmony.

◆ 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 )

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_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 )

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_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 )

Rewrites the URLs of the runtime's network requests.

The transform replaces the one set before.