KSMTP

session.h
1/*
2 SPDX-FileCopyrightText: 2010 BetterInbox <contact@betterinbox.com>
3 SPDX-FileContributor: Christophe Laveault <christophe@betterinbox.com>
4 SPDX-FileContributor: Gregory Schlomoff <gregory.schlomoff@gmail.com>
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
16namespace KSmtp
17{
18class SessionPrivate;
19class SessionThread;
20/**
21 * @brief The Session class
22 */
23class KSMTP_EXPORT Session : public QObject
24{
25 Q_OBJECT
26
27public:
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
146Q_SIGNALS:
147 void stateChanged(KSmtp::Session::State state);
148 void connectionError(const QString &error);
149
150private:
151 friend class SessionPrivate;
152 friend class SessionThread;
153 friend class JobPrivate;
154
155 SessionPrivate *const d;
156};
157}
The Session class.
Definition session.h:24
@ Authenticated
The Session is ready to send email.
Definition session.h:33
@ Ready
(internal)
Definition session.h:30
@ Handshake
(internal)
Definition session.h:31
@ NotAuthenticated
The Session is ready for login.
Definition session.h:32
EncryptionMode
Transport encryption for a session.
Definition session.h:39
@ Unencrypted
Use no encryption.
Definition session.h:40
@ TLS
Use TLS encryption on the socket.
Definition session.h:41
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri Dec 6 2024 12:09:19 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.