map.h File Reference

Go to the source code of this file.

Data Structures
struct	mln_map_options
struct	mln_screen_point
struct	mln_edge_insets
struct	mln_camera_options
struct	mln_unit_bezier
struct	mln_animation_options
struct	mln_camera_fit_options
struct	mln_vec3
struct	mln_quaternion
struct	mln_free_camera_options
struct	mln_lat_lng
struct	mln_string_view
struct	mln_coordinate_span
struct	mln_polygon_geometry
struct	mln_multi_line_geometry
struct	mln_multi_polygon_geometry
struct	mln_geometry_collection
struct	mln_geometry
struct	mln_json_array
struct	mln_json_member
struct	mln_json_object
struct	mln_json_value
struct	mln_feature_state_selector
struct	mln_feature
struct	mln_feature_collection
struct	mln_geojson
struct	mln_lat_lng_bounds
struct	mln_bound_options
struct	mln_offline_tile_pyramid_region_definition
struct	mln_offline_geometry_region_definition
struct	mln_offline_region_definition
struct	mln_offline_region_info
struct	mln_projected_meters
struct	mln_projection_mode
struct	mln_map_viewport_options
struct	mln_map_tile_options

Enumerations
enum	mln_camera_option_field : uint32_t
enum	mln_animation_option_field : uint32_t
enum	mln_camera_fit_option_field : uint32_t
enum	mln_bound_option_field : uint32_t
enum	mln_free_camera_option_field : uint32_t
enum	mln_projection_mode_field : uint32_t
enum	mln_map_debug_option : uint32_t
enum	mln_north_orientation : uint32_t
enum	mln_constrain_mode : uint32_t
enum	mln_viewport_mode : uint32_t
enum	mln_map_viewport_option_field : uint32_t
enum	mln_tile_lod_mode : uint32_t
enum	mln_map_tile_option_field : uint32_t
enum	mln_map_mode : uint32_t { MLN_MAP_MODE_CONTINUOUS = 0 , MLN_MAP_MODE_STATIC = 1 , MLN_MAP_MODE_TILE = 2 }
enum	mln_geometry_type : uint32_t
enum	mln_json_value_type : uint32_t
enum	mln_feature_state_selector_field : uint32_t
enum	mln_feature_identifier_type : uint32_t
enum	mln_geojson_type : uint32_t

Functions
mln_status	mln_runtime_offline_region_create_start (mln_runtime *runtime, const mln_offline_region_definition *definition, const uint8_t *metadata, size_t metadata_size, mln_offline_operation_id *out_operation_id)
mln_status	mln_runtime_offline_region_get_start (mln_runtime *runtime, mln_offline_region_id region_id, mln_offline_operation_id *out_operation_id)
mln_status	mln_runtime_offline_regions_list_start (mln_runtime *runtime, mln_offline_operation_id *out_operation_id)
mln_status	mln_runtime_offline_regions_merge_database_start (mln_runtime *runtime, const char *side_database_path, mln_offline_operation_id *out_operation_id)
mln_status	mln_runtime_offline_region_update_metadata_start (mln_runtime *runtime, mln_offline_region_id region_id, const uint8_t *metadata, size_t metadata_size, mln_offline_operation_id *out_operation_id)
mln_status	mln_runtime_offline_region_get_status_start (mln_runtime *runtime, mln_offline_region_id region_id, mln_offline_operation_id *out_operation_id)
mln_status	mln_runtime_offline_region_set_observed_start (mln_runtime *runtime, mln_offline_region_id region_id, bool observed, mln_offline_operation_id *out_operation_id)
mln_status	mln_runtime_offline_region_set_download_state_start (mln_runtime *runtime, mln_offline_region_id region_id, uint32_t state, mln_offline_operation_id *out_operation_id)
mln_status	mln_runtime_offline_region_invalidate_start (mln_runtime *runtime, mln_offline_region_id region_id, mln_offline_operation_id *out_operation_id)
mln_status	mln_runtime_offline_region_delete_start (mln_runtime *runtime, mln_offline_region_id region_id, mln_offline_operation_id *out_operation_id)
mln_status	mln_runtime_offline_region_create_take_result (mln_runtime *runtime, mln_offline_operation_id operation_id, mln_offline_region_snapshot **out_region)
mln_status	mln_runtime_offline_region_get_take_result (mln_runtime *runtime, mln_offline_operation_id operation_id, mln_offline_region_snapshot **out_region, bool *out_found)
mln_status	mln_runtime_offline_regions_list_take_result (mln_runtime *runtime, mln_offline_operation_id operation_id, mln_offline_region_list **out_regions)
mln_status	mln_runtime_offline_regions_merge_database_take_result (mln_runtime *runtime, mln_offline_operation_id operation_id, mln_offline_region_list **out_regions)
mln_status	mln_runtime_offline_region_update_metadata_take_result (mln_runtime *runtime, mln_offline_operation_id operation_id, mln_offline_region_snapshot **out_region)
mln_status	mln_runtime_offline_region_get_status_take_result (mln_runtime *runtime, mln_offline_operation_id operation_id, mln_offline_region_status *out_status)
mln_status	mln_offline_region_snapshot_get (const mln_offline_region_snapshot *snapshot, mln_offline_region_info *out_info)
void	mln_offline_region_snapshot_destroy (mln_offline_region_snapshot *snapshot)
mln_status	mln_offline_region_list_count (const mln_offline_region_list *list, size_t *out_count)
mln_status	mln_offline_region_list_get (const mln_offline_region_list *list, size_t index, mln_offline_region_info *out_info)
void	mln_offline_region_list_destroy (mln_offline_region_list *list)
mln_map_options	mln_map_options_default (void)
mln_status	mln_map_create (mln_runtime *runtime, const mln_map_options *options, mln_map **out_map)
mln_status	mln_map_request_repaint (mln_map *map)
mln_status	mln_map_request_still_image (mln_map *map)
mln_status	mln_map_destroy (mln_map *map)
mln_status	mln_map_set_style_url (mln_map *map, const char *url)
mln_status	mln_map_set_style_json (mln_map *map, const char *json)

Detailed Description

Public C API declarations for map lifecycle, shared types, and offline regions.

Enumeration Type Documentation

mln_animation_option_field

enum mln_animation_option_field : uint32_t

Field mask values for mln_animation_options.

mln_bound_option_field

enum mln_bound_option_field : uint32_t

Field mask values for mln_bound_options.

mln_camera_fit_option_field

enum mln_camera_fit_option_field : uint32_t

Field mask values for mln_camera_fit_options.

mln_camera_option_field

enum mln_camera_option_field : uint32_t

Field mask values for mln_camera_options.

mln_constrain_mode

enum mln_constrain_mode : uint32_t

Map constraint modes used by mln_map_viewport_options.

mln_feature_identifier_type

enum mln_feature_identifier_type : uint32_t

Feature identifier variant tags used by mln_feature.

mln_feature_state_selector_field

enum mln_feature_state_selector_field : uint32_t

Optional fields for mln_feature_state_selector.

mln_free_camera_option_field

enum mln_free_camera_option_field : uint32_t

Field mask values for mln_free_camera_options.

mln_geojson_type

enum mln_geojson_type : uint32_t

GeoJSON variant tags used by mln_geojson.

mln_geometry_type

enum mln_geometry_type : uint32_t

Geometry variant tags used by mln_geometry.

mln_json_value_type

enum mln_json_value_type : uint32_t

JSON-like value variant tags used by mln_json_value.

mln_map_debug_option

enum mln_map_debug_option : uint32_t

Debug overlay mask values for mln_map_set_debug_options().

mln_map_mode

enum mln_map_mode : uint32_t

Map rendering modes used when creating a map.

Enumerator
MLN_MAP_MODE_CONTINUOUS	Continuously updates as data arrives and map state changes.
MLN_MAP_MODE_STATIC	Produces one-off still images of an arbitrary viewport.
MLN_MAP_MODE_TILE	Produces one-off still images for a single tile.

mln_map_tile_option_field

enum mln_map_tile_option_field : uint32_t

Field mask values for mln_map_tile_options.

mln_map_viewport_option_field

enum mln_map_viewport_option_field : uint32_t

Field mask values for mln_map_viewport_options.

mln_north_orientation

enum mln_north_orientation : uint32_t

Map north orientation values used by mln_map_viewport_options.

mln_projection_mode_field

enum mln_projection_mode_field : uint32_t

Field mask values for MapLibre axonometric rendering options.

mln_tile_lod_mode

enum mln_tile_lod_mode : uint32_t

Tile LOD algorithms used by mln_map_tile_options.

mln_viewport_mode

enum mln_viewport_mode : uint32_t

Viewport orientation modes used by mln_map_viewport_options.

Function Documentation

mln_map_create()

mln_status mln_map_create	(	mln_runtime *	runtime,
		const mln_map_options *	options,
		mln_map **	out_map )

Creates a map handle on the runtime owner thread.

On success, the runtime owner thread becomes the map owner thread.

Returns:

• MLN_STATUS_OK on success.
• MLN_STATUS_INVALID_ARGUMENT when runtime is null or not live, out_map is null, *out_map is not null, or options are invalid.
• 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_map_destroy()

mln_status mln_map_destroy

(

mln_map *

map

)

Destroys a map handle on its owner thread.

The map must not have an attached render session.

Returns:

• MLN_STATUS_OK on success.
• MLN_STATUS_INVALID_ARGUMENT when map is null or not a live map handle.
• MLN_STATUS_INVALID_STATE when map still has an attached render target session.
• MLN_STATUS_WRONG_THREAD when called from a thread other than the map owner thread.
• MLN_STATUS_NATIVE_ERROR when an internal exception is converted to status.

mln_map_options_default()

mln_map_options mln_map_options_default

(

void

)

Returns map options initialized for this C API version.

mln_map_request_repaint()

mln_status mln_map_request_repaint

(

mln_map *

map

)

Requests a repaint for a continuous map.

Continuous maps also invalidate automatically when style data, resources, camera, or transitions change. Ask attached render targets to process the latest update when MLN_RUNTIME_EVENT_MAP_RENDER_UPDATE_AVAILABLE is reported. Repaint requests do not produce MLN_RUNTIME_EVENT_MAP_STILL_IMAGE_FINISHED or MLN_RUNTIME_EVENT_MAP_STILL_IMAGE_FAILED events.

Returns:

• MLN_STATUS_OK when the request was accepted.
• MLN_STATUS_INVALID_ARGUMENT when map is null or not live.
• MLN_STATUS_INVALID_STATE when map is not in MLN_MAP_MODE_CONTINUOUS.
• MLN_STATUS_WRONG_THREAD when called from a thread other than the map owner thread.
• MLN_STATUS_NATIVE_ERROR when an internal exception is converted to status.

mln_map_request_still_image()

mln_status mln_map_request_still_image

(

mln_map *

map

)

Requests one still image for a static or tile map.

Pump the runtime and poll runtime events for this map until MLN_RUNTIME_EVENT_MAP_STILL_IMAGE_FINISHED or MLN_RUNTIME_EVENT_MAP_STILL_IMAGE_FAILED is reported. While the request is pending, process each MLN_RUNTIME_EVENT_MAP_RENDER_UPDATE_AVAILABLE event from this map. Render targets use mln_render_session_render_update(). Surface targets present directly. A render-update call can return MLN_STATUS_INVALID_STATE before the next update is available; keep pumping and polling in that case. After MLN_RUNTIME_EVENT_MAP_STILL_IMAGE_FINISHED, use the latest successful texture update when the host needs image bytes or a backend texture.

Returns:

• MLN_STATUS_OK when the request was accepted.
• MLN_STATUS_INVALID_ARGUMENT when map is null or not live.
• MLN_STATUS_INVALID_STATE when map is not in MLN_MAP_MODE_STATIC or MLN_MAP_MODE_TILE, or when a still-image request is already pending.
• MLN_STATUS_WRONG_THREAD when called from a thread other than the map owner thread.
• MLN_STATUS_NATIVE_ERROR when an internal exception is converted to status.

mln_map_set_style_json()

mln_status mln_map_set_style_json	(	mln_map *	map,
		const char *	json )

Loads inline style JSON through MapLibre Native style APIs.

This is a map command. The return status reports synchronous acceptance or failure. Later native success and failure are reported through runtime events. Malformed JSON can fail synchronously and still enqueue a loading-failed event.

Returns:

• MLN_STATUS_OK when the load request was accepted.
• MLN_STATUS_INVALID_ARGUMENT when map is null, not live, or json is null.
• MLN_STATUS_WRONG_THREAD when called from a thread other than the map owner thread.
• MLN_STATUS_NATIVE_ERROR when a synchronous native error is reported or an internal exception is converted to status.

mln_map_set_style_url()

mln_status mln_map_set_style_url	(	mln_map *	map,
		const char *	url )

Loads a style URL through MapLibre Native style APIs.

This is a map command. The return status reports synchronous acceptance or failure. Later native success and failure are reported through runtime events.

Returns:

• MLN_STATUS_OK when the load request was accepted.
• MLN_STATUS_INVALID_ARGUMENT when map is null, not live, or url is null.
• MLN_STATUS_WRONG_THREAD when called from a thread other than the map owner thread.
• MLN_STATUS_NATIVE_ERROR when a synchronous native error is reported or an internal exception is converted to status.

mln_offline_region_list_count()

mln_status mln_offline_region_list_count	(	const mln_offline_region_list *	list,
		size_t *	out_count )

Gets the number of regions in a list handle.

Returns:

• MLN_STATUS_OK on success.
• MLN_STATUS_INVALID_ARGUMENT when list is null or not live, or out_count is null.
• MLN_STATUS_NATIVE_ERROR when an internal exception is converted to status.

mln_offline_region_list_destroy()

void mln_offline_region_list_destroy

(

mln_offline_region_list *

list

)

Destroys an offline region list handle. Null is accepted as a no-op.

mln_offline_region_list_get()

mln_status mln_offline_region_list_get	(	const mln_offline_region_list *	list,
		size_t	index,
		mln_offline_region_info *	out_info )

Copies a region data view for one list entry.

On success, out_info receives pointers into list-owned storage. Those pointers remain valid until the list is destroyed.

Returns:

• MLN_STATUS_OK on success.
• MLN_STATUS_INVALID_ARGUMENT when list is null or not live, index is out of range, out_info is null, or out_info->size is too small.
• MLN_STATUS_NATIVE_ERROR when an internal exception is converted to status.

mln_offline_region_snapshot_destroy()

void mln_offline_region_snapshot_destroy

(

mln_offline_region_snapshot *

snapshot

)

Destroys an offline region snapshot handle. Null is accepted as a no-op.

mln_offline_region_snapshot_get()

mln_status mln_offline_region_snapshot_get	(	const mln_offline_region_snapshot *	snapshot,
		mln_offline_region_info *	out_info )

Copies a region data view out of a snapshot handle.

On success, out_info receives pointers into snapshot-owned storage. Those pointers remain valid until the snapshot is destroyed.

Returns:

• MLN_STATUS_OK on success.
• MLN_STATUS_INVALID_ARGUMENT when snapshot is null or not live, out_info is null, or out_info->size is too small.
• MLN_STATUS_NATIVE_ERROR when an internal exception is converted to status.

mln_runtime_offline_region_create_start()

mln_status mln_runtime_offline_region_create_start	(	mln_runtime *	runtime,
		const mln_offline_region_definition *	definition,
		const uint8_t *	metadata,
		size_t	metadata_size,
		mln_offline_operation_id *	out_operation_id )

Starts creating an offline region.

Input strings, geometry descriptors, and metadata are copied before this call returns. Completion is reported through MLN_RUNTIME_EVENT_OFFLINE_OPERATION_COMPLETED. On successful completion, call mln_runtime_offline_region_create_take_result() to take the snapshot.

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, definition is null or invalid, metadata is null with a non-zero size, 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_offline_region_create_take_result()

mln_status mln_runtime_offline_region_create_take_result	(	mln_runtime *	runtime,
		mln_offline_operation_id	operation_id,
		mln_offline_region_snapshot **	out_region )

Takes the snapshot result from a completed offline region create operation.

Must only be called after the matching mln_runtime_offline_region_create_start() operation has completed successfully (MLN_RUNTIME_EVENT_OFFLINE_OPERATION_COMPLETED with result status MLN_STATUS_OK). The caller owns the returned snapshot handle and must destroy it with mln_offline_region_snapshot_destroy().

On success, the operation entry is consumed. On failure, it remains live so the caller may retry this call or discard the operation with mln_runtime_offline_operation_discard().

Returns:

• MLN_STATUS_OK when the result was taken and out_region was set.
• MLN_STATUS_INVALID_STATE when the operation has not completed or its result kind does not match a region snapshot.
• MLN_STATUS_INVALID_ARGUMENT when runtime is null or not live, or out_region is null.

mln_runtime_offline_region_delete_start()

mln_status mln_runtime_offline_region_delete_start	(	mln_runtime *	runtime,
		mln_offline_region_id	region_id,
		mln_offline_operation_id *	out_operation_id )

Deletes an offline region.

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

mln_status mln_runtime_offline_region_get_start	(	mln_runtime *	runtime,
		mln_offline_region_id	region_id,
		mln_offline_operation_id *	out_operation_id )

Starts getting an offline region snapshot by ID.

Completion is reported through MLN_RUNTIME_EVENT_OFFLINE_OPERATION_COMPLETED. On successful completion, call mln_runtime_offline_region_get_take_result().

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

mln_status mln_runtime_offline_region_get_status_start	(	mln_runtime *	runtime,
		mln_offline_region_id	region_id,
		mln_offline_operation_id *	out_operation_id )

Starts getting the current completed/download status for an offline region.

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

mln_status mln_runtime_offline_region_get_status_take_result	(	mln_runtime *	runtime,
		mln_offline_operation_id	operation_id,
		mln_offline_region_status *	out_status )

Takes the status struct from a completed offline region get-status operation.

Must only be called after the matching mln_runtime_offline_region_get_status_start() operation has completed successfully. The caller provides a pre-allocated mln_offline_region_status struct which is filled by this function.

On success, the operation entry is consumed. On failure, it remains live so the caller may retry this call or discard the operation with mln_runtime_offline_operation_discard().

Returns:

• MLN_STATUS_OK when the result was taken and out_status was filled.
• MLN_STATUS_INVALID_STATE when the operation has not completed or its result kind does not match a region status.
• MLN_STATUS_INVALID_ARGUMENT when runtime is null or not live, or out_status is null.

mln_runtime_offline_region_get_take_result()

mln_status mln_runtime_offline_region_get_take_result	(	mln_runtime *	runtime,
		mln_offline_operation_id	operation_id,
		mln_offline_region_snapshot **	out_region,
		bool *	out_found )

Takes the snapshot result from a completed offline region get operation.

Must only be called after the matching mln_runtime_offline_region_get_start() operation has completed successfully. The caller owns the returned snapshot handle and must destroy it with mln_offline_region_snapshot_destroy().

On success, the operation entry is consumed. On failure, it remains live so the caller may retry this call or discard the operation with mln_runtime_offline_operation_discard().

Returns:

• MLN_STATUS_OK when the result was taken; out_found indicates whether a region existed for the requested ID.
• MLN_STATUS_INVALID_STATE when the operation has not completed or its result kind does not match an optional region snapshot.
• MLN_STATUS_INVALID_ARGUMENT when runtime is null or not live, out_region is null, or out_found is null.

mln_runtime_offline_region_invalidate_start()

mln_status mln_runtime_offline_region_invalidate_start	(	mln_runtime *	runtime,
		mln_offline_region_id	region_id,
		mln_offline_operation_id *	out_operation_id )

Invalidates cached resources for an offline region.

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

mln_status mln_runtime_offline_region_set_download_state_start	(	mln_runtime *	runtime,
		mln_offline_region_id	region_id,
		uint32_t	state,
		mln_offline_operation_id *	out_operation_id )

Sets an offline region's native download state.

Register observation separately with mln_runtime_offline_region_set_observed_start() to receive progress and error events.

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, state is not a mln_offline_region_download_state 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_offline_region_set_observed_start()

mln_status mln_runtime_offline_region_set_observed_start	(	mln_runtime *	runtime,
		mln_offline_region_id	region_id,
		bool	observed,
		mln_offline_operation_id *	out_operation_id )

Enables or disables runtime events for an offline region.

Observer callbacks are copied into runtime events. Disabling observation also discards queued events for this region.

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

mln_status mln_runtime_offline_region_update_metadata_start	(	mln_runtime *	runtime,
		mln_offline_region_id	region_id,
		const uint8_t *	metadata,
		size_t	metadata_size,
		mln_offline_operation_id *	out_operation_id )

Starts updating opaque binary metadata for an offline region.

On successful completion, call mln_runtime_offline_region_update_metadata_take_result().

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, metadata is null with a non-zero size, 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_offline_region_update_metadata_take_result()

mln_status mln_runtime_offline_region_update_metadata_take_result	(	mln_runtime *	runtime,
		mln_offline_operation_id	operation_id,
		mln_offline_region_snapshot **	out_region )

Takes the snapshot result from a completed offline region update-metadata operation.

Must only be called after the matching mln_runtime_offline_region_update_metadata_start() operation has completed successfully. The caller owns the returned snapshot handle and must destroy it with mln_offline_region_snapshot_destroy().

On success, the operation entry is consumed. On failure, it remains live so the caller may retry this call or discard the operation with mln_runtime_offline_operation_discard().

Returns:

• MLN_STATUS_OK when the result was taken and out_region was set.
• MLN_STATUS_INVALID_STATE when the operation has not completed or its result kind does not match a region snapshot.
• MLN_STATUS_INVALID_ARGUMENT when runtime is null or not live, or out_region is null.

mln_runtime_offline_regions_list_start()

mln_status mln_runtime_offline_regions_list_start	(	mln_runtime *	runtime,
		mln_offline_operation_id *	out_operation_id )

Starts listing offline region snapshots in the runtime database.

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

mln_status mln_runtime_offline_regions_list_take_result	(	mln_runtime *	runtime,
		mln_offline_operation_id	operation_id,
		mln_offline_region_list **	out_regions )

Takes the region list from a completed offline regions list operation.

Must only be called after the matching mln_runtime_offline_regions_list_start() operation has completed successfully. The caller owns the returned list handle and must destroy it with mln_offline_region_list_destroy().

On success, the operation entry is consumed. On failure, it remains live so the caller may retry this call or discard the operation with mln_runtime_offline_operation_discard().

Returns:

• MLN_STATUS_OK when the result was taken and out_regions was set.
• MLN_STATUS_INVALID_STATE when the operation has not completed or its result kind does not match a region list.
• MLN_STATUS_INVALID_ARGUMENT when runtime is null or not live, or out_regions is null.

mln_runtime_offline_regions_merge_database_start()

mln_status mln_runtime_offline_regions_merge_database_start	(	mln_runtime *	runtime,
		const char *	side_database_path,
		mln_offline_operation_id *	out_operation_id )

Starts merging offline regions from another database path.

The side database may be upgraded in place by native code and must be writable when native merge requires it.

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, side_database_path is null, 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_offline_regions_merge_database_take_result()

mln_status mln_runtime_offline_regions_merge_database_take_result	(	mln_runtime *	runtime,
		mln_offline_operation_id	operation_id,
		mln_offline_region_list **	out_regions )

Takes the region list from a completed offline database merge operation.

Must only be called after the matching mln_runtime_offline_regions_merge_database_start() operation has completed successfully. The caller owns the returned list handle and must destroy it with mln_offline_region_list_destroy().

On success, the operation entry is consumed. On failure, it remains live so the caller may retry this call or discard the operation with mln_runtime_offline_operation_discard().

Returns:

• MLN_STATUS_OK when the result was taken and out_regions was set.
• MLN_STATUS_INVALID_STATE when the operation has not completed or its result kind does not match a region list.
• MLN_STATUS_INVALID_ARGUMENT when runtime is null or not live, or out_regions is null.