KSMTP

session.h
1 /*
2  SPDX-FileCopyrightText: 2010 BetterInbox <[email protected]>
3  SPDX-FileContributor: Christophe Laveault <[email protected]>
4  SPDX-FileContributor: Gregory Schlomoff <[email protected]>
5 
6  SPDX-License-Identifier: LGPL-2.1-or-later
7 */
8 
9 #pragma once
10 
11 #include "ksmtp_export.h"
12 #include "sessionuiproxy.h"
13 
14 #include <QObject>
15 
16 namespace KSmtp
17 {
18 class SessionPrivate;
19 class SessionThread;
20 /**
21  * @brief The Session class
22  */
23 class KSMTP_EXPORT Session : public QObject
24 {
25  Q_OBJECT
26 
27 public:
28  enum State {
29  Disconnected = 0, /**< The Session is not connected to the server. */
30  Ready, /**< (internal) */
31  Handshake, /**< (internal) */
32  NotAuthenticated, /**< The Session is ready for login. @sa KSmtp::LoginJob */
33  Authenticated, /**< The Session is ready to send email. @sa KSmtp::SendJob */
34  Quitting /**< (internal) */
35  };
36  Q_ENUM(State)
37 
38  /** Transport encryption for a session. */
40  Unencrypted, ///< Use no encryption.
41  TLS, ///< Use TLS encryption on the socket.
42  STARTTLS ///< Use STARTTLS to upgrade an unencrypted connection to encrypted after the initial handshake.
43  };
44  Q_ENUM(EncryptionMode)
45 
46  /**
47  Creates a new SMTP session to the specified host and port.
48  After creating the session, call setUseNetworkProxy() if necessary
49  and then either open() to open the connection.
50  @sa open()
51  */
52  explicit Session(const QString &hostName, quint16 port, QObject *parent = nullptr);
53  ~Session() override;
54 
55  void setUiProxy(const SessionUiProxy::Ptr &uiProxy);
56  [[nodiscard]] SessionUiProxy::Ptr uiProxy() const;
57 
58  /**
59  Sets whether the SMTP network connection should use the system proxy settings
60 
61  The default is to not use the proxy.
62  */
63  void setUseNetworkProxy(bool useProxy);
64 
65  /**
66  Returns the host name that has been provided in the Session's constructor
67  @sa port()
68  */
69  [[nodiscard]] QString hostName() const;
70 
71  /**
72  Returns the port number that has been provided in the Session's constructor
73  @sa hostName()
74  */
75  [[nodiscard]] quint16 port() const;
76 
77  [[nodiscard]] State state() const;
78 
79  /** Returns the requested encryption mode for this session. */
80  [[nodiscard]] EncryptionMode encryptionMode() const;
81 
82  /** Sets the encryption mode for this session.
83  * Has to be called before @c open().
84  */
85  void setEncryptionMode(EncryptionMode mode);
86 
87  /**
88  Returns true if the SMTP server has indicated that it allows TLS connections, false otherwise.
89  The session must be at least in the NotAuthenticated state. Before that, allowsTls() always
90  returns false.
91 
92  @sa KSmtp::LoginJob::setUseTls()
93  */
94  [[nodiscard]] bool allowsTls() const;
95 
96  /**
97  Returns true if the SMTP server has indicated that it allows Delivery Status Notification (DSN) support, false otherwise.
98  */
99  [[nodiscard]] bool allowsDsn() const;
100 
101  /**
102  @todo: return parsed auth modes, instead of strings.
103  */
104  [[nodiscard]] QStringList availableAuthModes() const;
105 
106  /**
107  Returns the maximum message size in bytes that the server accepts.
108  You can use SendJob::size() to get the size of the message that you are trying to send
109  @sa KSmtp::SendJob::size()
110  */
111  [[nodiscard]] int sizeLimit() const;
112 
113  [[nodiscard]] int socketTimeout() const;
114  void setSocketTimeout(int ms);
115 
116  /**
117  * Custom hostname to send in EHLO/HELO command
118  */
119  void setCustomHostname(const QString &hostname);
120  [[nodiscard]] QString customHostname() const;
121 
122  /**
123  Opens the connection to the server.
124 
125  You should connect to stateChanged() before calling this method, and wait until the session's
126  state is NotAuthenticated (Session is ready for a LoginJob) or Disconnected (connecting to the
127  server failed)
128 
129  Make sure to call @c setEncryptionMode() before.
130 
131  @see setEncryptionMode
132  */
133  void open();
134 
135  /**
136  Requests the server to quit the connection.
137 
138  This sends a "QUIT" command to the server and will not close the connection until
139  it receives a response. That means you should not delete this object right after
140  calling close, instead wait for stateChanged() to change to Disconnected.
141 
142  See RFC 821, Chapter 4.1.1, "QUIT".
143  */
144  void quit();
145 
146 Q_SIGNALS:
147  void stateChanged(KSmtp::Session::State state);
148  void connectionError(const QString &error);
149 
150 private:
151  friend class SessionPrivate;
152  friend class SessionThread;
153  friend class JobPrivate;
154 
155  SessionPrivate *const d;
156 };
157 }
EncryptionMode
Transport encryption for a session.
Definition: session.h:39
The Session class.
Definition: session.h:23
@ Handshake
(internal)
Definition: session.h:31
@ Unencrypted
Use no encryption.
Definition: session.h:40
@ NotAuthenticated
The Session is ready for login.
Definition: session.h:32
@ TLS
Use TLS encryption on the socket.
Definition: session.h:41
@ Authenticated
The Session is ready to send email.
Definition: session.h:33
@ Ready
(internal)
Definition: session.h:30
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Tue Dec 5 2023 03:59:40 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.