1/****************************************************************************
2**
3** Copyright (C) 2016 The Qt Company Ltd.
4** Contact: https://www.qt.io/licensing/
5**
6** This file is part of the QtNetwork module of the Qt Toolkit.
7**
8** $QT_BEGIN_LICENSE:LGPL$
9** Commercial License Usage
10** Licensees holding valid commercial Qt licenses may use this file in
11** accordance with the commercial license agreement provided with the
12** Software or, alternatively, in accordance with the terms contained in
13** a written agreement between you and The Qt Company. For licensing terms
14** and conditions see https://www.qt.io/terms-conditions. For further
15** information use the contact form at https://www.qt.io/contact-us.
16**
17** GNU Lesser General Public License Usage
18** Alternatively, this file may be used under the terms of the GNU Lesser
19** General Public License version 3 as published by the Free Software
20** Foundation and appearing in the file LICENSE.LGPL3 included in the
21** packaging of this file. Please review the following information to
22** ensure the GNU Lesser General Public License version 3 requirements
23** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
24**
25** GNU General Public License Usage
26** Alternatively, this file may be used under the terms of the GNU
27** General Public License version 2.0 or (at your option) the GNU General
28** Public license version 3 or any later version approved by the KDE Free
29** Qt Foundation. The licenses are as published by the Free Software
30** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
31** included in the packaging of this file. Please review the following
32** information to ensure the GNU General Public License requirements will
33** be met: https://www.gnu.org/licenses/gpl-2.0.html and
34** https://www.gnu.org/licenses/gpl-3.0.html.
35**
36** $QT_END_LICENSE$
37**
38****************************************************************************/
39
40#include <QtNetwork/private/qtnetworkglobal_p.h>
41
42#include "qlocalsocket.h"
43#include "qlocalsocket_p.h"
44
45QT_BEGIN_NAMESPACE
46
47/*!
48 \class QLocalSocket
49 \since 4.4
50 \inmodule QtNetwork
51
52 \brief The QLocalSocket class provides a local socket.
53
54 On Windows this is a named pipe and on Unix this is a local domain socket.
55
56 If an error occurs, error() returns the type of error, and
57 errorString() can be called to get a human readable description
58 of what happened.
59
60 Although QLocalSocket is designed for use with an event loop, it's possible
61 to use it without one. In that case, you must use waitForConnected(),
62 waitForReadyRead(), waitForBytesWritten(), and waitForDisconnected()
63 which blocks until the operation is complete or the timeout expires.
64
65 \sa QLocalServer
66*/
67
68/*!
69 \fn void QLocalSocket::connectToServer(OpenMode openMode)
70 \since 5.1
71
72 Attempts to make a connection to serverName().
73 setServerName() must be called before you open the connection.
74 Alternatively you can use connectToServer(const QString &name, OpenMode openMode);
75
76 The socket is opened in the given \a openMode and first enters ConnectingState.
77 If a connection is established, QLocalSocket enters ConnectedState and emits connected().
78
79 After calling this function, the socket can emit errorOccurred() to signal that an error occurred.
80
81 \sa state(), serverName(), waitForConnected()
82*/
83
84/*!
85 \fn void QLocalSocket::open(OpenMode openMode)
86
87 Equivalent to connectToServer(OpenMode mode).
88 The socket is opened in the given \a openMode to the server defined by setServerName().
89
90 Note that unlike in most other QIODevice subclasses, open() may not open the device directly.
91 The function return false if the socket was already connected or if the server to connect
92 to was not defined and true in any other case. The connected() or errorOccurred() signals will be
93 emitted once the device is actually open (or the connection failed).
94
95 See connectToServer() for more details.
96*/
97
98/*!
99 \fn void QLocalSocket::connected()
100
101 This signal is emitted after connectToServer() has been called and
102 a connection has been successfully established.
103
104 \sa connectToServer(), disconnected()
105*/
106
107/*!
108 \fn bool QLocalSocket::setSocketDescriptor(qintptr socketDescriptor,
109 LocalSocketState socketState, OpenMode openMode)
110
111 Initializes QLocalSocket with the native socket descriptor
112 \a socketDescriptor. Returns \c true if socketDescriptor is accepted
113 as a valid socket descriptor; otherwise returns \c false. The socket is
114 opened in the mode specified by \a openMode, and enters the socket state
115 specified by \a socketState.
116
117 \note It is not possible to initialize two local sockets with the same
118 native socket descriptor.
119
120 \sa socketDescriptor(), state(), openMode()
121*/
122
123/*!
124 \fn qintptr QLocalSocket::socketDescriptor() const
125
126 Returns the native socket descriptor of the QLocalSocket object if
127 this is available; otherwise returns -1.
128
129 The socket descriptor is not available when QLocalSocket
130 is in UnconnectedState.
131 The type of the descriptor depends on the platform:
132
133 \list
134 \li On Windows, the returned value is a
135 \l{https://msdn.microsoft.com/en-us/library/windows/desktop/ms740522(v=vs.85).aspx}
136 {Winsock 2 Socket Handle}.
137
138 \li With WinRT and on INTEGRITY, the returned value is the
139 QTcpSocket socket descriptor and the type is defined by
140 \l{QTcpSocket::socketDescriptor}{socketDescriptor}.
141
142 \li On all other UNIX-like operating systems, the type is
143 a file descriptor representing a socket.
144 \endlist
145
146 \sa setSocketDescriptor()
147*/
148
149/*!
150 \fn qint64 QLocalSocket::readData(char *data, qint64 c)
151 \reimp
152*/
153
154/*!
155 \fn qint64 QLocalSocket::writeData(const char *data, qint64 c)
156 \reimp
157*/
158
159/*!
160 \fn void QLocalSocket::abort()
161
162 Aborts the current connection and resets the socket.
163 Unlike disconnectFromServer(), this function immediately closes the socket,
164 clearing any pending data in the write buffer.
165
166 \sa disconnectFromServer(), close()
167*/
168
169/*!
170 \fn qint64 QLocalSocket::bytesAvailable() const
171 \reimp
172*/
173
174/*!
175 \fn qint64 QLocalSocket::bytesToWrite() const
176 \reimp
177*/
178
179/*!
180 \fn bool QLocalSocket::canReadLine() const
181 \reimp
182*/
183
184/*!
185 \fn void QLocalSocket::close()
186 \reimp
187*/
188
189/*!
190 \fn bool QLocalSocket::waitForBytesWritten(int msecs)
191 \reimp
192*/
193
194/*!
195 \fn bool QLocalSocket::flush()
196
197 This function writes as much as possible from the internal write buffer
198 to the socket, without blocking. If any data was written, this function
199 returns \c true; otherwise false is returned.
200
201 Call this function if you need QLocalSocket to start sending buffered data
202 immediately. The number of bytes successfully written depends on the
203 operating system. In most cases, you do not need to call this function,
204 because QLocalSocket will start sending data automatically once control
205 goes back to the event loop. In the absence of an event loop, call
206 waitForBytesWritten() instead.
207
208 \sa write(), waitForBytesWritten()
209*/
210
211/*!
212 \fn void QLocalSocket::disconnectFromServer()
213
214 Attempts to close the socket. If there is pending data waiting to be
215 written, QLocalSocket will enter ClosingState and wait until all data
216 has been written. Eventually, it will enter UnconnectedState and emit
217 the disconnectedFromServer() signal.
218
219 \sa connectToServer()
220*/
221
222/*!
223 \fn QLocalSocket::LocalSocketError QLocalSocket::error() const
224
225 Returns the type of error that last occurred.
226
227 \sa state(), errorString()
228*/
229
230/*!
231 \fn bool QLocalSocket::isValid() const
232
233 Returns \c true if the socket is valid and ready for use; otherwise
234 returns \c false.
235
236 \note The socket's state must be ConnectedState before reading
237 and writing can occur.
238
239 \sa state(), connectToServer()
240*/
241
242/*!
243 \fn qint64 QLocalSocket::readBufferSize() const
244
245 Returns the size of the internal read buffer. This limits the amount of
246 data that the client can receive before you call read() or readAll().
247 A read buffer size of 0 (the default) means that the buffer has no size
248 limit, ensuring that no data is lost.
249
250 \sa setReadBufferSize(), read()
251*/
252
253/*!
254 \fn void QLocalSocket::setReadBufferSize(qint64 size)
255
256 Sets the size of QLocalSocket's internal read buffer to be \a size bytes.
257
258 If the buffer size is limited to a certain size, QLocalSocket won't
259 buffer more than this size of data. Exceptionally, a buffer size of 0
260 means that the read buffer is unlimited and all incoming data is buffered.
261 This is the default.
262
263 This option is useful if you only read the data at certain points in
264 time (e.g., in a real-time streaming application) or if you want to
265 protect your socket against receiving too much data, which may eventually
266 cause your application to run out of memory.
267
268 \sa readBufferSize(), read()
269*/
270
271/*!
272 \fn bool QLocalSocket::waitForConnected(int msecs)
273
274 Waits until the socket is connected, up to \a msecs milliseconds. If the
275 connection has been established, this function returns \c true; otherwise
276 it returns \c false. In the case where it returns \c false, you can call
277 error() to determine the cause of the error.
278
279 The following example waits up to one second for a connection
280 to be established:
281
282 \snippet code/src_network_socket_qlocalsocket_unix.cpp 0
283
284 If \a msecs is -1, this function will not time out.
285
286 \sa connectToServer(), connected()
287*/
288
289/*!
290 \fn bool QLocalSocket::waitForDisconnected(int msecs)
291
292 Waits until the socket has disconnected, up to \a msecs milliseconds. If the
293 connection was successfully disconnected, this function returns \c true;
294 otherwise it returns \c false (if the operation timed out, if an error
295 occurred, or if this QLocalSocket is already disconnected). In the case
296 where it returns \c false, you can call error() to determine the cause of
297 the error.
298
299 The following example waits up to one second for a connection
300 to be closed:
301
302 \snippet code/src_network_socket_qlocalsocket_unix.cpp 1
303
304 If \a msecs is -1, this function will not time out.
305
306 \sa disconnectFromServer(), close()
307*/
308
309/*!
310 \fn bool QLocalSocket::waitForReadyRead(int msecs)
311
312 This function blocks until data is available for reading and the
313 \l{QIODevice::}{readyRead()} signal has been emitted. The function
314 will timeout after \a msecs milliseconds; the default timeout is
315 30000 milliseconds.
316
317 The function returns \c true if data is available for reading;
318 otherwise it returns \c false (if an error occurred or the
319 operation timed out).
320
321 \sa waitForBytesWritten()
322*/
323
324/*!
325 \fn void QLocalSocket::disconnected()
326
327 This signal is emitted when the socket has been disconnected.
328
329 \sa connectToServer(), disconnectFromServer(), abort(), connected()
330*/
331
332/*!
333 \fn void QLocalSocket::error(QLocalSocket::LocalSocketError socketError)
334 \obsolete
335
336 Use errorOccurred() instead.
337*/
338
339/*!
340 \fn void QLocalSocket::errorOccurred(QLocalSocket::LocalSocketError socketError)
341 \since 5.15
342
343 This signal is emitted after an error occurred. The \a socketError
344 parameter describes the type of error that occurred.
345
346 QLocalSocket::LocalSocketError is not a registered metatype, so for queued
347 connections, you will have to register it with Q_DECLARE_METATYPE() and
348 qRegisterMetaType().
349
350 \sa error(), errorString(), {Creating Custom Qt Types}
351*/
352
353/*!
354 \fn void QLocalSocket::stateChanged(QLocalSocket::LocalSocketState socketState)
355
356 This signal is emitted whenever QLocalSocket's state changes.
357 The \a socketState parameter is the new state.
358
359 QLocalSocket::SocketState is not a registered metatype, so for queued
360 connections, you will have to register it with Q_DECLARE_METATYPE() and
361 qRegisterMetaType().
362
363 \sa state(), {Creating Custom Qt Types}
364*/
365
366/*!
367 Creates a new local socket. The \a parent argument is passed to
368 QObject's constructor.
369 */
370QLocalSocket::QLocalSocket(QObject * parent)
371 : QIODevice(*new QLocalSocketPrivate, parent)
372{
373 Q_D(QLocalSocket);
374 d->init();
375
376 // Support the deprecated error() signal:
377 connect(sender: this, signal: &QLocalSocket::errorOccurred, receiver: this, slot: QOverload<QLocalSocket::LocalSocketError>::of(ptr: &QLocalSocket::error));
378}
379
380/*!
381 Destroys the socket, closing the connection if necessary.
382 */
383QLocalSocket::~QLocalSocket()
384{
385 QLocalSocket::close();
386#if !defined(Q_OS_WIN) && !defined(QT_LOCALSOCKET_TCP)
387 Q_D(QLocalSocket);
388 d->unixSocket.setParent(nullptr);
389#endif
390}
391
392bool QLocalSocket::open(OpenMode openMode)
393{
394 connectToServer(openMode);
395 return isOpen();
396}
397
398/*! \overload
399
400 Set the server \a name and attempts to make a connection to it.
401
402 The socket is opened in the given \a openMode and first enters ConnectingState.
403 If a connection is established, QLocalSocket enters ConnectedState and emits connected().
404
405 After calling this function, the socket can emit errorOccurred() to signal that an error occurred.
406
407 \sa state(), serverName(), waitForConnected()
408*/
409void QLocalSocket::connectToServer(const QString &name, OpenMode openMode)
410{
411 setServerName(name);
412 connectToServer(openMode);
413}
414
415/*!
416 \since 5.1
417
418 Set the \a name of the peer to connect to.
419 On Windows name is the name of a named pipe; on Unix name is the name of a local domain socket.
420
421 This function must be called when the socket is not connected.
422*/
423void QLocalSocket::setServerName(const QString & name)
424{
425 Q_D(QLocalSocket);
426 if (d->state != UnconnectedState) {
427 qWarning(msg: "QLocalSocket::setServerName() called while not in unconnected state");
428 return;
429 }
430 d->serverName = name;
431}
432
433/*!
434 Returns the name of the peer as specified by setServerName(), or an
435 empty QString if setServerName() has not been called or connectToServer() failed.
436
437 \sa connectToServer(), fullServerName()
438
439 */
440QString QLocalSocket::serverName() const
441{
442 Q_D(const QLocalSocket);
443 return d->serverName;
444}
445
446/*!
447 Returns the server path that the socket is connected to.
448
449 \note The return value of this function is platform specific.
450
451 \sa connectToServer(), serverName()
452 */
453QString QLocalSocket::fullServerName() const
454{
455 Q_D(const QLocalSocket);
456 return d->fullServerName;
457}
458
459/*!
460 Returns the state of the socket.
461
462 \sa error()
463 */
464QLocalSocket::LocalSocketState QLocalSocket::state() const
465{
466 Q_D(const QLocalSocket);
467 return d->state;
468}
469
470/*! \reimp
471*/
472bool QLocalSocket::isSequential() const
473{
474 return true;
475}
476
477/*!
478 \enum QLocalSocket::LocalSocketError
479
480 The LocalServerError enumeration represents the errors that can occur.
481 The most recent error can be retrieved through a call to
482 \l QLocalSocket::error().
483
484 \value ConnectionRefusedError The connection was refused by
485 the peer (or timed out).
486 \value PeerClosedError The remote socket closed the connection.
487 Note that the client socket (i.e., this socket) will be closed
488 after the remote close notification has been sent.
489 \value ServerNotFoundError The local socket name was not found.
490 \value SocketAccessError The socket operation failed because the
491 application lacked the required privileges.
492 \value SocketResourceError The local system ran out of resources
493 (e.g., too many sockets).
494 \value SocketTimeoutError The socket operation timed out.
495 \value DatagramTooLargeError The datagram was larger than the operating
496 system's limit (which can be as low as 8192 bytes).
497 \value ConnectionError An error occurred with the connection.
498 \value UnsupportedSocketOperationError The requested socket operation
499 is not supported by the local operating system.
500 \value OperationError An operation was attempted while the socket was in a state that
501 did not permit it.
502 \value UnknownSocketError An unidentified error occurred.
503 */
504
505/*!
506 \enum QLocalSocket::LocalSocketState
507
508 This enum describes the different states in which a socket can be.
509
510 \sa QLocalSocket::state()
511
512 \value UnconnectedState The socket is not connected.
513 \value ConnectingState The socket has started establishing a connection.
514 \value ConnectedState A connection is established.
515 \value ClosingState The socket is about to close
516 (data may still be waiting to be written).
517 */
518
519#ifndef QT_NO_DEBUG_STREAM
520QDebug operator<<(QDebug debug, QLocalSocket::LocalSocketError error)
521{
522 QDebugStateSaver saver(debug);
523 debug.resetFormat().nospace();
524 switch (error) {
525 case QLocalSocket::ConnectionRefusedError:
526 debug << "QLocalSocket::ConnectionRefusedError";
527 break;
528 case QLocalSocket::PeerClosedError:
529 debug << "QLocalSocket::PeerClosedError";
530 break;
531 case QLocalSocket::ServerNotFoundError:
532 debug << "QLocalSocket::ServerNotFoundError";
533 break;
534 case QLocalSocket::SocketAccessError:
535 debug << "QLocalSocket::SocketAccessError";
536 break;
537 case QLocalSocket::SocketResourceError:
538 debug << "QLocalSocket::SocketResourceError";
539 break;
540 case QLocalSocket::SocketTimeoutError:
541 debug << "QLocalSocket::SocketTimeoutError";
542 break;
543 case QLocalSocket::DatagramTooLargeError:
544 debug << "QLocalSocket::DatagramTooLargeError";
545 break;
546 case QLocalSocket::ConnectionError:
547 debug << "QLocalSocket::ConnectionError";
548 break;
549 case QLocalSocket::UnsupportedSocketOperationError:
550 debug << "QLocalSocket::UnsupportedSocketOperationError";
551 break;
552 case QLocalSocket::UnknownSocketError:
553 debug << "QLocalSocket::UnknownSocketError";
554 break;
555 case QLocalSocket::OperationError:
556 debug << "QLocalSocket::OperationError";
557 break;
558 default:
559 debug << "QLocalSocket::SocketError(" << int(error) << ')';
560 break;
561 }
562 return debug;
563}
564
565QDebug operator<<(QDebug debug, QLocalSocket::LocalSocketState state)
566{
567 QDebugStateSaver saver(debug);
568 debug.resetFormat().nospace();
569 switch (state) {
570 case QLocalSocket::UnconnectedState:
571 debug << "QLocalSocket::UnconnectedState";
572 break;
573 case QLocalSocket::ConnectingState:
574 debug << "QLocalSocket::ConnectingState";
575 break;
576 case QLocalSocket::ConnectedState:
577 debug << "QLocalSocket::ConnectedState";
578 break;
579 case QLocalSocket::ClosingState:
580 debug << "QLocalSocket::ClosingState";
581 break;
582 default:
583 debug << "QLocalSocket::SocketState(" << int(state) << ')';
584 break;
585 }
586 return debug;
587}
588#endif
589
590QT_END_NAMESPACE
591
592#include "moc_qlocalsocket.cpp"
593

source code of qtbase/src/network/socket/qlocalsocket.cpp