1/*
2 * Copyright (C) 2000 Alex Zepeda <zipzippy@sonic.net>
3 * Copyright (C) 2001 George Staikos <staikos@kde.org>
4 * Copyright (C) 2001 Dawit Alemayehu <adawit@kde.org>
5 * Copyright (C) 2007,2008 Andreas Hartmetz <ahartmetz@gmail.com>
6 *
7 * This file is part of the KDE project
8 *
9 * This library is free software; you can redistribute it and/or
10 * modify it under the terms of the GNU Library General Public
11 * License as published by the Free Software Foundation; either
12 * version 2 of the License, or (at your option) any later version.
13 *
14 * This library is distributed in the hope that it will be useful,
15 * but WITHOUT ANY WARRANTY; without even the implied warranty of
16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
17 * Library General Public License for more details.
18 *
19 * You should have received a copy of the GNU Library General Public License
20 * along with this library; see the file COPYING.LIB. If not, write to
21 * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
22 * Boston, MA 02110-1301, USA.
23 */
24
25#ifndef _TCP_SLAVEBASE_H
26#define _TCP_SLAVEBASE_H
27
28#include <sys/types.h>
29#include <stdio.h>
30
31#include <kio/slavebase.h>
32
33class QIODevice;
34
35namespace KIO {
36
37/**
38 * There are two classes that specifies the protocol between application (job)
39 * and kioslave. SlaveInterface is the class to use on the application end,
40 * SlaveBase is the one to use on the slave end.
41 *
42 * Slave implementations should simply inherit SlaveBase
43 *
44 * A call to foo() results in a call to slotFoo() on the other end.
45 */
46class KIO_EXPORT TCPSlaveBase : public SlaveBase
47{
48public:
49 /**
50 * Constructor.
51 *
52 * @param autoSsl if true, will automatically invoke startSsl() right after
53 * connecting. In the absence of errors the use of SSL will
54 * therefore be transparent to higher layers.
55 */
56 TCPSlaveBase(const QByteArray &protocol,
57 const QByteArray &poolSocket, const QByteArray &appSocket,
58 bool autoSsl = false);
59
60 virtual ~TCPSlaveBase();
61
62protected:
63 enum SslResultDetail {
64 ResultOk = 1,
65 ResultOverridden = 2,
66 ResultFailed = 4,
67 ResultFailedEarly = 8
68 };
69 friend class QFlags<KIO::TCPSlaveBase::SslResultDetail>;
70public:
71 Q_DECLARE_FLAGS(SslResult, SslResultDetail)
72protected:
73
74 /**
75 * Send data to the remote host.
76 *
77 * @param data data to be sent to remote machine
78 * @param len the length (in bytes) of the data to be sent
79 *
80 * @return the actual size of the data that was sent
81 */
82 using SlaveBase::write; //Silence incompatible virtual override warning
83 ssize_t write(const char *data, ssize_t len);
84
85 /**
86 * Read incoming data from the remote host.
87 *
88 * @param data storage for the data read from server
89 * @param len length of the data (in bytes) to read from the server
90 *
91 * @return the actual size of data that was obtained
92 */
93 using SlaveBase::read;
94 ssize_t read(char *data, ssize_t len);
95
96 /**
97 * Same as read() except it reads data one line at a time.
98 */
99 ssize_t readLine(char *data, ssize_t len);
100
101 /**
102 * Performs the initial TCP connection stuff and/or
103 * SSL handshaking as necessary.
104 *
105 * @param protocol the protocol being used
106 * @param host hostname
107 * @param port port number
108 *
109 * @return on succes, true is returned.
110 * on failure, false is returned and an appropriate
111 * error message is sent to the application.
112 */
113 bool connectToHost(const QString &protocol, const QString& host, quint16 port);
114
115 /**
116 * Connects to the specified host and port.
117 *
118 * @param host host name
119 * @param port port number
120 * @param errorString if not NULL, this string will contain error information
121 * on why the connection request failed.
122 *
123 * @return on success, 0 is returned. on failure, a KIO::Error code is returned.
124 * @ref errorString, if not NULL, will contain the appropriate error message
125 * that can be sent back to the client.
126 *
127 * @since 4.7.2
128 */
129 int connectToHost(const QString& host, quint16 port, QString* errorString = 0);
130
131 /**
132 * the current port for this service
133 *
134 */
135 quint16 port() const;
136
137 /**
138 * Will start SSL after connecting?
139 *
140 * @return if so, true is returned.
141 * if not, false is returned.
142 */
143 bool isAutoSsl() const;
144
145 /**
146 * Is the current connection using SSL?
147 *
148 * @return if so, true is returned.
149 * if not, false is returned.
150 */
151 bool isUsingSsl() const;
152
153 /**
154 * Start using SSL on the connection. You can use it right after connecting
155 * for classic, transparent to the protocol SSL. Calling it later can be
156 * used to implement e.g. SMTP's STARTTLS feature.
157 *
158 * @return on success, true is returned.
159 * on failure, false is returned.
160 */
161 bool startSsl();
162
163 /**
164 * Close the connection and forget non-permanent data like the peer host.
165 */
166 void disconnectFromHost();
167
168 /**
169 * Returns true when end of data is reached.
170 */
171 bool atEnd() const;
172
173 /**
174 * Determines whether or not we are still connected
175 * to the remote machine.
176 *
177 * return @p true if the socket is still active or
178 * false otherwise.
179 */
180 bool isConnected() const;
181
182 /**
183 * Wait for incoming data on the socket
184 * for the period specified by @p t.
185 *
186 * @param t length of time in seconds that we should monitor the
187 * socket before timing out.
188 *
189 * @return true if any data arrived on the socket before the
190 * timeout value was reached, false otherwise.
191 */
192 bool waitForResponse( int t );
193
194 /**
195 * Sets the mode of the connection to blocking or non-blocking.
196 *
197 * Be sure to call this function before calling connectToHost.
198 * Otherwise, this setting will not have any effect until the next
199 * @p connectToHost.
200 *
201 * @param b true to make the connection a blocking one, false otherwise.
202 */
203 void setBlocking( bool b );
204
205 /**
206 * Return the socket object, if the class ever needs to do anything to it
207 */
208 QIODevice *socket() const;
209
210protected:
211 virtual void virtual_hook( int id, void* data );
212
213private:
214 // For the certificate verification code
215 SslResult verifyServerCertificate();
216
217 // For prompting for the client certificate to use
218 void selectClientCertificate();
219
220 class TcpSlaveBasePrivate;
221 TcpSlaveBasePrivate* const d;
222};
223
224}
225
226#endif
227