syslog-rs 6.5.0

/*-
 * syslog-rs - a syslog client translated from libc to rust
 * 
 * Copyright 2025 Aleksandr Morozov
 * 
 * The syslog-rs crate can be redistributed and/or modified
 * under the terms of either of the following licenses:
 *
 *   1. the Mozilla Public License Version 2.0 (the “MPL”) OR
 *
 *   2. The MIT License (MIT)
 *                     
 *   3. EUROPEAN UNION PUBLIC LICENCE v. 1.2 EUPL © the European Union 2007, 2016
 */

use crate::{error::SyRes, formatters::SyslogFormatter, Priority, SyslogDestination};

/// A trait whcih describes common syslog API. The generic `D` [SyslogDestination] instance
/// contains the information about the destination and from which the syslog instance should 
/// be constructed.
#[allow(dead_code)]
pub trait SyslogApi<F: SyslogFormatter, D: SyslogDestination>: std::fmt::Debug  + 'static
{
    /// Connects the current instance to the syslog server (destination).
    fn connectlog(&self) -> SyRes<()>;

    /// Sets the logmask to filter out the syslog calls.
    /// 
    /// See macroses [LOG_MASK] and [LOG_UPTO] to generate mask
    ///
    /// # Example
    ///
    /// LOG_MASK!(Priority::LOG_EMERG) | LOG_MASK!(Priority::LOG_ERROR)
    ///
    /// or
    ///
    /// ~(LOG_MASK!(Priority::LOG_INFO))
    /// LOG_UPTO!(Priority::LOG_ERROR)
    fn setlogmask(&self, logmask: i32) -> SyRes<i32>;

    /// Closes connection to the syslog server (destination).
    fn closelog(&self) -> SyRes<()>;

    /// Similar to libc, syslog() sends data to syslog server.
    /// 
    /// # Arguments
    ///
    /// * `pri` - a priority [Priority]
    ///
    /// * `fmt` - a formatter [SyslogFormatter] message. In C exists a functions with
    ///     variable argumets amount. In Rust you should create your
    ///     own macros like format!() or use format!()]. The [String] and ref `'static` 
    ///     [str] can be passed directly.
    fn syslog(&self, pri: Priority, fmt: F);

    /// This function can be used to update the facility name, for example
    /// after fork().
    /// 
    /// # Arguments
    /// 
    /// * `ident` - an [Option] optional new identity (up to 48 UTF8 chars)
    ///     If set to [Option::None] would request the program name from OS.
    fn change_identity(&self, ident: Option<&str>) -> SyRes<()>;

    /// Re-opens the connection to the syslog server. Can be used to 
    /// rotate logs(handle SIGHUP).
    /// 
    /// # Returns
    /// 
    /// A [Result] is retured as [SyRes].
    /// 
    /// * [Result::Ok] - with empty inner type.
    /// 
    /// * [Result::Err] - an error code and description 
    fn reconnect(&self) -> SyRes<()>;

    /// Updates the instance's socket. `tap_data` [TapTypeData] should be of
    /// the same variant (type) as current.
    fn update_tap_data(&self, tap_data: D) -> SyRes<()>;
}