1 /* 2 * coap_debug.h -- debug utilities 3 * 4 * Copyright (C) 2010-2011,2014 Olaf Bergmann <bergmann@tzi.org> 5 * 6 * SPDX-License-Identifier: BSD-2-Clause 7 * 8 * This file is part of the CoAP library libcoap. Please see README for terms 9 * of use. 10 */ 11 12 #ifndef COAP_DEBUG_H_ 13 #define COAP_DEBUG_H_ 14 15 /** 16 * @defgroup logging Logging Support 17 * API functions for logging support 18 * @{ 19 */ 20 21 #ifndef COAP_DEBUG_FD 22 /** 23 * Used for output for @c LOG_DEBUG to @c LOG_ERR. 24 */ 25 #define COAP_DEBUG_FD stdout 26 #endif 27 28 #ifndef COAP_ERR_FD 29 /** 30 * Used for output for @c LOG_CRIT to @c LOG_EMERG. 31 */ 32 #define COAP_ERR_FD stderr 33 #endif 34 35 #ifdef HAVE_SYSLOG_H 36 #include <syslog.h> 37 /** 38 * Logging type. One of LOG_* from @b syslog. 39 */ 40 typedef short coap_log_t; 41 /* 42 LOG_DEBUG+2 gives ciphers in GnuTLS 43 Use COAP_LOG_CIPHERS to output Cipher Info in OpenSSL etc. 44 */ 45 #define COAP_LOG_CIPHERS (LOG_DEBUG+2) 46 #else /* !HAVE_SYSLOG_H */ 47 /** Pre-defined log levels akin to what is used in \b syslog 48 with LOG_CIPHERS added. */ 49 50 #if !defined(RIOT_VERSION) 51 typedef enum { 52 LOG_EMERG=0, /**< Emergency */ 53 LOG_ALERT, /**< Alert */ 54 LOG_CRIT, /**< Critical */ 55 LOG_ERR, /**< Error */ 56 LOG_WARNING, /**< Warning */ 57 LOG_NOTICE, /**< Notice */ 58 LOG_INFO, /**< Information */ 59 LOG_DEBUG, /**< Debug */ 60 COAP_LOG_CIPHERS=LOG_DEBUG+2 /**< CipherInfo */ 61 } coap_log_t; 62 #else /* RIOT_VERSION */ 63 /* RIOT defines a subset of the syslog levels in log.h with different 64 * numeric values. The remaining levels are defined here. Note that 65 * output granularity differs from what would be expected when 66 * adhering to the syslog levels. 67 */ 68 #include <log.h> 69 typedef short coap_log_t; 70 #define LOG_EMERG (0) 71 #define LOG_ALERT (1) 72 #define LOG_CRIT (2) 73 #define LOG_ERR (3) 74 /* LOG_WARNING (4) */ 75 #define LOG_NOTICE (5) 76 /* LOG_INFO (6) */ 77 /* LOG_DEBUG (7) */ 78 #define COAP_LOG_CIPHERS (9) 79 #endif /* RIOT_VERSION */ 80 81 #endif /* !HAVE_SYSLOG_H */ 82 83 /** 84 * Get the current logging level. 85 * 86 * @return One of the LOG_* values. 87 */ 88 coap_log_t coap_get_log_level(void); 89 90 /** 91 * Sets the log level to the specified value. 92 * 93 * @param level One of the LOG_* values. 94 */ 95 void coap_set_log_level(coap_log_t level); 96 97 /** 98 * Logging callback handler definition. 99 * 100 * @param level One of the LOG_* values. 101 * @param message Zero-terminated string message to log. 102 */ 103 typedef void (*coap_log_handler_t) (coap_log_t level, const char *message); 104 105 /** 106 * Add a custom log callback handler. 107 * 108 * @param handler The logging handler to use or @p NULL to use default handler. 109 */ 110 void coap_set_log_handler(coap_log_handler_t handler); 111 112 /** 113 * Get the library package name. 114 * 115 * @return Zero-terminated string with the name of this library. 116 */ 117 const char *coap_package_name(void); 118 119 /** 120 * Get the library package version. 121 * 122 * @return Zero-terminated string with the library version. 123 */ 124 const char *coap_package_version(void); 125 126 /** 127 * Writes the given text to @c COAP_ERR_FD (for @p level <= @c LOG_CRIT) or @c 128 * COAP_DEBUG_FD (for @p level >= @c LOG_ERR). The text is output only when 129 * @p level is below or equal to the log level that set by coap_set_log_level(). 130 * 131 * Internal function. 132 * 133 * @param level One of the LOG_* values. 134 & @param format The format string to use. 135 */ 136 #if (defined(__GNUC__)) 137 void coap_log_impl(coap_log_t level, 138 const char *format, ...) __attribute__ ((format(printf, 2, 3))); 139 #else 140 void coap_log_impl(coap_log_t level, const char *format, ...); 141 #endif 142 143 #ifndef coap_log 144 /** 145 * Logging function. 146 * Writes the given text to @c COAP_ERR_FD (for @p level <= @c LOG_CRIT) or @c 147 * COAP_DEBUG_FD (for @p level >= @c LOG_ERR). The text is output only when 148 * @p level is below or equal to the log level that set by coap_set_log_level(). 149 * 150 * @param level One of the LOG_* values. 151 */ 152 #define coap_log(level, ...) do { \ 153 if ((int)((level))<=(int)coap_get_log_level()) \ 154 coap_log_impl((level), __VA_ARGS__); \ 155 } while(0) 156 #endif 157 158 #include "pdu.h" 159 160 /** 161 * Defines the output mode for the coap_show_pdu() function. 162 * 163 * @param use_fprintf @p 1 if the output is to use fprintf() (the default) 164 * @p 0 if the output is to use coap_log(). 165 */ 166 void coap_set_show_pdu_output(int use_fprintf); 167 168 /** 169 * Display the contents of the specified @p pdu. 170 * Note: The output method of coap_show_pdu() is dependent on the setting of 171 * coap_set_show_pdu_output(). 172 * 173 * @param level The required minimum logging level. 174 * @param pdu The PDU to decode. 175 */ 176 void coap_show_pdu(coap_log_t level, const coap_pdu_t *pdu); 177 178 /** 179 * Display the current (D)TLS library linked with and built for version. 180 * 181 * @param level The required minimum logging level. 182 */ 183 void coap_show_tls_version(coap_log_t level); 184 185 /** 186 * Build a string containing the current (D)TLS library linked with and 187 * built for version. 188 * 189 * @param buffer The buffer to put the string into. 190 * @param bufsize The size of the buffer to put the string into. 191 * 192 * @return A pointer to the provided buffer. 193 */ 194 char *coap_string_tls_version(char *buffer, size_t bufsize); 195 196 /** 197 * Build a string containing the current (D)TLS library support 198 * 199 * @param buffer The buffer to put the string into. 200 * @param bufsize The size of the buffer to put the string into. 201 * 202 * @return A pointer to the provided buffer. 203 */ 204 char *coap_string_tls_support(char *buffer, size_t bufsize); 205 206 /** 207 * Print the address into the defined buffer. 208 * 209 * Internal Function. 210 * 211 * @param address The address to print. 212 * @param buffer The buffer to print into. 213 * @param size The size of the buffer to print into. 214 * 215 * @return The amount written into the buffer. 216 */ 217 size_t coap_print_addr(const coap_address_t *address, 218 unsigned char *buffer, size_t size); 219 220 /** @} */ 221 222 /** 223 * Set the packet loss level for testing. This can be in one of two forms. 224 * 225 * Percentage : 0% to 100%. Use the specified probability. 226 * 0% is send all packets, 100% is drop all packets. 227 * 228 * List: A comma separated list of numbers or number ranges that are the 229 * packets to drop. 230 * 231 * @param loss_level The defined loss level (percentage or list). 232 * 233 * @return @c 1 If loss level set, @c 0 if there is an error. 234 */ 235 int coap_debug_set_packet_loss(const char *loss_level); 236 237 /** 238 * Check to see whether a packet should be sent or not. 239 * 240 * Internal function 241 * 242 * @return @c 1 if packet is to be sent, @c 0 if packet is to be dropped. 243 */ 244 int coap_debug_send_packet(void); 245 246 247 #endif /* COAP_DEBUG_H_ */ 248