KasperskyOS Community Edition 1.3
English

Contents

The logrr_cpp library

The logrr_cpp library provides the API for sending messages to the log.

The logrr_cpp library is intended for use in C++ programs. In C-language programs, use the logrr_clog library.

To get access to the API of this library:

Link your program to the library by using the target_link_libraries() CMake command.

CMakeLists.txt

target_link_libraries (${TARGET_NAME} ${logrr_cpp_LIB})

In this Help section

Log() method and LOG macro

LogLevel class

LogIface class
Page top
[Topic logrr_api_cpp]

Log() method and LOG macro

The logrr::Log() method writes to the log.

Method parameters:

logLevel
Log level LogLevel.
sourceLocation
Object that determines the location in the source code (file name, function name, line number and column number). The std::source_location class is used in C++20, while the std::experimental::source_location class is used in earlier versions.
format
Message text formatting string.
args
Parameters to be inserted into the format formatting string.

The logrr::Log() method is intended for use in C++ programs. In C-language programs, use the static function ClogLog() or CLOG macro.

A description of the logrr::Log() method and macros for quick access to it are provided in the file /opt/KasperskyOS-Community-Edition-<version>/sysroot-*-kos/include/component/logrr/cpp/logger.h.

component/logrr/cpp/logger.h (fragment)

namespace logrr { namespace details { __rtl_public void PrintErrorMessage(std::string_view fileName, std::uint32_t line, std::string_view exMsg) noexcept; } // namespace details __rtl_public void Init(std::string_view providerName) noexcept; __rtl_public bool ShouldLog(logrr::LogLevel logLevel) noexcept; __rtl_public void SendMessage( std::string_view module, LogLevel logLevel, std::string_view file, const uint32_t line, std::string_view function, std::string_view msg) noexcept; template <typename... Args> __rtl_public void Log( logrr::LogLevel logLevel, kos::rtl::SourceLocation sourceLocation, std::string_view format, Args&&... args) noexcept { Log(logLevel, sourceLocation.file_name(), sourceLocation.line(), sourceLocation.function_name(), format, std::forward<Args>(args)...); } template <typename... Args> __rtl_public void Log( std::string_view module, logrr::LogLevel logLevel, kos::rtl::SourceLocation sourceLocation, std::string_view format, Args&&... args) noexcept { Log(module, logLevel, sourceLocation.file_name(), sourceLocation.line(), sourceLocation.function_name(), format, std::forward<Args>(args)...); } template <typename... Args> __rtl_public void Log( logrr::LogLevel logLevel, std::string_view file, const uint32_t line, std::string_view function, std::string_view format, Args&&... args) noexcept { Log("", logLevel, file, line, function, format, std::forward<Args>(args)...); } template <typename... Args> __rtl_public void Log( std::string_view module, logrr::LogLevel logLevel, std::string_view file, const uint32_t line, std::string_view function, std::string_view format, Args&&... args) noexcept { if (ShouldLog(logLevel)) try { constexpr auto MaxLength = static_cast<std::size_t>(LOGRR_LOG_MESSAGE_MAX_SIZE - 1); if constexpr (!sizeof...(args)) { SendMessage(module, logLevel, file, line, function, format.substr(0, MaxLength)); } else { std::array<std::uint8_t, MaxLength> fmtBuf; const auto endIt{fmt::format_to_n( fmtBuf.begin(), MaxLength, format, std::forward<Args>(args)...).out}; const std::string_view formattedStr{ reinterpret_cast<const char*>(fmtBuf.data()), static_cast<std::size_t>(std::distance(fmtBuf.begin(), endIt))}; SendMessage(module, logLevel, file, line, function, formattedStr); } } catch (const std::exception& e) { details::PrintErrorMessage(file, line, e.what()); } } } // namespace logrr namespace { const std::string_view LOG_MODULE; } // namespace #define __CPPLOG_LEVEL_TRACE__ logrr::LogLevel::Trace #define __CPPLOG_LEVEL_DEBUG__ logrr::LogLevel::Debug #define __CPPLOG_LEVEL_INFO__ logrr::LogLevel::Info #define __CPPLOG_LEVEL_WARNING__ logrr::LogLevel::Warning #define __CPPLOG_LEVEL_ERROR__ logrr::LogLevel::Error #define __CPPLOG_LEVEL_CRITICAL__ logrr::LogLevel::Critical #define LOG_INIT(providerName) \ logrr::Init(providerName) #define CALL_LOG(level, ...) \ logrr::Log(LOG_MODULE, level, kos::rtl::SourceLocation::current(), __VA_ARGS__) #define CALL_LOG_SL(level, file, line, func, ...) \ logrr::Log(LOG_MODULE, level, file, line, func, __VA_ARGS__) #define LOG(level, ...) CALL_LOG(__CPPLOG_LEVEL_ ## level ## __, __VA_ARGS__) #define LOG_SL(level, file, line, func, ...) CALL_LOG_SL(__CPPLOG_LEVEL_ ## level ## __, file, line, func, __VA_ARGS__)

A macro for quick access to the Log() method

Instead of calling the static method Logger::Log(), you can use the macro whose description is provided in the file component/logrr/cpp/logger.h. This macro is variadic (takes a variable number of parameters), which lets you avoid specifying all parameters of the Logger::Log() method. When calling this macro, you only need to specify the log level and message formatting string with the values of parameters. The applied log level logLevel is determined by the first parameter of the macro: An example of using these macros is provided in the section titled Using macros to send messages to a log.

Page top
[Topic logrr_api_cpp_log]

LogLevel class

The LogLevel class is an enumeration (enum class) and contains fields whose names correspond to the log levels available in the LogRR program.

The LogLevel class is intended for use in C++ programs. In C-language programs, use the enumerated type LogrrLogLevel.

Values of LogLevel enumeration can be passed to the following:

  • Static method Log() of the Logger class
  • Static methods ChangeLogLevel() and ChangeGlobalLogLevel() of the Controller structure
  • LogIface class constructor

A description of the LogLevel class is provided in the file /opt/KasperskyOS-Community-Edition-<version>/sysroot-*-kos/include/component/logrr/core/log_level.h.

component/logrr/core/log_level.h (fragment)

enum class LogLevel : int8_t { Critical = 0, Error, Warning, Info, Debug, Trace };
Page top
[Topic logrr_api_cpp_loglevel]

LogIface class

The LogIface class contains methods that let you incrementally build the text of a log entry from parts and then send the entry to the log with one call:

  • The SetLogLevel() method is used to set the log level of sent messages.
  • The Push() method is used to add text to a message.
  • The Flush() method is used to send a message composed of one or more Push() method calls to the log.

    When the ~LogIface() destructor is called, the message composed of Push() calls is also sent to the log if the message was not previously sent using Flush().

  • The Log() method is used to immediately send a separate message (without using the text composed of Push() calls).

To create a LogIface class instance, pass one of the LogLevel enumerators to the class constructor. An example of using functions of the LogIface class is provided in the "Merging messages" subsection under Advanced capabilities when sending messages to a log.

A description of the LogIface class is provided in the file /opt/KasperskyOS-Community-Edition-<version>/sysroot-*-kos/include/component/logrr/cpp/tools.h.

component/logrr/cpp/tools.h (fragment)

/** * @brief C++ provider interface for logrr for simple printing and queuing logs * */ class LogIface { // ... public: LogIface(logrr::LogLevel level, sl::source_location loc = sl::source_location::current()) : m_level(level), m_defaultSourceLocation(loc) {} void SetLogLevel(logrr::LogLevel new_level) { m_level = new_level; } /** * @brief Append new format with args to current message template * */ template <typename... Args> void Push(std::string_view frmt, Args&&... args) { AppendFormat(m_message, frmt, std::forward<Args>(args)...); } /** * @brief Log instantly through separate Log command * */ template <typename... Args> void Log(FormatWithLocation frmt, Args&&... args) { Flush_(frmt.loc, frmt.frmt, std::forward<Args>(args)...); } /** * @brief Flush current message, built with Push, to Log * */ void Flush(const sl::source_location& loc = sl::source_location::current()) { Flush_(loc, m_message); m_message.clear(); } ~LogIface() { if (!m_message.empty()) { Flush_(m_defaultSourceLocation, m_message); } } // ... };
Page top
[Topic logrr_api_cpp_logiface]