From 57349e7bd9d9414d8ca1fec321a8aca59b517885 Mon Sep 17 00:00:00 2001
From: Linus Jahn <lnj@kaidan.im>
Date: Mon, 29 Jul 2024 16:33:51 +0200
Subject: [PATCH] Client: Document new connection behaviour and SRV record
 handling

---
 src/client/QXmppClient.cpp      | 12 ++++++++++++
 src/client/QXmppConfiguration.h |  4 +++-
 2 files changed, 15 insertions(+), 1 deletion(-)

diff --git a/src/client/QXmppClient.cpp b/src/client/QXmppClient.cpp
index 6df1cc078..97a5f80bf 100644
--- a/src/client/QXmppClient.cpp
+++ b/src/client/QXmppClient.cpp
@@ -224,6 +224,18 @@ bool process(QXmppClient *client, const QList<QXmppClientExtension *> &extension
 /// - QXmppDiscoveryManager
 /// - QXmppEntityTimeManager
 ///
+/// ## Connection details
+///
+/// If no explicit host and port are configured, the client will look up the SRV records of the
+/// domain of the configured JID. Since QXmpp 1.8 both TCP and direct TLS records are looked up
+/// and connection via direct TLS is preferred as it saves the extra round trip from STARTTLS. See
+/// also \xep{0368, SRV records for XMPP over TLS}.
+///
+/// On connection errors the other SRV records are tested too (if multiple are available).
+///
+/// For servers without SRV records or if looking up the records did not succeed, domain and the
+/// default port of 5223 (TLS) and 5222 (TCP/STARTTLS) are tried.
+///
 /// ## Usage of FAST token-based authentication
 ///
 /// QXmpp uses \xep{0484, Fast Authentication Streamlining Tokens} if enabled and supported by the
diff --git a/src/client/QXmppConfiguration.h b/src/client/QXmppConfiguration.h
index dcf24c986..b00bcd0ab 100644
--- a/src/client/QXmppConfiguration.h
+++ b/src/client/QXmppConfiguration.h
@@ -44,7 +44,9 @@ class QXMPP_EXPORT QXmppConfiguration
         TLSDisabled,     ///< No encryption even if the server offers it.
         TLSRequired,     ///< Encryption must be available, otherwise the
                          ///< connection will not be established.
-        LegacySSL        ///< Use only legacy SSL mode.
+        /// Use direct TLS connection only and connect to configured host and port or domain and
+        /// 5223 or 5222. No SRV records are looked up.
+        LegacySSL
     };
 
     /// An enumeration for various Non-SASL authentication mechanisms available.