logger.h File Reference

UDIF Logging Functions. More...

#include "udifcommon.h"
#include "commands.h"

Go to the source code of this file.

Macros
#define	UDIF_LOGGING_MESSAGE_MAX   256U
	The maximum length (in characters) for a logging message.
#define	UDIF_LOG_STRING_DEPTH   69U
	The number of predefined log strings.
#define	UDIF_LOG_STRING_SIZE   64U
	The maximum size (in characters) for a single log string.

Functions
UDIF_EXPORT_API void	logger_default_path (char *path, size_t pathlen)
	Get the default logging path.
UDIF_EXPORT_API bool	udif_logger_dispose (const char *path)
	Erase and delete the log file.
UDIF_EXPORT_API bool	udif_logger_erase_all (const char *path)
	Erase the log file.
UDIF_EXPORT_API bool	udif_logger_exists (const char *path)
	Check if the log file exists.
UDIF_EXPORT_API void	udif_logger_initialize (const char *path)
	Initialize the logger.
UDIF_EXPORT_API size_t	udif_logger_get_size (const char *path)
	Get the size of the log file.
UDIF_EXPORT_API void	udif_logger_reset (const char *path)
	Reset the logger.
UDIF_EXPORT_API size_t	udif_logger_write_message (const char *path, const char *line, size_t linelen)
	Write a message to the log file.
UDIF_EXPORT_API size_t	udif_logger_write_decorated_message (const char *path, udif_application_messages msgtype, const char *message, size_t msglen)
	Write a decorated message to the log file.
UDIF_EXPORT_API size_t	udif_logger_write_time_stamped_message (const char *path, const char *message, size_t msglen)
	Write a time-stamped message to the log file.
UDIF_EXPORT_API size_t	udif_logger_write_decorated_time_stamped_message (const char *path, udif_application_messages msgtype, const char *message, size_t msglen)
	Write a decorated, time-stamped message to the log file.
UDIF_EXPORT_API size_t	udif_logger_read_all (const char *path, char *output, size_t outlen)
	Read the entire log into a character array.
UDIF_EXPORT_API int64_t	udif_logger_read_line (const char *path, char *output, size_t outlen, size_t linenum)
	Read a single line from the log file.
UDIF_EXPORT_API size_t	udif_logger_time_stamp (char *output, size_t outlen)
	Write a timestamp to a string.

Detailed Description

UDIF Logging Functions.

This header defines the logging functions used throughout the UDIF 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:

• UDIF_LOGGING_MESSAGE_MAX defines the maximum number of characters for a log message.
• UDIF_LOG_STRING_DEPTH and UDIF_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()

UDIF_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 UDIF 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.

udif_logger_dispose()

UDIF_EXPORT_API bool udif_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.

udif_logger_erase_all()

UDIF_EXPORT_API bool udif_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.

udif_logger_exists()

UDIF_EXPORT_API bool udif_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.

udif_logger_get_size()

UDIF_EXPORT_API size_t udif_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.

udif_logger_initialize()

UDIF_EXPORT_API void udif_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.

udif_logger_read_all()

UDIF_EXPORT_API size_t udif_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.

udif_logger_read_line()

UDIF_EXPORT_API int64_t udif_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.

udif_logger_reset()

UDIF_EXPORT_API void udif_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.

udif_logger_time_stamp()

UDIF_EXPORT_API size_t udif_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.

udif_logger_write_decorated_message()

UDIF_EXPORT_API size_t udif_logger_write_decorated_message	(	const char *	path,
		udif_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 udif_application_messages).
message	[in, const] The message to write.
msglen	The length of the message.

Returns

Returns the number of characters written.

udif_logger_write_decorated_time_stamped_message()

UDIF_EXPORT_API size_t udif_logger_write_decorated_time_stamped_message	(	const char *	path,
		udif_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.

udif_logger_write_message()

UDIF_EXPORT_API size_t udif_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.

udif_logger_write_time_stamped_message()

UDIF_EXPORT_API size_t udif_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.