1/*
2 * This file is part of the KDE libraries
3 * Copyright (C) 2007 Thiago Macieira <thiago@kde.org>
4 *
5 * This library is free software; you can redistribute it and/or
6 * modify it under the terms of the GNU Library General Public
7 * License as published by the Free Software Foundation; either
8 * version 2 of the License, or (at your option) any later version.
9 *
10 * This library is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 * Library General Public License for more details.
14 *
15 * You should have received a copy of the GNU Library General Public License
16 * along with this library; see the file COPYING.LIB. If not, write to
17 * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
18 * Boston, MA 02110-1301, USA.
19 */
20
21#ifndef KSOCKETFACTORY_H
22#define KSOCKETFACTORY_H
23
24#include <kdecore_export.h>
25#include <QtCore/QString>
26#include <QtNetwork/QNetworkProxy>
27#include <QtNetwork/QHostAddress>
28
29class QTcpSocket;
30class QTcpServer;
31class QUdpSocket;
32class QUrl;
33
34/**
35 * @namespace KSocketFactory
36 * @brief KSocketFactory provides functions for opening sockets to remote hosts
37 *
38 * KSocketFactory is a socket-opener group of functions that must be
39 * used whenever a KDE application wants to communicate with a remote
40 * host. It will determine the necessary proxy and local KDE settings,
41 * then open the connection. The typical use-case is:
42 *
43 * <code>
44 * d->socket = KSocketFactory::connectToHost("www.kde.org", "http");
45 * d->socket->setParent(this);
46 * QObject::connect(d->socket, SIGNAL(connected()),
47 * this, SLOT(socketConnected()));
48 * </code>
49 *
50 * Synchronous operation is not recommended, since it may lead to UI
51 * deadlocks. It is preferred to return to the mainloop if the socket
52 * is being created in the main GUI thread.
53 *
54 * However, if the socket is created in an auxiliary thread, it is
55 * possible to use something equivalent to synchronous mode:
56 *
57 * <code>
58 * d->socket = KSocketFactory::synchronousConnectToHost("www.kde.org", "http");
59 * d->socket->setParent(this);
60 * </code>
61 *
62 * All objects returned from these functions belong to the caller and
63 * must be disposed of properly. Calling QObject::setParent() or
64 * passing a parent object is the recommended way.
65 *
66 * @author Thiago Macieira <thiago@kde.org>
67 */
68namespace KSocketFactory
69{
70 /**
71 * Initiates a TCP/IP socket connection to remote node (host) @p
72 * host, using the @p protocol. Returns a QTcpSocket
73 * that is connecting (i.e., in a state before
74 * QAbstractSocket::Connected) in most cases, even if the target
75 * service doesn't exist or if a connection failure happens.
76 *
77 * This function never returns 0. If the returned socket cannot
78 * connect, it will emit the QAbstractSocket::error()
79 * signal. Otherwise, the QAbstractSocket::connected() signal will
80 * be emitted eventually.
81 *
82 * The @p protocol parameter <b>must</b> be a string representation
83 * of the protocol being attempted, like "http", "ftp" or
84 * "xmpp". It might be used to determine the proxy type -- for
85 * instance, the proxy for HTTP connections might be different
86 * from the proxy for other connections. Pass an empty QString if
87 * the connection is of no established protocol.
88 *
89 * The @p port parameter can be used to specify the port
90 * number lookup if the service is not a well-known service.
91 *
92 * @param protocol the protocol this socket will use
93 * @param host the remote node (host) to connect to
94 * @param port the port number to connect to
95 * @param parent the parent object to be passed to the
96 * QTcpSocket constructor
97 * @threadsafe
98 */
99 KDECORE_EXPORT QTcpSocket *connectToHost(const QString &protocol, const QString &host,
100 quint16 port, QObject *parent = 0);
101
102 /**
103 * @overload
104 */
105 KDECORE_EXPORT QTcpSocket *connectToHost(const QUrl &url, QObject *parent = 0);
106
107 /**
108 * @overload
109 */
110 KDECORE_EXPORT void connectToHost(QTcpSocket *socket, const QString &protocol,
111 const QString &host, quint16 port);
112
113 /**
114 * @overload
115 */
116 KDECORE_EXPORT void connectToHost(QTcpSocket *socket, const QUrl &url);
117
118 /**
119 * This function behaves exactly like connectToHost() above, except
120 * that the socket it returns is either in
121 * QAbstractSocket::Connected state, or it has failed connecting
122 * altogether.
123 *
124 * This function should be used if a synchronous connection is
125 * necessary instead of calling
126 * QAbstractSocket::waitForConnected(), since that may not work on
127 * all objects returned from connectToHost().
128 *
129 * This function does not return 0. If the connection attempt
130 * failed for some reason, the socket state will be
131 * QAbstractSocket::UnconnectedState and QAbstractSocket::isValid
132 * will return false. The socket error state and string will
133 * contain more information.
134 * @warning: This function may block.
135 *
136 * @param protocol the protocol this socket will use
137 * @param host the remote node (host) to connect to
138 * @param port the port number to connect to
139 * @param msecs the time (in milliseconds) to wait while
140 * attempting to connect
141 * @param parent the parent object to be passed to the
142 * QTcpSocket constructor
143 * @threadsafe
144 */
145 KDECORE_EXPORT QTcpSocket *synchronousConnectToHost(const QString &protocol,
146 const QString &host,
147 quint16 port, int msecs = 30000,
148 QObject *parent = 0);
149
150 /**
151 * @overload
152 */
153 KDECORE_EXPORT QTcpSocket *synchronousConnectToHost(const QUrl &url, int msecs = 30000,
154 QObject *parent = 0);
155
156 /**
157 * @overload
158 */
159 KDECORE_EXPORT void synchronousConnectToHost(QTcpSocket *socket, const QString &protocol,
160 const QString &host, quint16 port,
161 int msecs = 30000);
162
163 /**
164 * @overload
165 */
166 KDECORE_EXPORT void synchronousConnectToHost(QTcpSocket *socket, const QUrl &url,
167 int msecs = 30000);
168
169 /**
170 * Opens a TCP/IP socket for listening protocol @p protocol, binding
171 * only at address @p address. The @p port parameter indicates the
172 * port to be opened.
173 *
174 * This function does not return 0. If the opening of the socket
175 * failed for some reason, it will return a QTcpServer object that
176 * is not listening (QTcpServer::isListening() returns false),
177 * with a properly set error string indicating the reason).
178 *
179 * Note that passing 0 as the default port number will cause the
180 * operating system to automatically allocate a free port for the
181 * socket.
182 *
183 * @param protocol the protocol this socket will accept
184 * @param address the address to listen at
185 * @param port the default port for the service
186 * @param parent the parent object to be passed to the
187 * QTcpServer constructor
188 */
189 KDECORE_EXPORT QTcpServer *listen(const QString &protocol, const QHostAddress &address = QHostAddress::Any,
190 quint16 port = 0, QObject *parent = 0);
191
192 // These functions below aren't done yet
193 // Undocumented -> don't use!
194
195 KDECORE_EXPORT QUdpSocket *datagramSocket(const QString &protocol, const QString &host, QObject *parent = 0);
196
197#ifndef QT_NO_NETWORKPROXY
198 KDECORE_EXPORT QNetworkProxy proxyForConnection(const QString &protocol, const QString &host);
199 KDECORE_EXPORT QNetworkProxy proxyForListening(const QString &protocol);
200 KDECORE_EXPORT QNetworkProxy proxyForDatagram(const QString &protocol, const QString &host);
201#endif
202}
203
204#endif
205