Custom Logging

Setup

To use the Immersitech Logger you only have to call the following function:

imm_enable_logging( true );

You can also optionally set the log level.
All log messages equal to or higher priority than the set level will be printed.

imm_set_log_level( imm_log_level::IMM_LOG_WARNING );

Default Behavior

By default, you don\'t need to configure anything or write any code for logging to be work besides enabling it as above.
The Immersitech Library\'s default logger will print all log messages in the following form to the standard output:

[Immersitech] [Wed, 03.02.2021 18:41:03] [WARNING]: You cannot move the position of participant 4 because room 0 is not an open room

We recommend trying the default logging first and see how you like it, you may not need to change anything.
If you find you want something more from your logging experience, read on to implement a custom logger.

Coding a Custom Logger

To implement your own custom logging system, you simply have to implement the immersitech_logger_handler class.
When you implement the immersitech_logger_handler::handle() function, you will tell the library what to do with
a message that needs to be logged. For example, you can implement the handle function to write the message to a file.
If you want persistant date for your logger class, such as a pointer to an open file or a mutex for thread safety,
then you can allocate and free them in the immersitech_logger_handler::immersitech_logger_handler() and
immersitech_logger_handler::~immersitech_logger_handler() constructor and destructor respectively.

Example Custom Logger

Here is an example of a possible custom logging implementation that writes the output to a file instead of the console.

class my_custom_file_logger: public immersitech_logger_handler {
public:
    my_custom_file_logger(std::string file_path) {
        _myfile.open(file_path);
    };
    virtual ~my_custom_file_logger() {
        _myfile.close();
    };
    virtual void handle(log_level level, const char* str) {
        _myfile << \"[\" << level << \"] \" << str;
    };
private:
    ofstream _myfile;
};

Instantiate a Custom Logger

Once you have coded you custom logging class, unlike the default logger, you must initiate it in code.
To do so, simply allocate a new object, and then call the logger::initialize() function to point the singleton logger to your custom instance:

my_custom_file_logger* custom_logger = new my_custom_file_logger();
IMM_LOGGER->initialize(custom_logger);

Once your logger is initialized, the Immersitech library will take care of all the logging from there using your handle function.
Note that you must free the memory for your custom logger manually when the program is finished, the Immersitech Library will NOT free the custom logger for you.

delete( custom-logger );