From: Stephan Bosch <stephan.bosch@dovecot.fi>
Date: Fri, 23 Feb 2018 19:49:48 +0000 (+0100)
Subject: lib-smtp: client: transaction: Better document the failure handling for incomplete... 
X-Git-Tag: 2.3.9~2232
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=b60769f0d2052e69f04138d18e1174bccd5df56a;p=thirdparty%2Fdovecot%2Fcore.git

lib-smtp: client: transaction: Better document the failure handling for incomplete transactions.
---

diff --git a/src/lib-smtp/smtp-client-transaction.h b/src/lib-smtp/smtp-client-transaction.h
index 9d7c9f1a76..2e2c17a076 100644
--- a/src/lib-smtp/smtp-client-transaction.h
+++ b/src/lib-smtp/smtp-client-transaction.h
@@ -70,7 +70,9 @@ void smtp_client_transaction_start(struct smtp_client_transaction *trans,
 /* Add recipient to the transaction with a RCPT TO command. The
    rcpt_to_callback is called once the server replies to the RCPT TO command.
    If RCPT TO succeeded, the data_callback is called once the server replies
-   to the DATA command.
+   to the DATA command. The data_callback will not be called until
+   smtp_client_transaction_send() is called for the transaction (see
+   below). Until that time, any failure is remembered.
  */
 void smtp_client_transaction_add_rcpt(
 	struct smtp_client_transaction *trans,
@@ -90,11 +92,12 @@ void smtp_client_transaction_add_rcpt(
 		(smtp_client_command_callback_t *)rcpt_callback, \
 		(smtp_client_command_callback_t *)data_callback, context)
 
-/* Start sending input stream as DATA. If any RCPT TO succeeded, the
-   data_callback is called once the server replies to the DATA command.
-   This callback is mainly useful for SMTP, for LMTP it will only yield
-   the reply for the last recipient. This function starts the transaction
-   implicitly. */
+/* Start sending input stream as DATA. This completes the transaction, which
+   means that any pending failures that got recorded before this function was
+   called will be triggered now. If any RCPT TO succeeded, the provided
+   data_callback is called once the server replies to the DATA command. This
+   callback is mainly useful for SMTP, for LMTP it will only yield the reply for
+   the last recipient. This function starts the transaction implicitly. */
 void smtp_client_transaction_send(
 	struct smtp_client_transaction *trans, struct istream *data_input,
 	smtp_client_command_callback_t *data_callback, void *data_context);