用于在 milter 实现中生成 C 回调函数的过程宏。

本库中的属性宏简化了创建 FFI 回调函数的过程，这些回调函数用于配置 Milter。属性宏用于将普通 Rust 函数标记为 milter 回调。然后生成一个 C 函数，安全地将调用委托给 Rust 回调，并在 Rust/C 类型之间进行转换。

回调函数充当“事件处理器”的作用（因此命名为 on_*），用于处理 SMTP 会话期间发生的各种“事件”。对于 milter 协议中的每个阶段，都对应一个 属性宏。

使用方法

本库是 milter 库的依赖项，它导出其命名空间下的所有宏。建议使用 use 宏来自 milter 命名空间，而不是直接依赖此库

use milter::{on_connect, on_close, Milter, Status};

以下部分描述了属性宏的一些附加功能。

原始字符串输入

默认情况下，回调接收类型为 &str 的字符串输入，即 UTF-8 字符串。如果不需要 UTF-8 编码，可以在处理函数签名中用 C 字符串类型 &CStr 替换 &str 以接收原始字节。

将以下示例与 [macro@on_header] 中的示例进行比较。

use std::ffi::CStr;

#[on_header(header_callback)]
fn handle_header(context: Context<()>, name: &CStr, value: &CStr) -> Status {
    //                                       ^^^^^         ^^^^^
    Status::Continue
}

此功能在 &str 出现在回调函数参数中时受支持。

回调结果

回调函数的返回类型可以包裹在milter::Result中。这是一个便利特性：由于大多数上下文API方法返回milter::Result类型，因此可以使用?操作符来解包。

将以下示例与[宏@on_eom]中所示示例进行比较。这段代码片段还演示了通过选择此返回类型来启用?操作符的使用。

#[on_eom(eom_callback)]
fn handle_eom(context: Context<()>) -> milter::Result<Status> {
    //                                 ^^^^^^^^^^^^^^^^^^^^^^
    if let Some(version) = context.api.macro_value("v")? {
        println!("{}", version);
    }

    Ok(Status::Continue)
}

此功能支持所有回调函数。

失败模式

从回调函数返回的Err结果会导致临时失败（Status::Tempfail）响应被返回给MTA。然后milter继续正常处理请求。

另一方面，恐慌会导致milter立即关闭。所有阶段都会切换到返回失败响应，并不再执行处理函数（然而，目前执行中的回调处理程序被允许完成）。libmilter工作进程被终止，当前阻塞的Milter::run调用返回。在close或其他阶段的清理逻辑不会被执行。

恐慌行为背后的原则，正如其他地方一样，是在libmilter和FFI接口的限制下尽可能快速地退出。

上述失败模式提供为便利之用。如果它们不能满足您的需求，请使用显式错误处理。