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