doc: updated comment
This commit is contained in:
aZholtikov committed
1 parent
0c4f9297ea
commit
3c233e320f
2 files changed
+103
-56
No files matched your search
+99
-52
@@ -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);
|
||||
|
||||
|
||||
+4
-4
@@ -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)
|
||||
{
|
||||
|
||||
Reference in new issue
Block a user