third_party/ot-br-posix/repo/src/common/logging.hpp

   1 /*
   2  *    Copyright (c) 2017, The OpenThread Authors.
   3  *    All rights reserved.
   4  *
   5  *    Redistribution and use in source and binary forms, with or without
   6  *    modification, are permitted provided that the following conditions are met:
   7  *    1. Redistributions of source code must retain the above copyright
   8  *       notice, this list of conditions and the following disclaimer.
   9  *    2. Redistributions in binary form must reproduce the above copyright
  10  *       notice, this list of conditions and the following disclaimer in the
  11  *       documentation and/or other materials provided with the distribution.
  12  *    3. Neither the name of the copyright holder nor the
  13  *       names of its contributors may be used to endorse or promote products
  14  *       derived from this software without specific prior written permission.
  15  *
  16  *    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
  17  *    AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18  *    IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19  *    ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
  20  *    LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  21  *    CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  22  *    SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  23  *    INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  24  *    CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  25  *    ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  26  *    POSSIBILITY OF SUCH DAMAGE.
  27  */
  28
  29 /**
  30  * @file
  31  * This file define logging interface.
  32  */
  33 #ifndef OTBR_COMMON_LOGGING_HPP_
  34 #define OTBR_COMMON_LOGGING_HPP_
  35
  36 #include "openthread-br/config.h"
  37
  38 #include <stdarg.h>
  39 #include <stddef.h>
  40
  41 #include "common/types.hpp"
  42
  43 /**
  44  * Logging level, which is identical to syslog
  45  *
  46  */
  47 enum
  48 {
  49     OTBR_LOG_EMERG,   /* system is unusable */
  50     OTBR_LOG_ALERT,   /* action must be taken immediately */
  51     OTBR_LOG_CRIT,    /* critical conditions */
  52     OTBR_LOG_ERR,     /* error conditions */
  53     OTBR_LOG_WARNING, /* warning conditions */
  54     OTBR_LOG_NOTICE,  /* normal but significant condition */
  55     OTBR_LOG_INFO,    /* informational */
  56     OTBR_LOG_DEBUG,   /* debug-level messages */
  57 };
  58
  59 /**
  60  * Get current log level
  61  */
  62 int otbrLogGetLevel(void);
  63
  64 /**
  65  * Control log to syslog
  66  *
  67  * @param[in] enable true to log to/via syslog
  68  *
  69  */
  70 void otbrLogEnableSyslog(bool aEnabled);
  71
  72 /**
  73  * This function initialize the logging service.
  74  *
  75  * @param[in]   aIdent          Identity of the logger.
  76  * @param[in]   aLevel          Log level of the logger.
  77  * @param[in]   aPrintStderr    Whether to log to stderr.
  78  *
  79  */
  80 void otbrLogInit(const char *aIdent, int aLevel, bool aPrintStderr);
  81
  82 /**
  83  * This function log at level @p aLevel.
  84  *
  85  * @param[in]   aLevel  Log level of the logger.
  86  * @param[in]   aFormat Format string as in printf.
  87  *
  88  */
  89 void otbrLog(int aLevel, const char *aFormat, ...);
  90
  91 /**
  92  * This macro log a action result according to @p aError.
  93  *
  94  * If @p aError is OTBR_ERROR_NONE, the log level will be OTBR_LOG_INFO,
  95  * otherwise OTBR_LOG_WARNING.
  96  *
  97  * @param[in]   aError  The action result.
  98  * @param[in]   aFormat Format string as in printf.
  99  *
 100  */
 101 #define otbrLogResult(aError, aFormat, ...)                                                                \
 102     do                                                                                                     \
 103     {                                                                                                      \
 104         otbrError _err = (aError);                                                                         \
 105         otbrLog(_err == OTBR_ERROR_NONE ? OTBR_LOG_INFO : OTBR_LOG_WARNING, aFormat ": %s", ##__VA_ARGS__, \
 106                 otbrErrorString(_err));                                                                    \
 107     } while (0)
 108
 109 /**
 110  * This function log at level @p aLevel.
 111  *
 112  * @param[in]   aLevel  Log level of the logger.
 113  * @param[in]   aFormat Format string as in printf.
 114  *
 115  */
 116 void otbrLogv(int aLevel, const char *aFormat, va_list);
 117
 118 /**
 119  * This function dump memory as hex string at level @p aLevel.
 120  *
 121  * @param[in]   aLevel  Log level of the logger.
 122  * @param[in]   aPrefix String before dumping memory.
 123  * @param[in]   aMemory The pointer to the memory to be dumped.
 124  * @param[in]   aSize   The size of memory in bytes to be dumped.
 125  *
 126  */
 127 void otbrDump(int aLevel, const char *aPrefix, const void *aMemory, size_t aSize);
 128
 129 /**
 130  * This function converts error code to string.
 131  *
 132  * @param[in]   aError      The error code.
 133  *
 134  * @returns The string information of error.
 135  *
 136  */
 137 const char *otbrErrorString(otbrError aError);
 138
 139 /**
 140  * This function deinitializes the logging service.
 141  *
 142  */
 143 void otbrLogDeinit(void);
 144
 145 #endif // OTBR_COMMON_LOGGING_HPP_