166 lines
6.5 KiB
C
166 lines
6.5 KiB
C
/**
|
|
* @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
|
|
* - Short messages are formatted into a stack buffer, longer ones fall back
|
|
* to a heap allocation with the exact required size
|
|
*
|
|
* @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
|
|
|
|
#include "stdio.h"
|
|
#include "string.h"
|
|
#include "stdint.h"
|
|
#include "stdbool.h"
|
|
#include "esp_heap_caps.h"
|
|
#include "esp_err.h"
|
|
#include "esp_log.h"
|
|
#include "lwip/sockets.h"
|
|
|
|
#define ZH_SYSLOG_INIT_CONFIG_DEFAULT() \
|
|
{ \
|
|
.syslog_ip = "192.168.0.1", \
|
|
.syslog_port = 514}
|
|
|
|
#ifdef __cplusplus
|
|
extern "C"
|
|
{
|
|
#endif
|
|
|
|
/**
|
|
* @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_syslog_facility_code_t;
|
|
|
|
/**
|
|
* @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_syslog_severity_code_t;
|
|
|
|
/**
|
|
* @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 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.
|
|
*
|
|
* Creates a UDP socket and configures connection parameters
|
|
* for the remote syslog server.
|
|
*
|
|
* @param[in] config Pointer to syslog client initialization configuration structure (must not be NULL)
|
|
*
|
|
* @return ESP_OK on success
|
|
* @return ESP_ERR_INVALID_ARG if any parameter is NULL, port is out of range, or IP is malformed
|
|
* @return ESP_ERR_INVALID_STATE if client is already initialized
|
|
* @return ESP_FAIL if socket creation fails
|
|
*
|
|
* @note Connection to the network must be established before calling this function.
|
|
* @note Before initializing the syslog client, it is recommended to initialize the zh_syslog_init_config_t structure with default values.
|
|
*/
|
|
esp_err_t zh_syslog_init(const zh_syslog_init_config_t *config);
|
|
|
|
/**
|
|
* @brief Deinitialize syslog client.
|
|
*
|
|
* 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 a syslog message to the configured server.
|
|
*
|
|
* Formats and sends a syslog message according to RFC 5424 structure
|
|
* via the pre-configured UDP socket.
|
|
*
|
|
* @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 (must not be NULL)
|
|
* @param[in] app_name Pointer to application name that generated the message (must not be NULL)
|
|
* @param[in] message Pointer to the message payload to send (must not be NULL)
|
|
*
|
|
* @return ESP_OK on success
|
|
* @return ESP_ERR_INVALID_ARG if hostname, app_name, or message is NULL, or facility/severity is out of range
|
|
* @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);
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif |