KDELibs4Support

k3streamsocket.h
1 /* -*- C++ -*-
2  * Copyright (C) 2003,2005 Thiago Macieira <[email protected]>
3  *
4  *
5  * Permission is hereby granted, free of charge, to any person obtaining
6  * a copy of this software and associated documentation files (the
7  * "Software"), to deal in the Software without restriction, including
8  * without limitation the rights to use, copy, modify, merge, publish,
9  * distribute, sublicense, and/or sell copies of the Software, and to
10  * permit persons to whom the Software is furnished to do so, subject to
11  * the following conditions:
12  *
13  * The above copyright notice and this permission notice shall be included
14  * in all copies or substantial portions of the Software.
15  *
16  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
17  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
18  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
19  * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
20  * LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
21  * OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
22  * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
23  */
24 
25 #ifndef KSTREAMSOCKET_H
26 #define KSTREAMSOCKET_H
27 
28 #include <QString>
29 
30 #include "k3clientsocketbase.h"
31 
32 /** A namespace to store all networking-related (socket) classes. */
33 namespace KNetwork
34 {
35 
36 class KResolverEntry;
37 class KServerSocket;
38 class KBufferedSocket;
39 
40 class KStreamSocketPrivate;
41 /** @class KStreamSocket k3streamsocket.h k3streamsocket.h
42  * @brief Simple stream socket
43  *
44  * This class provides functionality to creating unbuffered, stream
45  * sockets. In the case of Internet (IP) sockets, this class creates and
46  * uses TCP/IP sockets.
47  *
48  * Objects of this class start, by default, on non-blocking mode. Call
49  * setBlocking if you wish to change that.
50  *
51  * KStreamSocket objects are thread-safe and can be used in auxiliary
52  * threads (i.e., not the thread in which the Qt event loop runs in).
53  * Note that KBufferedSocket cannot be used reliably in an auxiliary thread.
54  *
55  * Sample usage:
56  * \code
57  * QByteArray httpGet(const QString& hostname)
58  * {
59  * KStreamSocket socket(hostname, "http");
60  * if (!socket.connect())
61  * return QByteArray();
62  * QByteArray data = socket.readAll();
63  * return data;
64  * }
65  * \endcode
66  *
67  * Here's another sample, showing asynchronous operation:
68  * \code
69  * DataRetriever::DataRetriever(const QString& hostname, const QString& port)
70  * : socket(hostname, port)
71  * {
72  * // connect signals to our slots
73  * QObject::connect(&socket, SIGNAL(connected(const KNetwork::KResolverEntry&)),
74  * this, SLOT(slotSocketConnected()));
75  * QObject::connect(&socket, SIGNAL(gotError(int)),
76  * this, SLOT(slotSocketError(int)));
77  * QObject::connect(&socket, SIGNAL(readyRead()),
78  * this, SLOT(slotSocketReadyToRead()));
79  * QObject::connect(&socket, SIGNAL(readyWrite()),
80  * this, SLOT(slotSocketReadyToWrite()));
81  *
82  * // set non-blocking mode in order to work asynchronously
83  * socket.setBlocking(false);
84  *
85  * // turn on signal emission
86  * socket.enableRead(true);
87  * socket.enableWrite(true);
88  *
89  * // start connecting
90  * socket.connect();
91  * }
92  * \endcode
93  *
94  * @see KNetwork::KBufferedSocket, KNetwork::KServerSocket
95  * @author Thiago Macieira <[email protected]>
96  * @version 0.9
97  * @deprecated Use KSocketFactory or KLocalSocket instead
98  */
99 class KDELIBS4SUPPORT_DEPRECATED_EXPORT KStreamSocket: public KClientSocketBase
100 {
101  Q_OBJECT
102 
103 public:
104  /**
105  * Default constructor.
106  *
107  * @param node destination host
108  * @param service destination service to connect to
109  * @param parent the parent QObject object
110  */
111  KDELIBS4SUPPORT_DEPRECATED explicit KStreamSocket(const QString &node = QString(), const QString &service = QString(),
112  QObject *parent = nullptr);
113 
114  /**
115  * Destructor. This closes the socket.
116  */
117  ~KStreamSocket() override;
118 
119  /**
120  * Retrieves the timeout value (in milliseconds).
121  */
122  int timeout() const;
123 
124  /**
125  * Retrieves the remaining timeout time (in milliseconds). This value
126  * equals timeout() if there's no connection in progress.
127  */
128  int remainingTimeout() const;
129 
130  /**
131  * Sets the timeout value. Setting this value while a connection attempt
132  * is in progress will reset the timer.
133  *
134  * Please note that the timeout value is valid for the connection attempt
135  * only. No other operations are timed against this value -- including the
136  * name lookup associated.
137  *
138  * @param msecs the timeout value in milliseconds
139  */
140  void setTimeout(int msecs);
141 
142  /**
143  * Binds this socket to the given nodename and service,
144  * or use the default ones if none are given. In order to bind to a service
145  * and allow the operating system to choose the interface, set @p node to
146  * QString().
147  *
148  * Reimplemented from KClientSocketBase.
149  *
150  * Upon successful binding, the bound() signal will be
151  * emitted. If an error is found, the gotError()
152  * signal will be emitted.
153  *
154  * @note Due to the internals of the name lookup and binding
155  * mechanism, some (if not most) implementations of this function
156  * do not actually bind the socket until the connection
157  * is requested (see connect()). They only set the values
158  * for future reference.
159  *
160  * This function returns true on success.
161  *
162  * @param node the nodename
163  * @param service the service
164  */
165  bool bind(const QString &node = QString(),
166  const QString &service = QString()) override;
167 
168  /**
169  * Reimplemented from KClientSocketBase. Connect this socket to this
170  * specific address.
171  *
172  * Unlike bind(const QString&, const QString&) above, this function
173  * really does bind the socket. No lookup is performed. The bound()
174  * signal will be emitted.
175  */
176  bool bind(const KResolverEntry &entry) override;
177 
178  /**
179  * Reimplemented from KClientSocketBase.
180  *
181  * Attempts to connect to the these hostname and service,
182  * or use the default ones if none are given. If a connection attempt
183  * is already in progress, check on its state and set the error status
184  * (NoError, meaning the connection is completed, or InProgress).
185  *
186  * If the blocking mode for this object is on, this function will only
187  * return when all the resolved peer addresses have been tried or when
188  * a connection is established.
189  *
190  * Upon successfully connecting, the connected() signal
191  * will be emitted. If an error is found, the gotError()
192  * signal will be emitted.
193  *
194  * This function also implements timeout handling.
195  *
196  * @param node the remote node to connect to
197  * @param service the service on the remote node to connect to
198  * @param mode mode to operate this socket in
199  */
200  bool connect(const QString &node = QString(),
201  const QString &service = QString(),
202  OpenMode mode = ReadWrite) override;
203 
204  /**
205  * Unshadowing from KClientSocketBase.
206  */
207  bool connect(const KResolverEntry &entry,
208  OpenMode mode = ReadWrite) override;
209 
210 Q_SIGNALS:
211  /**
212  * This signal is emitted when a connection timeout occurs.
213  */
214  void timedOut();
215 
216 private Q_SLOTS:
217  void hostFoundSlot();
218  void connectionEvent();
219  void timeoutSlot();
220 
221 private:
222  /**
223  * @internal
224  * If the user requested local bind before connection, bind the socket to one
225  * suitable address and return true. Also sets d->local to the address used.
226  *
227  * Return false in case of error.
228  */
229  bool bindLocallyFor(const KResolverEntry &peer);
230 
231  /**
232  * @internal
233  * Finishes the connection process by setting internal values and
234  * emitting the proper signals.
235  *
236  * Note: assumes d->local iterator points to the address that we bound
237  * to.
238  */
239  void connectionSucceeded(const KResolverEntry &peer);
240 
241  KStreamSocket(const KStreamSocket &);
242  KStreamSocket &operator=(const KStreamSocket &);
243 
244  KStreamSocketPrivate *const d;
245 
246  friend class KServerSocket;
247  friend class KBufferedSocket;
248 };
249 
250 } // namespace KNetwork
251 
252 #endif
Simple stream socket.
A server socket for accepting connections.
One resolution entry.
Definition: k3resolver.h:72
A namespace to store all networking-related (socket) classes.
Buffered stream sockets.
Abstract client socket class.
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Sat Sep 25 2021 22:59:58 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.