api: Deprecate old server config keys that were replaced by add_or_update_transport()

Author: Hocuri

deltachat-ffi/deltachat.h

@@ -390,26 +390,9 @@ char*           dc_get_blobdir               (const dc_context_t* context);
 /**
  * Configure the context. The configuration is handled by key=value pairs as:
  *
- * - `addr`         = Email address to use for configuration.
- *                    If dc_configure() fails this is not the email address actually in use.
- *                    Use `configured_addr` to find out the email address actually in use.
- * - `configured_addr` = Email address actually in use.
+ * - `configured_addr` = Email address in use.
  *                    Unless for testing, do not set this value using dc_set_config().
  *                    Instead, set `addr` and call dc_configure().
- * - `mail_server`  = IMAP-server, guessed if left out
- * - `mail_user`    = IMAP-username, guessed if left out
- * - `mail_pw`      = IMAP-password (always needed)
- * - `mail_port`    = IMAP-port, guessed if left out
- * - `mail_security`= IMAP-socket, one of @ref DC_SOCKET, defaults to #DC_SOCKET_AUTO
- * - `send_server`  = SMTP-server, guessed if left out
- * - `send_user`    = SMTP-user, guessed if left out
- * - `send_pw`      = SMTP-password, guessed if left out
- * - `send_port`    = SMTP-port, guessed if left out
- * - `send_security`= SMTP-socket, one of @ref DC_SOCKET, defaults to #DC_SOCKET_AUTO
- * - `server_flags` = IMAP-/SMTP-flags as a combination of @ref DC_LP flags, guessed if left out
- * - `proxy_enabled` = Proxy enabled. Disabled by default.
- * - `proxy_url` = Proxy URL. May contain multiple URLs separated by newline, but only the first one is used.
- * - `imap_certificate_checks` = how to check IMAP and SMTP certificates, one of the @ref DC_CERTCK flags, defaults to #DC_CERTCK_AUTO (0)
  * - `displayname`  = Own name to use when sending messages. MUAs are allowed to spread this way e.g. using CC, defaults to empty
  * - `selfstatus`   = Own status to display, e.g. in e-mail footers, defaults to empty
  * - `selfavatar`   = File containing avatar. Will immediately be copied to the 
@@ -512,6 +495,27 @@ char*           dc_get_blobdir               (const dc_context_t* context);
  *                       1 = Contacts (default, does not include contact requests),
  *                       2 = Nobody (calls never result in a notification).
  *
+ * Also, there are configs that are only needed
+ * if you want to use the deprecated dc_configure() API, such as:
+ *
+ * - `addr`         = Email address to use for configuration.
+ *                    If dc_configure() fails this is not the email address actually in use.
+ *                    Use `configured_addr` to find out the email address actually in use.
+ * - `mail_server`  = IMAP-server, guessed if left out
+ * - `mail_user`    = IMAP-username, guessed if left out
+ * - `mail_pw`      = IMAP-password (always needed)
+ * - `mail_port`    = IMAP-port, guessed if left out
+ * - `mail_security`= IMAP-socket, one of @ref DC_SOCKET, defaults to #DC_SOCKET_AUTO
+ * - `send_server`  = SMTP-server, guessed if left out
+ * - `send_user`    = SMTP-user, guessed if left out
+ * - `send_pw`      = SMTP-password, guessed if left out
+ * - `send_port`    = SMTP-port, guessed if left out
+ * - `send_security`= SMTP-socket, one of @ref DC_SOCKET, defaults to #DC_SOCKET_AUTO
+ * - `server_flags` = IMAP-/SMTP-flags as a combination of @ref DC_LP flags, guessed if left out
+ * - `proxy_enabled` = Proxy enabled. Disabled by default.
+ * - `proxy_url` = Proxy URL. May contain multiple URLs separated by newline, but only the first one is used.
+ * - `imap_certificate_checks` = how to check IMAP and SMTP certificates, one of the @ref DC_CERTCK flags, defaults to #DC_CERTCK_AUTO (0)
+
  * If you want to retrieve a value, use dc_get_config().
  *
  * @memberof dc_context_t
@@ -698,6 +702,12 @@ int              dc_get_push_state           (dc_context_t* context);
 
 /**
  * Configure a context.
+ *
+ * This way of configuring a context is deprecated,
+ * and does not allow to configure multiple transports.
+ * If you can, use the JSON-RPC API (../deltachat-jsonrpc/src/api.rs)
+ * `add_or_update_transport()`/`addOrUpdateTransport()` instead.
+ *
  * During configuration IO must not be started,
  * if needed stop IO using dc_accounts_stop_io() or dc_stop_io() first.
  * If the context is already configured,

src/config.rs

@@ -42,45 +42,85 @@ use crate::{constants, stats};
 )]
 #[strum(serialize_all = "snake_case")]
 pub enum Config {
+    /// Deprecated(2026-04).
+    /// Use ConfiguredAddr, [`crate::login_param::EnteredLoginParam`],
+    /// or add_transport{from_qr}()/list_transports() instead.
+    ///
     /// Email address, used in the `From:` field.
     Addr,
 
+    /// Deprecated(2026-04).
+    /// Use EnteredLoginParam and add_transport{from_qr}()/list_transports() instead.
+    ///
     /// IMAP server hostname.
     MailServer,
 
+    /// Deprecated(2026-04).
+    /// Use EnteredLoginParam and add_transport{from_qr}()/list_transports() instead.
+    ///
     /// IMAP server username.
     MailUser,
 
+    /// Deprecated(2026-04).
+    /// Use EnteredLoginParam and add_transport{from_qr}()/list_transports() instead.
+    ///
     /// IMAP server password.
     MailPw,
 
+    /// Deprecated(2026-04).
+    /// Use EnteredLoginParam and add_transport{from_qr}()/list_transports() instead.
+    ///
     /// IMAP server port.
     MailPort,
 
+    /// Deprecated(2026-04).
+    /// Use EnteredLoginParam and add_transport{from_qr}()/list_transports() instead.
+    ///
     /// IMAP server security (e.g. TLS, STARTTLS).
     MailSecurity,
 
+    /// Deprecated(2026-04).
+    /// Use EnteredLoginParam and add_transport{from_qr}()/list_transports() instead.
+    ///
     /// How to check TLS certificates.
     ///
     /// "IMAP" in the name is for compatibility,
     /// this actually applies to both IMAP and SMTP connections.
     ImapCertificateChecks,
 
+    /// Deprecated(2026-04).
+    /// Use EnteredLoginParam and add_transport{from_qr}()/list_transports() instead.
+    ///
     /// SMTP server hostname.
     SendServer,
 
+    /// Deprecated(2026-04).
+    /// Use EnteredLoginParam and add_transport{from_qr}()/list_transports() instead.
+    ///
     /// SMTP server username.
     SendUser,
 
+    /// Deprecated(2026-04).
+    /// Use EnteredLoginParam and add_transport{from_qr}()/list_transports() instead.
+    ///
     /// SMTP server password.
     SendPw,
 
+    /// Deprecated(2026-04).
+    /// Use EnteredLoginParam and add_transport{from_qr}()/list_transports() instead.
+    ///
     /// SMTP server port.
     SendPort,
 
+    /// Deprecated(2026-04).
+    /// Use EnteredLoginParam and add_transport{from_qr}()/list_transports() instead.
+    ///
     /// SMTP server security (e.g. TLS, STARTTLS).
     SendSecurity,
 
+    /// Deprecated(2026-04).
+    /// Use EnteredLoginParam and add_transport{from_qr}()/list_transports() instead.
+    ///
     /// Whether to use OAuth 2.
     ///
     /// Historically contained other bitflags, which are now deprecated.
@@ -180,32 +220,47 @@ pub enum Config {
     /// The primary email address.
     ConfiguredAddr,
 
+    /// Deprecated(2026-04).
+    /// Use ConfiguredLoginParam and add_transport{from_qr}()/list_transports() instead.
+    ///
     /// List of configured IMAP servers as a JSON array.
     ConfiguredImapServers,
 
+    /// Deprecated(2026-04).
+    /// Use ConfiguredLoginParam and add_transport{from_qr}()/list_transports() instead.
+    ///
     /// Configured IMAP server hostname.
     ///
     /// This is replaced by `configured_imap_servers` for new configurations.
     ConfiguredMailServer,
 
-    /// Configured IMAP server port.
+    /// Deprecated(2026-04).
+    /// Use ConfiguredLoginParam and add_transport{from_qr}()/list_transports() instead.
     ///
-    /// This is replaced by `configured_imap_servers` for new configurations.
+    /// Configured IMAP server port.
     ConfiguredMailPort,
 
-    /// Configured IMAP server security (e.g. TLS, STARTTLS).
+    /// Deprecated(2026-04).
+    /// Use ConfiguredLoginParam and add_transport{from_qr}()/list_transports() instead.
     ///
-    /// This is replaced by `configured_imap_servers` for new configurations.
+    /// Configured IMAP server security (e.g. TLS, STARTTLS).
     ConfiguredMailSecurity,
 
-    /// Configured IMAP server username.
+    /// Deprecated(2026-04).
+    /// Use ConfiguredLoginParam and add_transport{from_qr}()/list_transports() instead.
     ///
-    /// This is set if user has configured username manually.
+    /// Configured IMAP server username.
     ConfiguredMailUser,
 
+    /// Deprecated(2026-04).
+    /// Use ConfiguredLoginParam and add_transport{from_qr}()/list_transports() instead.
+    ///
     /// Configured IMAP server password.
     ConfiguredMailPw,
 
+    /// Deprecated(2026-04).
+    /// Use ConfiguredLoginParam and add_transport{from_qr}()/list_transports() instead.
+    ///
     /// Configured TLS certificate checks.
     /// This option is saved on successful configuration
     /// and should not be modified manually.
@@ -214,32 +269,53 @@ pub enum Config {
     /// but has "IMAP" in the name for backwards compatibility.
     ConfiguredImapCertificateChecks,
 
+    /// Deprecated(2026-04).
+    /// Use ConfiguredLoginParam and add_transport{from_qr}()/list_transports() instead.
+    ///
     /// List of configured SMTP servers as a JSON array.
     ConfiguredSmtpServers,
 
+    /// Deprecated(2026-04).
+    /// Use ConfiguredLoginParam and add_transport{from_qr}()/list_transports() instead.
+    ///
     /// Configured SMTP server hostname.
     ///
     /// This is replaced by `configured_smtp_servers` for new configurations.
     ConfiguredSendServer,
 
+    /// Deprecated(2026-04).
+    /// Use ConfiguredLoginParam and add_transport{from_qr}()/list_transports() instead.
+    ///
     /// Configured SMTP server port.
     ///
     /// This is replaced by `configured_smtp_servers` for new configurations.
     ConfiguredSendPort,
 
+    /// Deprecated(2026-04).
+    /// Use ConfiguredLoginParam and add_transport{from_qr}()/list_transports() instead.
+    ///
     /// Configured SMTP server security (e.g. TLS, STARTTLS).
     ///
     /// This is replaced by `configured_smtp_servers` for new configurations.
     ConfiguredSendSecurity,
 
+    /// Deprecated(2026-04).
+    /// Use ConfiguredLoginParam and add_transport{from_qr}()/list_transports() instead.
+    ///
     /// Configured SMTP server username.
     ///
     /// This is set if user has configured username manually.
     ConfiguredSendUser,
 
+    /// Deprecated(2026-04).
+    /// Use ConfiguredLoginParam and add_transport{from_qr}()/list_transports() instead.
+    ///
     /// Configured SMTP server password.
     ConfiguredSendPw,
 
+    /// Deprecated(2026-04).
+    /// Use ConfiguredLoginParam and add_transport{from_qr}()/list_transports() instead.
+    ///
     /// Whether OAuth 2 is used with configured provider.
     ConfiguredServerFlags,
 
@@ -252,6 +328,9 @@ pub enum Config {
     /// ID of the configured provider from the provider database.
     ConfiguredProvider,
 
+    /// Deprecated(2026-04).
+    /// Use [`Context::is_configured()`] instead.
+    ///
     /// True if account is configured.
     Configured,