src/network/socket/qlocalsocket.cpp

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