MRTKLIB Public API — Context Management and Logging. More...

#include <stdarg.h>
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include <time.h>
#include "mrtklib/mrtk_version.h"

Include dependency graph for mrtklib.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Typedefs
typedef struct mrtk_context_s	mrtk_context_t
	Opaque library context structure.
typedef void(*	mrtk_log_cb_t) (mrtk_context_t ctx, mrtk_log_level_t level, const char msg)
	Log callback function signature.

Enumerations
enum	mrtk_log_level_t { MRTK_LOG_DEBUG = 0 , MRTK_LOG_INFO , MRTK_LOG_WARN , MRTK_LOG_ERROR , MRTK_LOG_NONE }
	Log severity levels. More...

Functions
mrtk_context_t *	mrtk_context_new (void)
	Create a new library context.
void	mrtk_context_free (mrtk_context_t *ctx)
	Free the library context and release all associated resources.
void	mrtk_context_set_log_callback (mrtk_context_t *ctx, mrtk_log_cb_t cb)
	Set a custom log callback handler.
void	mrtk_context_set_log_level (mrtk_context_t *ctx, mrtk_log_level_t level)
	Set the minimum log level threshold.
mrtk_log_level_t	mrtk_context_get_log_level (const mrtk_context_t *ctx)
	Get the current log level threshold.
void	mrtk_log (mrtk_context_t ctx, mrtk_log_level_t level, const char fmt,...)
	Log a formatted message.
void	mrtk_log_v (mrtk_context_t ctx, mrtk_log_level_t level, const char fmt, va_list args)
	Log a formatted message using a pre-initialized va_list.
const char *	mrtk_get_last_error (const mrtk_context_t *ctx)
	Get the last error message.
void	mrtk_clear_error (mrtk_context_t *ctx)
	Clear the last error message.
void	mrtk_context_set_user_data (mrtk_context_t ctx, void user_data)
	Associate user-defined data with the context.
void *	mrtk_context_get_user_data (const mrtk_context_t *ctx)
	Retrieve user-defined data from the context.
const char *	mrtk_version_string (void)
	Get the library version string.

Variables
mrtk_context_t *	g_mrtk_legacy_ctx
	Global context for legacy RTKLIB trace() bridge.

Detailed Description

MRTKLIB Public API — Context Management and Logging.

This header defines the public API for MRTKLIB, a modernized and refactored version of RTKLIB targeting JAXA QZSS/MADOCA processing. The library is designed to be:

Thread-safe through context-based state management
Re-entrant, allowing multiple simultaneous processing instances
Library-first with no global state

Note: All public functions require a valid mrtk_context_t pointer unless otherwise specified.

Definition in file mrtklib.h.

Typedef Documentation

◆ mrtk_context_t

typedef struct mrtk_context_s mrtk_context_t

Opaque library context structure.

Holds all library state including logging configuration, error state, and user-defined data. This structure is intentionally opaque to allow internal changes without breaking API compatibility.

Note: Users must create contexts via mrtk_context_new() and free them via mrtk_context_free(). Never allocate this structure directly.

Definition at line 63 of file mrtklib.h.

◆ mrtk_log_cb_t

typedef void(* mrtk_log_cb_t) (mrtk_context_t *ctx, mrtk_log_level_t level, const char *msg)

Log callback function signature.

Custom log handlers must conform to this signature. The callback is invoked for each log message that passes the minimum log level filter.

Parameters

ctx	Context instance that generated the log message
level	Severity level of the message
msg	Null-terminated formatted message string

Note: The msg pointer is only valid during the callback invocation. Copy the string if you need to retain it.; The callback is invoked synchronously from the calling thread.

Definition at line 98 of file mrtklib.h.

Enumeration Type Documentation

◆ mrtk_log_level_t

enum mrtk_log_level_t

Log severity levels.

Levels are ordered by severity (DEBUG < INFO < WARN < ERROR < NONE). Setting a minimum log level filters out all messages below that severity. MRTK_LOG_NONE disables all output.

Enumerator
MRTK_LOG_DEBUG	Detailed debug information for development
MRTK_LOG_INFO	General informational messages
MRTK_LOG_WARN	Warning conditions that may require attention
MRTK_LOG_ERROR	Error conditions that affect processing
MRTK_LOG_NONE	Sentinel — disables all logging output

Definition at line 76 of file mrtklib.h.

Function Documentation

◆ mrtk_clear_error()

void mrtk_clear_error ( mrtk_context_t * ctx )

Clear the last error message.

Resets the error state, clearing any previously stored error message.

Parameters

ctx	Context instance
ctx	Context instance

Definition at line 319 of file mrtk_core.c.

References mrtk_context_s::last_error.

◆ mrtk_context_free()

void mrtk_context_free ( mrtk_context_t * ctx )

Free the library context and release all associated resources.

Safely frees a context created by mrtk_context_new(). After this call, the context pointer is invalid and must not be used.

Parameters

ctx	Context to free. If NULL, this function does nothing.

Free the library context and release all associated resources.

Releases all memory associated with the context. Safe to call with NULL.

Parameters

ctx	Context to free, or NULL (no-op)

Definition at line 184 of file mrtk_core.c.

References free.

◆ mrtk_context_get_log_level()

mrtk_log_level_t mrtk_context_get_log_level ( const mrtk_context_t * ctx )

Get the current log level threshold.

Parameters

ctx	Context instance

Returns: Current minimum log level, or MRTK_LOG_NONE if ctx is NULL.

Get the current log level threshold.

Parameters

ctx	Context instance

Returns: Current log level, or MRTK_LOG_NONE if ctx is NULL

Definition at line 233 of file mrtk_core.c.

References mrtk_context_s::log_level, and MRTK_LOG_NONE.

◆ mrtk_context_get_user_data()

void * mrtk_context_get_user_data ( const mrtk_context_t * ctx )

Retrieve user-defined data from the context.

Parameters

ctx	Context instance

Returns: Previously stored user data pointer, or NULL if none was set or if ctx is NULL.

Retrieve user-defined data from the context.

Parameters

ctx	Context instance

Returns: Associated user data, or NULL if ctx is NULL or no data was set

Definition at line 347 of file mrtk_core.c.

References mrtk_context_s::user_data.

◆ mrtk_context_new()

mrtk_context_t * mrtk_context_new ( void )

Create a new library context.

Allocates and initializes a new context with default settings:

Log level: MRTK_LOG_INFO
Log callback: Default stdout/stderr logger
User data: NULL

Returns: Pointer to newly created context, or NULL if allocation fails.

Note: The caller is responsible for freeing the context via mrtk_context_free().

mrtk_context_t* ctx = mrtk_context_new();
if (ctx == NULL) { ... }
// ... use context ...
mrtk_context_free(ctx);

Allocates memory for a new context and initializes it with default values. The default configuration is:

log_level: MRTK_LOG_INFO
log_callback: default_log_callback (stdout/stderr output)
last_error: empty string
user_data: NULL

Returns: Newly allocated context, or NULL if memory allocation fails.

Definition at line 162 of file mrtk_core.c.

References calloc, default_log_callback(), mrtk_context_s::last_error, mrtk_context_s::log_callback, mrtk_context_s::log_level, MRTK_LOG_INFO, and mrtk_context_s::user_data.

Here is the call graph for this function:

◆ mrtk_context_set_log_callback()

void mrtk_context_set_log_callback	(	mrtk_context_t *	ctx,
		mrtk_log_cb_t	cb )

Set a custom log callback handler.

Replaces the default logging behavior with a custom callback. This allows integration with external logging systems, GUI log windows, or file-based logging.

Parameters

ctx	Context instance
cb	Callback function to handle log messages. Pass NULL to restore the default stdout/stderr logger.

Set a custom log callback handler.

Parameters

ctx	Context instance
cb	Callback function, or NULL to restore default logger

Definition at line 202 of file mrtk_core.c.

References default_log_callback(), and mrtk_context_s::log_callback.

Here is the call graph for this function:

◆ mrtk_context_set_log_level()

void mrtk_context_set_log_level	(	mrtk_context_t *	ctx,
		mrtk_log_level_t	level )

Set the minimum log level threshold.

Messages below this severity level will be silently discarded. Setting MRTK_LOG_NONE disables all logging output.

Parameters

ctx	Context instance
level	Minimum level to log (inclusive)

Set the minimum log level threshold.

Parameters

ctx	Context instance
level	New minimum log level

Definition at line 221 of file mrtk_core.c.

References mrtk_context_s::log_level.

◆ mrtk_context_set_user_data()

void mrtk_context_set_user_data	(	mrtk_context_t *	ctx,
		void *	user_data )

Associate user-defined data with the context.

Stores an arbitrary pointer that can be retrieved later. Useful for passing application-specific state through callbacks.

Parameters

ctx	Context instance
user_data	Pointer to user data (may be NULL)

Note: The library does not manage the lifetime of user_data.

Associate user-defined data with the context.

Parameters

ctx	Context instance
user_data	Pointer to associate with context

Definition at line 335 of file mrtk_core.c.

References mrtk_context_s::user_data.

◆ mrtk_get_last_error()

const char * mrtk_get_last_error ( const mrtk_context_t * ctx )

Get the last error message.

Retrieves the most recent error message stored in the context by an internal library function. Returns an empty string if no error has occurred.

Parameters

ctx	Context instance

Returns: Pointer to the error message string, or "Invalid context" if ctx is NULL.

Note: The returned pointer remains valid until the next error occurs or the context is freed.

Parameters

ctx	Context instance

Returns: Error message string, or "Invalid context" if ctx is NULL

Definition at line 307 of file mrtk_core.c.

References mrtk_context_s::last_error.

◆ mrtk_log()

void mrtk_log	(	mrtk_context_t *	ctx,
		mrtk_log_level_t	level,
		const char *	fmt,
			... )

Log a formatted message.

Formats and dispatches a log message through the registered callback if the message level meets or exceeds the minimum threshold.

Parameters

ctx	Context instance
level	Severity level of this message
fmt	printf-style format string
...	Format arguments

Convenience wrapper around mrtk_log_v() that accepts variadic arguments.

Parameters

ctx	Context instance
level	Message severity level
fmt	printf-style format string
...	Format arguments

Definition at line 289 of file mrtk_core.c.

References mrtk_log_v().

Referenced by mrtk_set_error().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ mrtk_log_v()

void mrtk_log_v	(	mrtk_context_t *	ctx,
		mrtk_log_level_t	level,
		const char *	fmt,
		va_list	args )

Log a formatted message using a pre-initialized va_list.

This is the va_list variant of mrtk_log(), intended for use by wrapper functions (such as the legacy RTKLIB trace() bridge) that receive variadic arguments from their own callers.

Parameters

ctx	Context instance
level	Severity level of this message
fmt	printf-style format string
args	Pre-initialized va_list

This is the core formatting and dispatch function. Both mrtk_log() and the legacy trace() bridge delegate to this function.

Parameters

ctx	Context instance
level	Message severity level
fmt	printf-style format string
args	Pre-initialized va_list

Definition at line 251 of file mrtk_core.c.

References mrtk_context_s::log_callback, MAX_LOG_LEN, and MRTK_LOG_NONE.

Referenced by mrtk_log().

Here is the caller graph for this function:

◆ mrtk_version_string()

const char * mrtk_version_string ( void )

Get the library version string.

Returns: Static string containing the version (e.g., "1.2.0"); Static version string (e.g., "0.1.0")

Definition at line 363 of file mrtk_core.c.

Variable Documentation

◆ g_mrtk_legacy_ctx

mrtk_context_t* g_mrtk_legacy_ctx

extern

Global context for legacy RTKLIB trace() bridge.

During the migration period, this global pointer allows the existing trace() / tracet() functions in rtkcmn.c to route their output through the new context-based logging system without modifying thousands of call sites.

Note: Applications must set this to mrtk_context_new() at startup and free it with mrtk_context_free() at shutdown.; This pointer is intentionally global and will be removed once all modules have been migrated to context-based APIs.

See also: g_mrtk_legacy_ctx declaration in mrtklib.h

Definition at line 40 of file mrtk_core.c.

Typedefs

Enumerations

Functions

Variables

Detailed Description

Typedef Documentation

◆ mrtk_context_t

◆ mrtk_log_cb_t

Enumeration Type Documentation

◆ mrtk_log_level_t

Function Documentation

◆ mrtk_clear_error()

◆ mrtk_context_free()

◆ mrtk_context_get_log_level()

◆ mrtk_context_get_user_data()

◆ mrtk_context_new()

◆ mrtk_context_set_log_callback()

◆ mrtk_context_set_log_level()

◆ mrtk_context_set_user_data()

◆ mrtk_get_last_error()

◆ mrtk_log()

◆ mrtk_log_v()

◆ mrtk_version_string()

Variable Documentation

◆ g_mrtk_legacy_ctx