From 3c233e320ff4b98f328e0b58ad32348aff61c79b Mon Sep 17 00:00:00 2001 From: Alexey Zholtikov Date: Sun, 16 Aug 2026 07:57:41 +0300 Subject: [PATCH] doc: updated comment --- include/zh_syslog.h | 151 +++++++++++++++++++++++++++++--------------- zh_syslog.c | 8 +-- 2 files changed, 103 insertions(+), 56 deletions(-) diff --git a/include/zh_syslog.h b/include/zh_syslog.h index 3f16093..b98a7fd 100644 --- a/include/zh_syslog.h +++ b/include/zh_syslog.h @@ -1,5 +1,20 @@ /** * @file zh_syslog.h + * + * @brief ESP-IDF syslog UDP client library for sending log messages to a remote syslog server. + * + * Lightweight implementation of RFC 5424-compatible syslog client using UDP datagrams. + * Designed for ESP32/ESP-IDF platforms with FreeRTOS support. + * + * Key features: + * - Support for all standard syslog facility codes (0-23) + * - Support for all standard syslog severity levels (0-7) + * - RFC 5424 format message generation + * - Thread-safe initialization and deinitialization + * - MALLOC_CAP_8BIT memory allocation for DMA compatibility + * + * @note Connection to the network must be established before calling zh_syslog_init(). + * @warning This library does not guarantee message delivery (UDP is connectionless). */ #pragma once @@ -13,7 +28,7 @@ #include "lwip/netdb.h" /** - * @brief Syslog client initial default values. + * @brief Default syslog client initialization configuration. */ #define ZH_SYSLOG_INIT_CONFIG_DEFAULT() \ { \ @@ -26,92 +41,124 @@ extern "C" #endif /** - * @brief Enumeration of possible syslog facility codes. + * @brief Syslog facility codes (RFC 5424). + * + * Defines standard facility values ranging from 0 to 23. + * Facilities 0-22 are standardized by RFC 5424. + * Facilities 16-23 (LOCAL0-LOCAL7) are reserved for local/custom use. */ typedef enum { - ZH_KERN, /*!< Kernel messages. */ - ZH_USER, /*!< User-level messages. */ - ZH_MAIL, /*!< Mail system. */ - ZH_DAEMON, /*!< System daemons. */ - ZH_AUTH, /*!< Security/authorization messages. */ - ZH_SYSLOG, /*!< Messages generated internally by syslogd. */ - ZH_LPR, /*!< Line printer subsystem. */ - ZH_NEWS, /*!< Network news subsystem. */ - ZH_UUCP, /*!< UUCP subsystem. */ - ZH_CRON, /*!< Cron subsystem. */ - ZH_AUTHPRIV, /*!< Security/authorization messages. */ - ZH_FTP, /*!< FTP daemon. */ - ZH_NTP, /*!< NTP subsystem. */ - ZH_SECURITY, /*!< Log audit. */ - ZH_CONSOLE, /*!< Log alert. */ - ZH_SOLARIS_CRON, /*!< Scheduling daemon. */ - ZH_LOCAL0, /*!< Local use 0. */ - ZH_LOCAL1, /*!< Local use 1. */ - ZH_LOCAL2, /*!< Local use 2. */ - ZH_LOCAL3, /*!< Local use 3. */ - ZH_LOCAL4, /*!< Local use 4. */ - ZH_LOCAL5, /*!< Local use 5. */ - ZH_LOCAL6, /*!< Local use 6. */ - ZH_LOCAL7, /*!< Local use 7. */ + ZH_KERN, /*!< Kernel messages */ + ZH_USER, /*!< User-level messages */ + ZH_MAIL, /*!< Mail system */ + ZH_DAEMON, /*!< System daemons */ + ZH_AUTH, /*!< Security/authorization messages */ + ZH_SYSLOG, /*!< Messages generated internally by syslogd */ + ZH_LPR, /*!< Line printer subsystem */ + ZH_NEWS, /*!< Network news subsystem */ + ZH_UUCP, /*!< UUCP subsystem */ + ZH_CRON, /*!< Cron subsystem */ + ZH_AUTHPRIV, /*!< Security/authorization messages */ + ZH_FTP, /*!< FTP daemon */ + ZH_NTP, /*!< NTP subsystem */ + ZH_SECURITY, /*!< Log audit */ + ZH_CONSOLE, /*!< Log alert */ + ZH_SOLARIS_CRON, /*!< Scheduling daemon */ + ZH_LOCAL0, /*!< Local use 0 */ + ZH_LOCAL1, /*!< Local use 1 */ + ZH_LOCAL2, /*!< Local use 2 */ + ZH_LOCAL3, /*!< Local use 3 */ + ZH_LOCAL4, /*!< Local use 4 */ + ZH_LOCAL5, /*!< Local use 5 */ + ZH_LOCAL6, /*!< Local use 6 */ + ZH_LOCAL7, /*!< Local use 7 */ } zh_syslog_facility_code_t; /** - * @brief Enumeration of possible syslog severity codes. + * @brief Syslog severity codes (RFC 5424). + * + * Defines eight severity levels from 0 (most severe) to 7 (least severe). + * Level 0 (EMERG) indicates a system is unusable. + * Level 7 (DEBUG) indicates debug-level diagnostic information. */ typedef enum { - ZH_EMERG, /*!< System is unusable. */ - ZH_ALERT, /*!< Action must be taken immediately. */ - ZH_CRIT, /*!< Critical conditions. */ - ZH_ERR, /*!< Error conditions. */ - ZH_WARNING, /*!< Warning conditions. */ - ZH_NOTICE, /*!< Normal but significant condition. */ - ZH_INFO, /*!< Informational messages. */ - ZH_DEBUG /*!< Debug-level messages. */ + ZH_EMERG, /*!< System is unusable */ + ZH_ALERT, /*!< Action must be taken immediately */ + ZH_CRIT, /*!< Critical conditions */ + ZH_ERR, /*!< Error conditions */ + ZH_WARNING, /*!< Warning conditions */ + ZH_NOTICE, /*!< Normal but significant condition */ + ZH_INFO, /*!< Informational messages */ + ZH_DEBUG /*!< Debug-level messages */ } zh_syslog_severity_code_t; /** - * @brief Structure for initial initialization of syslog client. + * @brief Syslog client initialization configuration structure. + * + * Contains network parameters required to establish connection + * to the remote syslog server. + * + * @note IP address must be a valid IPv4 string (e.g., "192.168.1.1"). + * Maximum length is 15 characters plus null terminator (16 bytes). + * @warning Port value should be within valid range (typically 514 for syslog). */ typedef struct { - char syslog_ip[16]; /*!< Syslog server IP address. */ - uint32_t syslog_port; /*!< Syslog server port. */ + char syslog_ip[16]; /*!< Syslog server IPv4 address as a null-terminated string */ + uint32_t syslog_port; /*!< Syslog server UDP port number (e.g., 514) */ } zh_syslog_init_config_t; /** * @brief Initialize syslog client. * - * @param[in] config Pointer to syslog client initialized configuration structure. Can point to a temporary variable. + * Creates a UDP socket and configures connection parameters + * for the remote syslog server. * - * @attention Connection to the network must be established first. + * @param[in] config Pointer to syslog client initialization configuration structure. Can point to a temporary variable * + * @return ESP_OK on success + * @return ESP_ERR_INVALID_ARG if config is NULL + * @return ESP_FAIL if socket creation fails + * + * @note Connection to the network must be established before calling this function. * @note Before initialize the syslog client recommend initialize zh_syslog_init_config_t structure with default values. - * - * @code zh_syslog_init_config_t config = ZH_SYSLOG_INIT_CONFIG_DEFAULT() @endcode - * - * @return ESP_OK if success or an error code otherwise. */ esp_err_t zh_syslog_init(const zh_syslog_init_config_t *config); /** * @brief Deinitialize syslog client. * - * @return ESP_OK if success or an error code otherwise. + * Closes the UDP socket and releases resources. + * After calling this function, zh_syslog_init() must be called again + * before any subsequent zh_syslog_send() calls. + * + * @return ESP_OK on success + * @return ESP_ERR_INVALID_STATE if zh_syslog_init() was not called previously */ esp_err_t zh_syslog_deinit(void); /** - * @brief Send message to syslog server. + * @brief Send a syslog message to the configured server. * - * @param[in] facility Syslog facility code. - * @param[in] severity Syslog severity code. - * @param[in] hostname Pointer to device that generated the message. Only alphanumeric characters without spaces. - * @param[in] app_name Pointer to application that generated the message. Only alphanumeric characters without spaces. - * @param[in] message Pointer to message for send. + * Formats and sends a syslog message according to RFC 5424 structure + * via the pre-configured UDP socket. * - * @return ESP_OK if success or an error code otherwise. + * @param[in] facility Syslog facility code (0-23) + * @param[in] severity Syslog severity code (0-7) + * @param[in] hostname Pointer to device hostname that generated the message. Only alphanumeric characters without spaces + * @param[in] app_name Pointer to application name that generated the message. Only alphanumeric characters without spaces + * @param[in] message Pointer to the message payload to send + * + * @return ESP_OK on success + * @return ESP_ERR_INVALID_ARG if hostname, app_name, or message is NULL + * @return ESP_ERR_INVALID_STATE if zh_syslog_init() was not called previously + * @return ESP_ERR_NO_MEM if memory allocation fails + * @return ESP_FAIL if UDP send operation fails + * + * @note This function is not thread-safe. Caller must ensure mutual exclusion + * if multiple tasks may call this function concurrently. */ esp_err_t zh_syslog_send(const zh_syslog_facility_code_t facility, const zh_syslog_severity_code_t severity, const char *hostname, const char *app_name, const char *message); diff --git a/zh_syslog.c b/zh_syslog.c index 9b3ab6a..11281f0 100644 --- a/zh_syslog.c +++ b/zh_syslog.c @@ -13,10 +13,10 @@ static const char *TAG = "zh_syslog"; -static zh_syslog_init_config_t _init_config = {0}; -static struct sockaddr_in _syslog_server = {0}; -volatile static int _socket = 0; -volatile static bool _is_initialized = false; +static zh_syslog_init_config_t _init_config = {0}; /*!< Syslog client initialization configuration (internal copy) */ +static struct sockaddr_in _syslog_server = {0}; /*!< Pre-configured syslog server address */ +volatile static int _socket = 0; /*!< UDP socket file descriptor */ +volatile static bool _is_initialized = false; /*!< Initialization status flag */ esp_err_t zh_syslog_init(const zh_syslog_init_config_t *config) {