Events

Event Callback¶

The event callback is called by libESMTP as the SMTP protocol progresses. Some are informational whereas others may be used to alter certain default actions.

The callback function signature varies depending on the event type described below.

void ev_connect_cb(smtp_session_t session, int event_no, void *arg)¶: SMTP_EV_CONNECT event

Parameters

smtp_session_t session: The session.
int event_no: Equal to SMTP_EV_CONNECT
void *arg: application data (closure) specified to smtp_set_eventcb().

Description

The smtp_session has successfully connected to the submission MTA.

void ev_disconnect_cb(smtp_session_t session, int event_no, void *arg)¶: SMTP_EV_DISCONNECT event

Parameters

smtp_session_t session: The session.
int event_no: Equal to SMTP_EV_DISCONNECT
void *arg: application data (closure) specified to smtp_set_eventcb().

Description

The smtp_session has successfully disconnected from the submission MTA. In certain circumstances libESMTP may try connecting to an alternative MTA if the session was rejected. This may happen if multiple A or AAAA records are specified to load balance across multiple servers and an MTA is experiencing excessive load.

void ev_syntaxwarning_cb(smtp_session_t session, int event_no, void *arg, int *quit)¶: SMTP_EV_SYNTAXWARNING event

Parameters

smtp_session_t session: The session.
int event_no: Equal to SMTP_EV_SYNTAXWARNING
void *arg: application data (closure) specified to smtp_set_eventcb().
int *quit: Set non-zero to quit SMTP session, zero to continue.

Description

Issued if the MTA breaks SMTP protocol compliance. Currently only reported if libESMTP is expecting enhanced status codes but does not find them in the server response. By default libESMTP will continue the session but the application can set quit to non-zero to quite the session.

void ev_extna_cb(smtp_session_t session, int event_no, void *arg, int *quit)¶: SMTP_EXTNA_<EXT> extension not available event

Parameters

smtp_session_t session: The session.
int event_no: One of SMTP_EV_EXTNA_DSN, SMTP_EV_EXTNA_CHUNKING or SMTP_EV_EXTNA_ETRN
void *arg: application data (closure) specified to smtp_set_eventcb().
int *quit: Set non-zero to quit SMTP session, zero to continue.

Description

Issued if a requested SMTP extension is not supported by the MTA. event_no is one of SMTP_EV_EXTNA_DSN, SMTP_EV_EXTNA_CHUNKING or SMTP_EV_EXTNA_ETRN. The value pointed to by quit may be used to determine whether the default action is to quit the protocol, and may be set to change this, non-zero means the protocol session will quit.

void ev_extna_2_cb(smtp_session_t session, int event_no, void *arg)¶: SMTP_EXTNA_<EXT> extension not available event

Parameters

smtp_session_t session: The session.
int event_no: One of SMTP_EV_EXTNA_BINARYMIME or SMTP_EV_EXTNA_8BITMIME.
void *arg: application data (closure) specified to smtp_set_eventcb().

Description

Issued if a requested SMTP extension is not supported by the MTA. It is not possible to change default behavious in these cases since the message requires an eight-bit-clean transport which is not available unless one of these extensions are supported.

If event_no is SMTP_EV_EXTNA_STARTTLS, the application has required the use of a TLS connection but this is not supported by the MTA.

void deliverby_expired(smtp_session_t session, int event_no, void *arg, long expiry_difference, int *adjust)¶: SMTP_EV_DELIVERBY_EXPIRED event

Parameters

smtp_session_t session: The session.
int event_no: Equal to SMTP_EV_DELIVERBY_EXPIRED
void *arg: application data (closure) specified to smtp_set_eventcb().
long expiry_difference: difference in seconds between server and requested expiry
int *adjust: set deliver by time to server minimum plus adjust seconds.

Description

Report that mail cannot be delivered by the requested time. Adjust can be used to request a later deliver by time if set greater than zero.

void mailstatus(smtp_session_t session, int event_no, void *arg, const char *mailbox, smtp_message_t message)¶: SMTP_EV_MAILSTATUS event

Parameters

smtp_session_t session: The session.
int event_no: Equal to SMTP_EV_MAILSTATUS
void *arg: application data (closure) specified to smtp_set_eventcb().
const char *mailbox: The reverse path mailbox.
smtp_message_t message: The smtp_message_t

Description

Report MTA status for the MAIL FROM:<> command. The actual status code may be retrieved with smtp_reverse_path_status().

void rcptstatus(smtp_session_t session, int event_no, void *arg, const char *mailbox, smtp_recipient_t recipient)¶: SMTP_EV_RCPTSTATUS event

Parameters

smtp_session_t session: The session.
int event_no: Equal to SMTP_EV_RCPTSTATUS
void *arg: application data (closure) specified to smtp_set_eventcb().
const char *mailbox: The reverse path mailbox.
smtp_recipient_t recipient: The smtp_recipient_t

Description

Report MTA status for the RCPT TO:<> command. The actual status code may be retrieved with smtp_recipient_status().

void messagedata(smtp_session_t session, int event_no, void *arg, smtp_message_t message, int len)¶: SMTP_EV_MESSAGEDATA event

Parameters

smtp_session_t session: The session.
int event_no: Equal to SMTP_EV_MESSAGEDATA
void *arg: application data (closure) specified to smtp_set_eventcb().
smtp_message_t message: the smtp_message_t.
int len: octets transferred.

Description

Report progress of message transfer to application. This event is emitted multiple times as the transfer progresses with len set to the octet count transferred so far.

void messagesent(smtp_session_t session, int event_no, void *arg, smtp_message_t message)¶: SMTP_EV_MESSAGESENT event

Parameters

smtp_session_t session: The session.
int event_no: Equal to SMTP_EV_MESSAGESENT
void *arg: application data (closure) specified to smtp_set_eventcb().
smtp_message_t message: the smtp_message_t.

Description

Report completion of the message transfer. The associated ststus code from the MTA may be retrieved using smtp_message_transfer_status().

void etrnstatus(smtp_session_t session, int event_no, void *arg, int option, const char *domain)¶: SMTP_EV_ETRNSTATUS event

Parameters

smtp_session_t session: The session.
int event_no: Equal to SMTP_EV_ETRNSTATUS
void *arg: application data (closure) specified to smtp_set_eventcb().
int option: the ETRN option character.
const char *domain: the ETRN domain name.

Description

Report ETRN status.