callback_adapter.h File Reference

Go to the source code of this file.

Data Structures
struct	mln_adapter_resource_rewrite_rule
struct	mln_adapter_resource_rewrite_rules
struct	mln_adapter_http_header
struct	mln_adapter_http_header_transform_rule
struct	mln_adapter_http_header_transform_rules
struct	mln_adapter_resource_provider_rule
struct	mln_adapter_resource_provider_rules
struct	mln_adapter_queued_resource_provider_route
struct	mln_adapter_queued_resource_provider
struct	mln_adapter_queued_resource_request
struct	mln_adapter_log_callback_state
struct	mln_adapter_log_record

Macros
#define	MLN_ADAPTER_RESOURCE_KIND_ANY   UINT32_MAX

Typedefs
typedef enum mln_adapter_url_match_flags	mln_adapter_url_match_flags
typedef struct mln_adapter_resource_rewrite_rule	mln_adapter_resource_rewrite_rule
typedef struct mln_adapter_resource_rewrite_rules	mln_adapter_resource_rewrite_rules
typedef struct mln_adapter_http_header	mln_adapter_http_header
typedef struct mln_adapter_http_header_transform_rule	mln_adapter_http_header_transform_rule
typedef struct mln_adapter_http_header_transform_rules	mln_adapter_http_header_transform_rules
typedef struct mln_adapter_resource_provider_rule	mln_adapter_resource_provider_rule
typedef struct mln_adapter_resource_provider_rules	mln_adapter_resource_provider_rules
typedef enum mln_adapter_resource_route_flags	mln_adapter_resource_route_flags
typedef struct mln_adapter_queued_resource_provider_route	mln_adapter_queued_resource_provider_route
typedef void(*	mln_adapter_queued_resource_request_listener) (void *request)
typedef struct mln_adapter_queued_resource_provider	mln_adapter_queued_resource_provider
typedef struct mln_adapter_queued_resource_request	mln_adapter_queued_resource_request
typedef void(*	mln_adapter_log_record_listener) (void *record)
typedef struct mln_adapter_log_callback_state	mln_adapter_log_callback_state
typedef struct mln_adapter_log_record	mln_adapter_log_record

Enumerations
enum	mln_adapter_url_match_flags : uint32_t
enum	mln_adapter_resource_route_flags : uint32_t

Functions
void *	mln_adapter_handle_leak_token_create (const char *type_name, uint64_t handle)
void	mln_adapter_handle_leak_token_destroy (void *token)
void	mln_adapter_handle_leak_report (void *token)
uint32_t	mln_adapter_log_callback (void *user_data, uint32_t severity, uint32_t event, int64_t code, const char *message)
mln_status	mln_adapter_log_set_callback (mln_adapter_log_callback_state *state)
void	mln_adapter_log_record_destroy (void *record)
mln_status	mln_adapter_resource_transform_rewrite_callback (void *user_data, uint32_t kind, const char *url, mln_resource_transform_response *out_response)
mln_status	mln_adapter_http_header_transform_callback (void *user_data, uint32_t kind, const char *url, mln_http_header_transform_response *out_response)
mln_status	mln_adapter_http_header_validate (const char *name, const char *value)
uint32_t	mln_adapter_resource_provider_rules_callback (void *user_data, const mln_resource_request *request, mln_resource_request_handle handle)
uint32_t	mln_adapter_queued_resource_provider_callback (void *user_data, const mln_resource_request *request, mln_resource_request_handle handle)
void	mln_adapter_resource_provider_request_destroy (void *request)
void	mln_adapter_queued_resource_provider_retire (mln_adapter_queued_resource_provider *provider)
void	mln_adapter_custom_geometry_callbacks_retire (mln_custom_geometry_source_tile_callback fetch_tile, mln_custom_geometry_source_tile_callback cancel_tile, void *user_data)
void	mln_adapter_custom_mvt_vector_callbacks_retire (mln_custom_mvt_vector_source_tile_callback fetch_tile, mln_custom_mvt_vector_source_tile_callback cancel_tile, void *user_data)

Detailed Description

Public C API declarations for adapting native callbacks to host runtimes that cannot run user code on a native callback thread.

MapLibre callback contracts are synchronous: logging and resource providers return an immediate decision, and borrowed request payloads expire when the callback returns. This layer answers on behalf of hosts that cannot. It copies borrowed payloads into native-owned records the host releases explicitly, applies native-owned routing rules when a decision is needed immediately, and hands records to the host through void listener functions, so host user code runs on its own execution context rather than on MapLibre worker, network, logging, or render threads.

This header is not part of the maplibre_native_c.h umbrella. Include it directly when a binding needs it.

This header targets C23.

Macro Definition Documentation

MLN_ADAPTER_RESOURCE_KIND_ANY

#define MLN_ADAPTER_RESOURCE_KIND_ANY   UINT32_MAX

Rule kind that matches every resource kind.

Typedef Documentation

mln_adapter_http_header

typedef struct mln_adapter_http_header mln_adapter_http_header

One borrowed header supplied by an HTTP header transform rule.

mln_adapter_http_header_transform_rule

typedef struct mln_adapter_http_header_transform_rule mln_adapter_http_header_transform_rule

One native-owned matching rule for an HTTP header transform.

kind is one mln_resource_kind value or MLN_ADAPTER_RESOURCE_KIND_ANY. The flags field is a bitwise OR of mln_adapter_url_match_flags values choosing how url compares against the complete transformed URL. A null url or an unknown flag bit makes the rule match nothing.

The first matching rule supplies its complete header list. Every pointer is borrowed and must outlive the registration.

mln_adapter_http_header_transform_rules

typedef struct mln_adapter_http_header_transform_rules mln_adapter_http_header_transform_rules

A borrowed table of HTTP header transform rules.

mln_adapter_log_callback_state

typedef struct mln_adapter_log_callback_state mln_adapter_log_callback_state

Registration state for an adapted log callback.

The consume field is the value reported to MapLibre for every dispatched record. The address of this struct identifies the registration; it is borrowed and must stay valid until the callback is replaced or cleared.

mln_adapter_log_record

typedef struct mln_adapter_log_record mln_adapter_log_record

A native-owned copy of a log record.

The message pointer is owned by this record and stays valid until mln_adapter_log_record_destroy().

mln_adapter_log_record_listener

typedef void(* mln_adapter_log_record_listener) (void *record)

Receives a log record as a native-owned mln_adapter_log_record, or null when the callback retires.

The listener returns void and may be invoked from any MapLibre logging or worker thread. It takes ownership of the record and releases it with mln_adapter_log_record_destroy() once the host has read it.

mln_adapter_queued_resource_provider

typedef struct mln_adapter_queued_resource_provider mln_adapter_queued_resource_provider

A provider that hands matching requests to a host listener.

The routes pointer is borrowed and must stay valid while the provider is registered.

mln_adapter_queued_resource_provider_route

typedef struct mln_adapter_queued_resource_provider_route mln_adapter_queued_resource_provider_route

One route a queued provider claims.

The kind field matches mln_resource_kind values, or MLN_ADAPTER_RESOURCE_KIND_ANY for every kind. The flags field is a bitwise OR of mln_adapter_resource_route_flags values choosing which URL the route compares and how; with no flags the route matches mln_resource_request.resolved_url exactly.

The url field is a comparison value, read literally or as a glob pattern according to flags. A null url or an unknown flag bit makes the route match nothing. The url pointer is borrowed and must outlive the provider.

mln_adapter_queued_resource_request

typedef struct mln_adapter_queued_resource_request mln_adapter_queued_resource_request

A native-owned copy of a resource request.

Every pointer field is owned by this record and stays valid until mln_adapter_resource_provider_request_destroy(). The handle field carries the request handle the host completes; it is an ordinary handle value the host moves between execution contexts and passes to mln_resource_request_*().

mln_adapter_queued_resource_request_listener

typedef void(* mln_adapter_queued_resource_request_listener) (void *request)

Receives a queued request as a native-owned mln_adapter_queued_resource_request, or null when the provider retires.

The listener returns void and may be invoked from any MapLibre thread. It takes ownership of the record and releases it with mln_adapter_resource_provider_request_destroy() once the host has read it.

mln_adapter_resource_provider_rule

typedef struct mln_adapter_resource_provider_rule mln_adapter_resource_provider_rule

One resource provider rule.

The kind field matches mln_resource_kind values, or MLN_ADAPTER_RESOURCE_KIND_ANY for every kind. The flags field is a bitwise OR of mln_adapter_url_match_flags values choosing how requested_url compares against mln_resource_request.requested_url. A null requested_url or an unknown flag bit makes the rule match nothing.

A matching request is completed with the rule's response without reaching the host. The response and its buffers are borrowed and must outlive the rule table.

mln_adapter_resource_provider_rules

typedef struct mln_adapter_resource_provider_rules mln_adapter_resource_provider_rules

A borrowed table of provider rules.

The rules pointer is borrowed and must stay valid while the table is registered as resource provider user data.

mln_adapter_resource_rewrite_rule

typedef struct mln_adapter_resource_rewrite_rule mln_adapter_resource_rewrite_rule

One resource rewrite rule.

The kind field matches mln_resource_kind values, or MLN_ADAPTER_RESOURCE_KIND_ANY for every kind. The flags field is a bitwise OR of mln_adapter_url_match_flags values choosing how url compares against the request URL. A null url or an unknown flag bit makes the rule match nothing.

A null replacement_url leaves the URL unchanged. Both strings are borrowed and must outlive the rule table.

mln_adapter_resource_rewrite_rules

typedef struct mln_adapter_resource_rewrite_rules mln_adapter_resource_rewrite_rules

A borrowed table of rewrite rules.

The rules pointer is borrowed and must stay valid while the table is registered as resource transform user data.

mln_adapter_resource_route_flags

typedef enum mln_adapter_resource_route_flags mln_adapter_resource_route_flags

How a queued provider route compares its url against a request.

MLN_ADAPTER_RESOURCE_ROUTE_MATCH_GLOB reads the url as a glob pattern, in the language mln_adapter_url_match_flags describes. MLN_ADAPTER_RESOURCE_ROUTE_USE_REQUESTED_URL selects mln_resource_request.requested_url as the compared URL instead of mln_resource_request.resolved_url. Setting both matches a requested-URL glob.

mln_adapter_url_match_flags

typedef enum mln_adapter_url_match_flags mln_adapter_url_match_flags

How a rule compares its url against a request URL.

With no flags, a rule compares the complete URL byte for byte. MLN_ADAPTER_URL_MATCH_GLOB reads the url as a glob pattern instead:

• * matches a run of any length that contains no /, including an empty run.
• ** matches a run of any length, including one that contains /.
• ? matches one character other than /.
• \ matches the next character literally, and a trailing \ matches itself.

Every other byte compares literally. A pattern matches the complete URL, so a pattern that describes a suffix opens with a wildcard. Comparison is case-sensitive either way, and applies no URL parsing or normalization.

Confining * to one path segment is what makes a host pattern hold: https://*.example.com/** matches every subdomain of example.com and never https://attacker.example/x.example.com/tile. Use ** wherever a pattern spans path segments, as in https://tiles.example.com/** for one host.

Enumeration Type Documentation

mln_adapter_resource_route_flags

enum mln_adapter_resource_route_flags : uint32_t

How a queued provider route compares its url against a request.

MLN_ADAPTER_RESOURCE_ROUTE_MATCH_GLOB reads the url as a glob pattern, in the language mln_adapter_url_match_flags describes. MLN_ADAPTER_RESOURCE_ROUTE_USE_REQUESTED_URL selects mln_resource_request.requested_url as the compared URL instead of mln_resource_request.resolved_url. Setting both matches a requested-URL glob.

mln_adapter_url_match_flags

enum mln_adapter_url_match_flags : uint32_t

How a rule compares its url against a request URL.

With no flags, a rule compares the complete URL byte for byte. MLN_ADAPTER_URL_MATCH_GLOB reads the url as a glob pattern instead:

• * matches a run of any length that contains no /, including an empty run.
• ** matches a run of any length, including one that contains /.
• ? matches one character other than /.
• \ matches the next character literally, and a trailing \ matches itself.

Every other byte compares literally. A pattern matches the complete URL, so a pattern that describes a suffix opens with a wildcard. Comparison is case-sensitive either way, and applies no URL parsing or normalization.

Confining * to one path segment is what makes a host pattern hold: https://*.example.com/** matches every subdomain of example.com and never https://attacker.example/x.example.com/tile. Use ** wherever a pattern spans path segments, as in https://tiles.example.com/** for one host.

Function Documentation

mln_adapter_custom_geometry_callbacks_retire()

void mln_adapter_custom_geometry_callbacks_retire	(	mln_custom_geometry_source_tile_callback	fetch_tile,
		mln_custom_geometry_source_tile_callback	cancel_tile,
		void *	user_data )

Invokes custom geometry tile callbacks once with a retirement tile id.

The retirement tile id uses z = UINT8_MAX, which no real tile uses, so a host listener recognizes it and releases the state behind the callbacks.

mln_adapter_custom_mvt_vector_callbacks_retire()

void mln_adapter_custom_mvt_vector_callbacks_retire	(	mln_custom_mvt_vector_source_tile_callback	fetch_tile,
		mln_custom_mvt_vector_source_tile_callback	cancel_tile,
		void *	user_data )

Invokes custom MVT vector tile callbacks once with a retirement tile id.

The retirement tile id uses z = UINT8_MAX, which no real tile uses, so a host listener recognizes it and releases the state behind the callbacks.

mln_adapter_handle_leak_report()

void mln_adapter_handle_leak_report

(

void *

token

)

Reports a leaked handle on stderr and releases the token.

mln_adapter_handle_leak_token_create()

void * mln_adapter_handle_leak_token_create	(	const char *	type_name,
		uint64_t	handle )

Creates a token describing a handle the host has not closed yet.

The token copies type_name and records handle so the report can name them. Hosts attach the token to a finalizer, which can no longer touch the handle itself.

Returns null when the token cannot be allocated.

mln_adapter_handle_leak_token_destroy()

void mln_adapter_handle_leak_token_destroy

(

void *

token

)

Releases a leak token without reporting it.

mln_adapter_http_header_transform_callback()

mln_status mln_adapter_http_header_transform_callback	(	void *	user_data,
		uint32_t	kind,
		const char *	url,
		mln_http_header_transform_response *	out_response )

The mln_http_header_transform_callback implementation for native rules.

The first rule whose kind and transformed URL match supplies all its headers. A request with no matching rule proceeds unchanged. The callback returns the first non-OK status from mln_http_header_transform_response_set().

mln_adapter_http_header_validate()

mln_status mln_adapter_http_header_validate	(	const char *	name,
		const char *	value )

Validates one null-terminated HTTP header from an adapter-owned rule table.

This applies the C API's field-name, UTF-8 field-value, control-byte, and transport-managed-name rules without requiring an active transform callback. A diagnostic for a rejected header never includes its value.

mln_adapter_log_callback()

uint32_t mln_adapter_log_callback	(	void *	user_data,
		uint32_t	severity,
		uint32_t	event,
		int64_t	code,
		const char *	message )

The mln_log_callback implementation this layer registers.

Copies the record, hands it to the registered listener, and reports the registration's fixed consume value. The user_data pointer is the mln_adapter_log_callback_state passed to mln_adapter_log_set_callback().

mln_adapter_log_record_destroy()

void mln_adapter_log_record_destroy

(

void *

record

)

Releases a log record delivered to a listener.

mln_adapter_log_set_callback()

mln_status mln_adapter_log_set_callback

(

mln_adapter_log_callback_state *

state

)

Installs state as the process-global log callback, or clears the current callback when state is null.

A registration this call replaces receives one final null record through its listener once its in-flight dispatches finish.

Returns:

• MLN_STATUS_OK on success.
• The status reported by mln_log_set_callback() or mln_log_clear_callback().

mln_adapter_queued_resource_provider_callback()

uint32_t mln_adapter_queued_resource_provider_callback	(	void *	user_data,
		const mln_resource_request *	request,
		mln_resource_request_handle	handle )

The mln_resource_provider_callback implementation for queued providers.

The user_data pointer is an mln_adapter_queued_resource_provider. A request matching one of the provider's routes is copied and handed to the listener, and reports MLN_RESOURCE_PROVIDER_DECISION_HANDLE. Other requests pass through unchanged and continue through the native loader. A request that cannot be copied is completed with an error response rather than left outstanding.

mln_adapter_queued_resource_provider_retire()

void mln_adapter_queued_resource_provider_retire

(

mln_adapter_queued_resource_provider *

provider

)

Delivers one null record to a queued provider's listener.

Hosts call this after the provider is no longer registered so the listener can release the host-side state that backed it.

mln_adapter_resource_provider_request_destroy()

void mln_adapter_resource_provider_request_destroy

(

void *

request

)

Releases a queued request record delivered to a listener.

mln_adapter_resource_provider_rules_callback()

uint32_t mln_adapter_resource_provider_rules_callback	(	void *	user_data,
		const mln_resource_request *	request,
		mln_resource_request_handle	handle )

The mln_resource_provider_callback implementation for provider rules.

The user_data pointer is an mln_adapter_resource_provider_rules table. A matching request is completed inline with the rule's response and reports MLN_RESOURCE_PROVIDER_DECISION_HANDLE. Other requests pass through.

mln_adapter_resource_transform_rewrite_callback()

mln_status mln_adapter_resource_transform_rewrite_callback	(	void *	user_data,
		uint32_t	kind,
		const char *	url,
		mln_resource_transform_response *	out_response )

The mln_resource_transform_callback implementation for rewrite rules.

The user_data pointer is an mln_adapter_resource_rewrite_rules table. The first matching rule replaces the URL, and a request that matches no rule passes through unchanged.