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 | |
29 | class QTcpSocket; |
30 | class QTcpServer; |
31 | class QUdpSocket; |
32 | class 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 | */ |
68 | namespace 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 | |