Struct milter::ContextApi

pub struct ContextApi { /* fields omitted */ }

An accessor to the set of methods that make up the context API.

The context API is the set of mostly side-effecting operations that affect the current connection.

Action methods

Of the methods that are part of the context API, some are designated action methods. These are the methods that modify the message being processed. They can be called only in the eom milter callback, and must be enabled before use, either using Milter::actions or during negotiation.

The trait ActionContext serves as a representation of the set of action methods.

Implementations

impl ContextApi

pub fn request_macros(&self, stage: Stage, macros: &str) -> Result<()>

Requests that the space-separated macros be made available in the given stage. The set of macros appropriate to use depends on the MTA. Passing the empty string requests that no macros be sent. This method may only be called once for each Stage variant; calls per stage are not cumulative.

This method is part of the negotiation procedure and should therefore only be called in the negotiate stage.

Errors

An error variant is returned if type conversion at the FFI boundary fails, or if the underlying libmilter library returns a failure status.

Examples

context.api.request_macros(Stage::Helo, "{cert_issuer} {cert_subject}")?;

pub fn macro_value(&self, name: &str) -> Result<Option<&str>>

Returns the value for the given macro if present. The set of macros available depends on the stage and the MTA in use.

Errors

If conversion of arguments or return values at the boundary to the libmilter library fails, an error variant is returned.

Examples

let ip_address = context.api.macro_value("{daemon_addr}")?;

pub fn set_error_reply(
    &self,
    code: &str,
    ext_code: Option<&str>,
    msg_lines: Vec<&str>
) -> Result<()>

Sets the default SMTP error reply code for the current connection.

The three-digit SMTP reply code (RFC 5321) may be enhanced with an optional extended status code (RFC 3463), and with an optional multi-line text message.

This setting only takes effect when the first digit of the reply code matches the Status returned from the callback: "4xx" for Tempfail, "5xx" for Reject.

Errors

An error variant is returned if type conversion at the FFI boundary fails, or if the underlying libmilter library returns a failure status.

Examples

context.api.set_error_reply("550", Some("5.7.0"), vec![
    "Access rejected.",
    "Rejection is due to the sending MTA's poor reputation.",
])?;

pub fn replace_sender(
    &self,
    mail_from: &str,
    esmtp_args: Option<&str>
) -> Result<()>

Replaces the envelope sender (MAIL FROM address) of the current message with mail_from. Optional additional ESMTP arguments to the MAIL command may be given in esmtp_args.

This action is enabled with the flag Actions::REPLACE_SENDER.

Errors

An error variant is returned if type conversion at the FFI boundary fails, or if libmilter returns a failure status.

pub fn add_recipient(
    &self,
    rcpt_to: &str,
    esmtp_args: Option<&str>
) -> Result<()>

Adds envelope recipient (RCPT TO address) rcpt_to to the current message. Optional additional ESMTP arguments to the RCPT command may be given in esmtp_args.

This action is enabled with two distinct flags:

• Actions::ADD_RECIPIENT if no ESMTP arguments are specified
• Actions::ADD_RECIPIENT_EXT if additional ESMTP arguments are specified

Errors

An error variant is returned if type conversion at the FFI boundary fails, or if libmilter returns a failure status.

pub fn remove_recipient(&self, rcpt_to: &str) -> Result<()>

Removes envelope recipient (RCPT TO address) rcpt_to from the current message.

This action is enabled with the flag Actions::REMOVE_RECIPIENT.

Errors

An error variant is returned if type conversion at the FFI boundary fails, or if libmilter returns a failure status.

pub fn add_header(&self, name: &str, value: &str) -> Result<()>

Appends a header to the list of headers of the current message. If the header value is to span multiple lines, use \n (followed by whitespace) as the line separator, not \r\n.

This action is enabled with the flag Actions::ADD_HEADER.

Errors

An error variant is returned if type conversion at the FFI boundary fails, or if libmilter returns a failure status.

Examples

context.api.add_header(
    "Content-Type",
    "multipart/signed; micalg=pgp-sha512;\n\
     \tprotocol=\"application/pgp-signature\"; boundary=\"=-=-=\"",
)?;

pub fn insert_header(&self, index: usize, name: &str, value: &str) -> Result<()>

Inserts a header at index in the list of headers of the current message.

When inserting at index 0, the header is inserted in the first position, before the MTA’s own Received header. When inserting at index 1, the header is inserted in the first position, after the MTA’s Received header. However, the MTA’s Received header, being a header not received from the client but generated by the MTA, is invisible to milters: therefore the exact insertion point may be dependent on header modifications done by earlier milters. This is an unfortunate complication inherent in the milter API.

If the header value is to span multiple lines, use \n (followed by whitespace) as the line separator, not \r\n.

This action is enabled with the flag Actions::ADD_HEADER.

Errors

An error variant is returned if type conversion at the FFI boundary fails, or if libmilter returns a failure status.

pub fn replace_header(
    &self,
    name: &str,
    index: usize,
    value: Option<&str>
) -> Result<()>

Replaces (or removes, or appends) a header at the index’th occurrence of headers with the given name for the current message. The index is 1-based (starts at 1).

More precisely,

• replaces the index’th occurrence of headers named name with the specified value;
• if the value is None, the header is instead removed;
• if index is greater than the number of occurrences of headers named name, a new header is instead appended.

If the header value is to span multiple lines, use \n (followed by whitespace) as the line separator, not \r\n.

This action is enabled with the flag Actions::REPLACE_HEADER.

Errors

An error variant is returned if type conversion at the FFI boundary fails, or if libmilter returns a failure status.

pub fn append_body_chunk(&self, content: &[u8]) -> Result<()>

Appends a chunk of bytes to the new message body of the current message.

This method may be called repeatedly: initially empty, the new body is augmented with additional content with each call. If this method is not called, the original message body remains unchanged.

This action is enabled with the flag Actions::REPLACE_BODY.

Errors

An error variant is returned if libmilter returns a failure status.

pub fn quarantine(&self, reason: &str) -> Result<()>

Quarantines the current message for the given reason.

This action is enabled with the flag Actions::QUARANTINE.

Errors

An error variant is returned if type conversion at the FFI boundary fails, or if libmilter returns a failure status.

pub fn signal_progress(&self) -> Result<()>

Signals to the libmilter library that this milter is still active, causing it to reset timeouts.

Errors

An error variant is returned if libmilter returns a failure status.

Trait Implementations

impl ActionContext for ContextApi

fn replace_sender(
    &self,
    mail_from: &str,
    esmtp_args: Option<&str>
) -> Result<()>

Replaces the envelope sender of a message as specified for ContextApi::replace_sender.

fn add_recipient(&self, rcpt_to: &str, esmtp_args: Option<&str>) -> Result<()>

Adds an envelope recipient to a message as specified for ContextApi::add_recipient.

fn remove_recipient(&self, rcpt_to: &str) -> Result<()>

Removes an envelope recipient from a message as specified for ContextApi::remove_recipient.

fn add_header(&self, name: &str, value: &str) -> Result<()>

Appends a header to the list of headers of a message as specified for ContextApi::add_header.

fn insert_header(&self, index: usize, name: &str, value: &str) -> Result<()>

Inserts a header into the list of headers of a message as specified for ContextApi::insert_header.

fn replace_header(
    &self,
    name: &str,
    index: usize,
    value: Option<&str>
) -> Result<()>

Replaces a header in the list of headers of a message as specified for ContextApi::replace_header.

fn append_body_chunk(&self, content: &[u8]) -> Result<()>

Appends a chunk of bytes to the new message body of a message as specified for ContextApi::append_body_chunk.

fn quarantine(&self, reason: &str) -> Result<()>

Quarantines a message as specified for ContextApi::quarantine.

fn signal_progress(&self) -> Result<()>

Signals to the libmilter library that work is in progress as specified for ContextApi::signal_progress.

impl Debug for ContextApi

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl MacroValue for ContextApi

fn macro_value(&self, name: &str) -> Result<Option<&str>>

Returns the value for the given macro as specified for ContextApi::macro_value.

impl SetErrorReply for ContextApi

fn set_error_reply(
    &self,
    code: &str,
    ext_code: Option<&str>,
    msg_lines: Vec<&str>
) -> Result<()>

Sets the SMTP error reply as specified for ContextApi::set_error_reply.