logger.h File Reference

MPDC Logging Functions. More...

#include "common.h"
#include "commands.h"

Go to the source code of this file.

Macros
#define	MPDC_LOGGING_MESSAGE_MAX   256
	The maximum length (in characters) for a logging message.
#define	MPDC_LOG_STRING_DEPTH   69
	The number of predefined log strings.
#define	MPDC_LOG_STRING_SIZE   64
	The maximum size (in characters) for a single log string.

Functions
MPDC_EXPORT_API void	logger_default_path (char *path, size_t pathlen)
	Get the default logging path.
MPDC_EXPORT_API bool	mpdc_logger_dispose (const char *path)
	Erase and delete the log file.
MPDC_EXPORT_API bool	mpdc_logger_erase_all (const char *path)
	Erase the log file.
MPDC_EXPORT_API bool	mpdc_logger_exists (const char *path)
	Check if the log file exists.
MPDC_EXPORT_API void	mpdc_logger_initialize (const char *path)
	Initialize the logger.
MPDC_EXPORT_API size_t	mpdc_logger_get_size (const char *path)
	Get the size of the log file.
MPDC_EXPORT_API void	mpdc_logger_reset (const char *path)
	Reset the logger.
MPDC_EXPORT_API size_t	mpdc_logger_write_message (const char *path, const char *line, size_t linelen)
	Write a message to the log file.
MPDC_EXPORT_API size_t	mpdc_logger_write_decorated_message (const char *path, mpdc_application_messages msgtype, const char *message, size_t msglen)
	Write a decorated message to the log file.
MPDC_EXPORT_API size_t	mpdc_logger_write_time_stamped_message (const char *path, const char *message, size_t msglen)
	Write a time-stamped message to the log file.
MPDC_EXPORT_API size_t	mpdc_logger_write_decorated_time_stamped_message (const char *path, mpdc_application_messages msgtype, const char *message, size_t msglen)
	Write a decorated, time-stamped message to the log file.
MPDC_EXPORT_API size_t	mpdc_logger_read_all (const char *path, char *output, size_t outlen)
	Read the entire log into a character array.
MPDC_EXPORT_API int64_t	mpdc_logger_read_line (const char *path, char *output, size_t outlen, size_t linenum)
	Read a single line from the log file.
MPDC_EXPORT_API size_t	mpdc_logger_time_stamp (char *output, size_t outlen)
	Write a timestamp to a string.

Detailed Description

MPDC Logging Functions.

This header defines the logging functions used throughout the MPDC system. The logger provides a standard mechanism for writing diagnostic and operational messages to a log file. The logging module supports basic operations such as:

• Obtaining the default logging file path.
• Initializing the logger.
• Checking for the existence and retrieving the size of the log file.
• Writing plain, decorated, and time-stamped log messages.
• Reading the complete log or individual log lines.
• Resetting (erasing) and disposing (deleting) the log file.

The following macros are defined to specify the maximum message length and the dimensions of the log string storage:

• MPDC_LOGGING_MESSAGE_MAX defines the maximum number of characters for a log message.
• MPDC_LOG_STRING_DEPTH and MPDC_LOG_STRING_SIZE specify the dimensions used for storing pre-defined log strings.

Additionally, static constants provide the default logger path, file name, and header string.

These logging routines utilize underlying QSC file and console utilities to ensure thread-safe access to the log file and provide formatted, timestamped output.

Function Documentation

logger_default_path()

MPDC_EXPORT_API void logger_default_path	(	char *	path,
		size_t	pathlen )

Get the default logging path.

This function retrieves the default log file path by obtaining the user's documents directory, appending the MPDC logger directory name, and finally the log file name.

Parameters

path	[out] The output buffer that will receive the full log file path.
pathlen	The length of the output buffer.

mpdc_logger_dispose()

MPDC_EXPORT_API bool mpdc_logger_dispose

(

const char *

path

)

Erase and delete the log file.

This function deletes the log file at the specified path.

Parameters

path	[in] The log file path.

Returns

Returns true on success.

mpdc_logger_erase_all()

MPDC_EXPORT_API bool mpdc_logger_erase_all

(

const char *

path

)

Erase the log file.

This function clears the contents of the log file without deleting the file itself.

Parameters

path	[in] The log file path.

Returns

Returns true on success.

mpdc_logger_exists()

MPDC_EXPORT_API bool mpdc_logger_exists

(

const char *

path

)

Check if the log file exists.

Parameters

path	[in] The log file path.

Returns

Returns true if the log file exists.

mpdc_logger_get_size()

MPDC_EXPORT_API size_t mpdc_logger_get_size

(

const char *

path

)

Get the size of the log file.

This function returns the size (in characters) of the log file.

Parameters

path	[in] The log file path.

Returns

Returns the character size of the log file.

mpdc_logger_initialize()

MPDC_EXPORT_API void mpdc_logger_initialize

(

const char *

path

)

Initialize the logger.

This function creates or resets the log file at the specified path if it does not already exist.

Parameters

path	[in] The log file path.

mpdc_logger_read_all()

MPDC_EXPORT_API size_t mpdc_logger_read_all	(	const char *	path,
		char *	output,
		size_t	outlen )

Read the entire log into a character array.

Parameters

path	[in] The full path to the log file.
output	[out] The output string receiving the log contents.
outlen	The length of the output array.

Returns

Returns the number of characters read.

mpdc_logger_read_line()

MPDC_EXPORT_API int64_t mpdc_logger_read_line	(	const char *	path,
		char *	output,
		size_t	outlen,
		size_t	linenum )

Read a single line from the log file.

Parameters

path	[in] The full path to the log file.
output	[out] The output string receiving the line.
outlen	The length of the output string.
linenum	The 0-based line number to read.

Returns

Returns the number of characters read.

mpdc_logger_reset()

MPDC_EXPORT_API void mpdc_logger_reset

(

const char *

path

)

Reset the logger.

Erases the log file (or creates a new empty log file if it does not exist).

Parameters

path	[in] The log file path.

mpdc_logger_time_stamp()

MPDC_EXPORT_API size_t mpdc_logger_time_stamp	(	char *	output,
		size_t	outlen )

Write a timestamp to a string.

This function retrieves the current date and time in a formatted string.

Parameters

output	[out] The output string receiving the timestamp.
outlen	The length of the output array.

Returns

Returns the number of characters in the timestamp string.

mpdc_logger_write_decorated_message()

MPDC_EXPORT_API size_t mpdc_logger_write_decorated_message	(	const char *	path,
		mpdc_application_messages	msgtype,
		const char *	message,
		size_t	msglen )

Write a decorated message to the log file.

This function prepends a predefined message (based on the provided message type) to the given message text and writes the result to the log.

Parameters

path	[in] The log file path.
msgtype	The predefined message type (from mpdc_application_messages).
message	[in, const] The message to write.
msglen	The length of the message.

Returns

Returns the number of characters written.

mpdc_logger_write_decorated_time_stamped_message()

MPDC_EXPORT_API size_t mpdc_logger_write_decorated_time_stamped_message	(	const char *	path,
		mpdc_application_messages	msgtype,
		const char *	message,
		size_t	msglen )

Write a decorated, time-stamped message to the log file.

This function first obtains a current timestamp, then prepends a predefined message based on the given message type, and finally writes the complete entry to the log file.

Parameters

path	[in] The full log file path.
msgtype	The predefined message type.
message	[in, const] The message to write.
msglen	The length of the message.

Returns

Returns the number of characters written.

mpdc_logger_write_message()

MPDC_EXPORT_API size_t mpdc_logger_write_message	(	const char *	path,
		const char *	line,
		size_t	linelen )

Write a message to the log file.

This function appends a terminated line (with a newline) to the log file.

Parameters

path	[in] The log file path.
line	[in, const] The null-terminated string to write.
linelen	The length of the line.

Returns

Returns the number of characters written.

mpdc_logger_write_time_stamped_message()

MPDC_EXPORT_API size_t mpdc_logger_write_time_stamped_message	(	const char *	path,
		const char *	message,
		size_t	msglen )

Write a time-stamped message to the log file.

This function writes a log entry that begins with a current timestamp.

Parameters

path	[in] The log file path.
message	[in, const] The message to log.
msglen	The length of the message.

Returns

Returns the number of characters written.