/* * Copyright (c) 2010-2019 Belledonne Communications SARL. * * This file is part of Liblinphone. * * This program is free software: you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation, either version 3 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License * along with this program. If not, see . */ #ifndef _LINPHONE_LOG_H_ #define _LINPHONE_LOG_H_ #include "types.h" #include "defs.h" #ifdef __cplusplus extern "C" { #endif /** * @addtogroup logging * @{ */ /** * @brief Singleton class giving access to logging features. * * It supports custom domain, writing into a file as well as several verbosity levels. * The #LinphoneLoggingServiceCbs listener allows you to be notified each time a log is printed. * * As the #LinphoneLoggingService is a singleton, use linphone_logging_service_get() to get it. */ typedef struct _LinphoneLoggingService LinphoneLoggingService; /** * @brief Listener for #LinphoneLoggingService. */ typedef struct _LinphoneLoggingServiceCbs LinphoneLoggingServiceCbs; /** * @brief Verbosity levels of log messages. */ typedef enum _LinphoneLogLevel { LinphoneLogLevelDebug = 1<<0, /**< @brief Level for debug messages. */ LinphoneLogLevelTrace = 1<<1, /**< @brief Level for traces. */ LinphoneLogLevelMessage = 1<<2, /**< @brief Level for information messages. */ LinphoneLogLevelWarning = 1<<3, /**< @brief Level for warning messages. */ LinphoneLogLevelError = 1<<4, /**< @brief Level for error messages. */ LinphoneLogLevelFatal = 1<<5 /**< @brief Level for fatal error messages. */ } LinphoneLogLevel; /** * @brief Type of callbacks called each time liblinphone write a log message. * * @param log_service A pointer on the logging service singleton. @notnil * @param domain A string describing which sub-library of liblinphone the message is coming from. @notnil * @param level Verbosity #LinphoneLogLevel of the message. * @param message Content of the message. @notnil */ typedef void (*LinphoneLoggingServiceCbsLogMessageWrittenCb)(LinphoneLoggingService *log_service, const char *domain, LinphoneLogLevel level, const char *message); /** * @brief Gets the singleton logging service object. * * The singleton is automatically instantiated if it hasn't * been done yet. * * @return A pointer on the #LinphoneLoggingService singleton. @notnil */ LINPHONE_PUBLIC LinphoneLoggingService *linphone_logging_service_get(void); /** * @brief Increases the reference counter. * @param log_service the #LinphoneLoggingService object @notnil * @return the same #LinphoneLoggingService object @notnil */ LINPHONE_PUBLIC LinphoneLoggingService *linphone_logging_service_ref(LinphoneLoggingService *log_service); /** * @brief Decreases the reference counter and destroy the object if the counter reaches 0. * @param log_service the #LinphoneLoggingService object @notnil */ LINPHONE_PUBLIC void linphone_logging_service_unref(LinphoneLoggingService *log_service); /** * Adds a callback object to the list of listeners * @param log_service the #LinphoneLoggingService object @notnil * @param cbs the #LinphoneLoggingServiceCbs to add @notnil */ LINPHONE_PUBLIC void linphone_logging_service_add_callbacks(LinphoneLoggingService *log_service, LinphoneLoggingServiceCbs *cbs); /** * Removes a callback object from the list of listeners * @param log_service the #LinphoneLoggingService object @notnil * @param cbs the #LinphoneLoggingServiceCbs to remove @notnil */ LINPHONE_PUBLIC void linphone_logging_service_remove_callbacks(LinphoneLoggingService *log_service, LinphoneLoggingServiceCbs *cbs); /** * Returns the current callbacks being called while iterating on callbacks * @param log_service the #LinphoneLoggingService object @notnil * @return A pointer to the current #LinphoneLoggingServiceCbs object @maybenil */ LINPHONE_PUBLIC LinphoneLoggingServiceCbs *linphone_logging_service_get_current_callbacks(const LinphoneLoggingService *log_service); /** * @brief Set the verbosity of the log. * * For instance, a level of #LinphoneLogLevelMessage will let pass fatal, error, warning and message-typed messages * whereas trace and debug messages will be dumped out. * @param log_service the #LinphoneLoggingService object @notnil * @param level the #LinphoneLogLevel to set */ LINPHONE_PUBLIC void linphone_logging_service_set_log_level(LinphoneLoggingService *log_service, LinphoneLogLevel level); /** * @brief Sets the types of messages that will be authorized to be written in the log. * @param log_service the #LinphoneLoggingService object @notnil * @param mask Example: #LinphoneLogLevelMessage|#LinphoneLogLevelError will ONLY let pass message-typed and error messages. * @note Calling that function reset the log level that has been specified by #linphone_logging_service_set_log_level(). */ LINPHONE_PUBLIC void linphone_logging_service_set_log_level_mask(LinphoneLoggingService *log_service, unsigned int mask); /** * @brief Gets the log level mask. * @param log_service the #LinphoneLoggingService object @notnil * @return the log level mask */ LINPHONE_PUBLIC unsigned int linphone_logging_service_get_log_level_mask(const LinphoneLoggingService *log_service); /** * @brief Enables logging in a file. * * That function enables an internal log handler that writes log messages in * log-rotated files. * * @param log_service the #LinphoneLoggingService object @notnil * @param dir Directory where to create the distinct parts of the log. @notnil * @param filename Name of the log file. @notnil * @param max_size The maximal size of each part of the log. The log rotating is triggered * each time the currently opened log part reach that limit. */ LINPHONE_PUBLIC void linphone_logging_service_set_log_file(const LinphoneLoggingService *log_service, const char *dir, const char *filename, size_t max_size); /** * @brief Set the domain where application logs are written (for example with #linphone_logging_service_message()). * @param log_service the #LinphoneLoggingService object @notnil * @param domain The domain. @maybenil * @note The domain is mandatory to write logs. This needs to be set before setting the log level. */ LINPHONE_PUBLIC void linphone_logging_service_set_domain(LinphoneLoggingService *log_service, const char *domain); /** * @brief Get the domain where application logs are written (for example with #linphone_logging_service_message()). * @param log_service the #LinphoneLoggingService object @maybenil * @return The domain where application logs are written. @maybenil */ LINPHONE_PUBLIC const char *linphone_logging_service_get_domain(LinphoneLoggingService *log_service); /** * @brief Write a LinphoneLogLevelDebug message to the logs. * @param log_service the #LinphoneLoggingService object @notnil * @param message The log message. @notnil */ LINPHONE_PUBLIC void linphone_logging_service_debug(LinphoneLoggingService *log_service, const char *message); /** * @brief Write a LinphoneLogLevelTrace message to the logs. * @param log_service the #LinphoneLoggingService object @notnil * @param message The log message. @notnil */ LINPHONE_PUBLIC void linphone_logging_service_trace(LinphoneLoggingService *log_service, const char *message); /** * @brief Write a LinphoneLogLevelMessage message to the logs. * @param log_service the #LinphoneLoggingService object @notnil * @param message The log message. @notnil */ LINPHONE_PUBLIC void linphone_logging_service_message(LinphoneLoggingService *log_service, const char *message); /** * @brief Write a LinphoneLogLevelWarning message to the logs. * @param log_service the #LinphoneLoggingService object @notnil * @param message The log message. @notnil */ LINPHONE_PUBLIC void linphone_logging_service_warning(LinphoneLoggingService *log_service, const char *message); /** * @brief Write a LinphoneLogLevelError message to the logs. * @param log_service the #LinphoneLoggingService object @notnil * @param message The log message. @notnil */ LINPHONE_PUBLIC void linphone_logging_service_error(LinphoneLoggingService *log_service, const char *message); /** * @brief Write a LinphoneLogLevelFatal message to the logs. * @param log_service the #LinphoneLoggingService object @notnil * @param message The log message. @notnil */ LINPHONE_PUBLIC void linphone_logging_service_fatal(LinphoneLoggingService *log_service, const char *message); /** * @brief Increases the reference counter. * @param cbs the #LinphoneLoggingServiceCbs object. @notnil * @return the same #LinphoneLoggingServiceCbs object @notnil */ LINPHONE_PUBLIC LinphoneLoggingServiceCbs *linphone_logging_service_cbs_ref(LinphoneLoggingServiceCbs *cbs); /** * @brief Decreases the reference counter. * * The object is automatically destroyed once the counter reach 0. * @param cbs the #LinphoneLoggingServiceCbs object. @notnil */ LINPHONE_PUBLIC void linphone_logging_service_cbs_unref(LinphoneLoggingServiceCbs *cbs); /** * @brief Sets the callback to call each time liblinphone writes a log message. * @param cbs the #LinphoneLoggingServiceCbs object. @notnil * @param cb the #LinphoneLoggingServiceCbsLogMessageWrittenCb to set */ LINPHONE_PUBLIC void linphone_logging_service_cbs_set_log_message_written(LinphoneLoggingServiceCbs *cbs, LinphoneLoggingServiceCbsLogMessageWrittenCb cb); /** * @brief Gets the value of the message event callback. * @param cbs the #LinphoneLoggingServiceCbs object. @notnil * @return the current #LinphoneLoggingServiceCbsLogMessageWrittenCb */ LINPHONE_PUBLIC LinphoneLoggingServiceCbsLogMessageWrittenCb linphone_logging_service_cbs_get_log_message_written(const LinphoneLoggingServiceCbs *cbs); /** * @brief Pass a pointer on a custom object. * * That pointer can be get back by callbacks by using #linphone_logging_service_get_cbs() and #linphone_logging_service_cbs_get_user_data(). * @param cbs the #LinphoneLoggingServiceCbs object. @notnil * @param user_data the user data pointer. @maybenil */ LINPHONE_PUBLIC void linphone_logging_service_cbs_set_user_data(LinphoneLoggingServiceCbs *cbs, void *user_data); /** * @brief Gets the user_data pointer back. * @param cbs the #LinphoneLoggingServiceCbs object. @notnil * @return the user data pointer. @maybenil */ LINPHONE_PUBLIC void *linphone_logging_service_cbs_get_user_data(const LinphoneLoggingServiceCbs *cbs); /************ */ /* DEPRECATED */ /* ********** */ /** * @brief Gets the logging service listener. * @param log_service the #LinphoneLoggingService object * @deprecated 19/02/2019 Use add_callbacks / remove_callbacks instead * @donotwrap */ LINPHONE_PUBLIC LINPHONE_DEPRECATED LinphoneLoggingServiceCbs *linphone_logging_service_get_callbacks(const LinphoneLoggingService *log_service); /** * @} */ #ifdef __cplusplus } #endif #endif // _LINPHONE_LOG_H_