File indexing completed on 2024-05-12 05:21:35
0001 /* 0002 SPDX-FileCopyrightText: 2010 BetterInbox <contact@betterinbox.com> 0003 SPDX-FileContributor: Christophe Laveault <christophe@betterinbox.com> 0004 SPDX-FileContributor: Gregory Schlomoff <gregory.schlomoff@gmail.com> 0005 0006 SPDX-License-Identifier: LGPL-2.1-or-later 0007 */ 0008 0009 #pragma once 0010 0011 #include "ksmtp_export.h" 0012 #include "sessionuiproxy.h" 0013 0014 #include <QObject> 0015 0016 namespace KSmtp 0017 { 0018 class SessionPrivate; 0019 class SessionThread; 0020 /** 0021 * @brief The Session class 0022 */ 0023 class KSMTP_EXPORT Session : public QObject 0024 { 0025 Q_OBJECT 0026 0027 public: 0028 enum State { 0029 Disconnected = 0, /**< The Session is not connected to the server. */ 0030 Ready, /**< (internal) */ 0031 Handshake, /**< (internal) */ 0032 NotAuthenticated, /**< The Session is ready for login. @sa KSmtp::LoginJob */ 0033 Authenticated, /**< The Session is ready to send email. @sa KSmtp::SendJob */ 0034 Quitting /**< (internal) */ 0035 }; 0036 Q_ENUM(State) 0037 0038 /** Transport encryption for a session. */ 0039 enum EncryptionMode { 0040 Unencrypted, ///< Use no encryption. 0041 TLS, ///< Use TLS encryption on the socket. 0042 STARTTLS ///< Use STARTTLS to upgrade an unencrypted connection to encrypted after the initial handshake. 0043 }; 0044 Q_ENUM(EncryptionMode) 0045 0046 /** 0047 Creates a new SMTP session to the specified host and port. 0048 After creating the session, call setUseNetworkProxy() if necessary 0049 and then either open() to open the connection. 0050 @sa open() 0051 */ 0052 explicit Session(const QString &hostName, quint16 port, QObject *parent = nullptr); 0053 ~Session() override; 0054 0055 void setUiProxy(const SessionUiProxy::Ptr &uiProxy); 0056 [[nodiscard]] SessionUiProxy::Ptr uiProxy() const; 0057 0058 /** 0059 Sets whether the SMTP network connection should use the system proxy settings 0060 0061 The default is to not use the proxy. 0062 */ 0063 void setUseNetworkProxy(bool useProxy); 0064 0065 /** 0066 Returns the host name that has been provided in the Session's constructor 0067 @sa port() 0068 */ 0069 [[nodiscard]] QString hostName() const; 0070 0071 /** 0072 Returns the port number that has been provided in the Session's constructor 0073 @sa hostName() 0074 */ 0075 [[nodiscard]] quint16 port() const; 0076 0077 [[nodiscard]] State state() const; 0078 0079 /** Returns the requested encryption mode for this session. */ 0080 [[nodiscard]] EncryptionMode encryptionMode() const; 0081 0082 /** Sets the encryption mode for this session. 0083 * Has to be called before @c open(). 0084 */ 0085 void setEncryptionMode(EncryptionMode mode); 0086 0087 /** 0088 Returns true if the SMTP server has indicated that it allows TLS connections, false otherwise. 0089 The session must be at least in the NotAuthenticated state. Before that, allowsTls() always 0090 returns false. 0091 0092 @sa KSmtp::LoginJob::setUseTls() 0093 */ 0094 [[nodiscard]] bool allowsTls() const; 0095 0096 /** 0097 Returns true if the SMTP server has indicated that it allows Delivery Status Notification (DSN) support, false otherwise. 0098 */ 0099 [[nodiscard]] bool allowsDsn() const; 0100 0101 /** 0102 @todo: return parsed auth modes, instead of strings. 0103 */ 0104 [[nodiscard]] QStringList availableAuthModes() const; 0105 0106 /** 0107 Returns the maximum message size in bytes that the server accepts. 0108 You can use SendJob::size() to get the size of the message that you are trying to send 0109 @sa KSmtp::SendJob::size() 0110 */ 0111 [[nodiscard]] int sizeLimit() const; 0112 0113 [[nodiscard]] int socketTimeout() const; 0114 void setSocketTimeout(int ms); 0115 0116 /** 0117 * Custom hostname to send in EHLO/HELO command 0118 */ 0119 void setCustomHostname(const QString &hostname); 0120 [[nodiscard]] QString customHostname() const; 0121 0122 /** 0123 Opens the connection to the server. 0124 0125 You should connect to stateChanged() before calling this method, and wait until the session's 0126 state is NotAuthenticated (Session is ready for a LoginJob) or Disconnected (connecting to the 0127 server failed) 0128 0129 Make sure to call @c setEncryptionMode() before. 0130 0131 @see setEncryptionMode 0132 */ 0133 void open(); 0134 0135 /** 0136 Requests the server to quit the connection. 0137 0138 This sends a "QUIT" command to the server and will not close the connection until 0139 it receives a response. That means you should not delete this object right after 0140 calling close, instead wait for stateChanged() to change to Disconnected. 0141 0142 See RFC 821, Chapter 4.1.1, "QUIT". 0143 */ 0144 void quit(); 0145 0146 Q_SIGNALS: 0147 void stateChanged(KSmtp::Session::State state); 0148 void connectionError(const QString &error); 0149 0150 private: 0151 friend class SessionPrivate; 0152 friend class SessionThread; 0153 friend class JobPrivate; 0154 0155 SessionPrivate *const d; 0156 }; 0157 }