1 /****************************************************************************

     2 **

     3 ** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).

     4 ** All rights reserved.

     5 ** Contact: Nokia Corporation (qt-info@nokia.com)

     6 **

     7 ** This file is part of the QtNetwork module of the Qt Toolkit.

     8 **

     9 ** $QT_BEGIN_LICENSE:LGPL$

    10 ** No Commercial Usage

    11 ** This file contains pre-release code and may not be distributed.

    12 ** You may use this file in accordance with the terms and conditions

    13 ** contained in the Technology Preview License Agreement accompanying

    14 ** this package.

    15 **

    16 ** GNU Lesser General Public License Usage

    17 ** Alternatively, this file may be used under the terms of the GNU Lesser

    18 ** General Public License version 2.1 as published by the Free Software

    19 ** Foundation and appearing in the file LICENSE.LGPL included in the

    20 ** packaging of this file.  Please review the following information to

    21 ** ensure the GNU Lesser General Public License version 2.1 requirements

    22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

    23 **

    24 ** In addition, as a special exception, Nokia gives you certain additional

    25 ** rights.  These rights are described in the Nokia Qt LGPL Exception

    26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

    27 **

    28 ** If you have questions regarding the use of this file, please contact

    29 ** Nokia at qt-info@nokia.com.

    30 **

    31 **

    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 

    53     \brief The QLocalSocket class provides a local socket.

    54 

    55     On Windows this is a named pipe and on Unix this is a local domain socket.

    56 

    57     If an error occurs, socketError() returns the type of error, and

    58     errorString() can be called to get a human readable description

    59     of what happened.

    60 

    61     Although QLocalSocket is designed for use with an event loop, it's possible

    62     to use it without one. In that case, you must use waitForConnected(),

    63     waitForReadyRead(), waitForBytesWritten(), and waitForDisconnected()

    64     which blocks until the operation is complete or the timeout expires.

    65 

    66     Note that this feature is not supported on versions of Windows earlier than

    67     Windows XP.

    68 

    69     \sa QLocalServer

    70 */

    71 

    72 /*!

    73     \fn void QLocalSocket::connectToServer(const QString &name, OpenMode openMode)

    74 

    75     Attempts to make a connection to \a name.

    76 

    77     The socket is opened in the given \a openMode and first enters ConnectingState.

    78     It then attempts to connect to the address or addresses returned by the lookup.

    79     Finally, if a connection is established, QLocalSocket enters ConnectedState

    80     and emits connected().

    81 

    82     At any point, the socket can emit error() to signal that an error occurred.

    83 

    84     See also state(), serverName(), and waitForConnected().

    85 */

    86 

    87 /*!

    88     \fn void QLocalSocket::connected()

    89 

    90     This signal is emitted after connectToServer() has been called and

    91     a connection has been successfully established.

    92 

    93     \sa connectToServer(), disconnected()

    94 */

    95 

    96 /*!

    97     \fn bool QLocalSocket::setSocketDescriptor(quintptr socketDescriptor,

    98         LocalSocketState socketState, OpenMode openMode)

    99 

   100     Initializes QLocalSocket with the native socket descriptor

   101     \a socketDescriptor. Returns true if socketDescriptor is accepted

   102     as a valid socket descriptor; otherwise returns false. The socket is

   103     opened in the mode specified by \a openMode, and enters the socket state

   104     specified by \a socketState.

   105 

   106     \note It is not possible to initialize two local sockets with the same

   107     native socket descriptor.

   108 

   109     \sa socketDescriptor(), state(), openMode()

   110 */

   111 

   112 /*!

   113     \fn quintptr QLocalSocket::socketDescriptor() const

   114 

   115     Returns the native socket descriptor of the QLocalSocket object if

   116     this is available; otherwise returns -1.

   117 

   118     The socket descriptor is not available when QLocalSocket

   119     is in UnconnectedState.

   120 

   121     \sa setSocketDescriptor()

   122 */

   123 

   124 /*!

   125     \fn qint64 QLocalSocket::readData(char *data, qint64 c)

   126     \reimp

   127 */

   128 

   129 /*!

   130     \fn qint64 QLocalSocket::writeData(const char *data, qint64 c)

   131     \reimp

   132 */

   133 

   134 /*!

   135     \fn void QLocalSocket::abort()

   136 

   137     Aborts the current connection and resets the socket.

   138     Unlike disconnectFromServer(), this function immediately closes the socket,

   139     clearing any pending data in the write buffer.

   140 

   141     \sa disconnectFromServer(), close()

   142 */

   143 

   144 /*!

   145     \fn qint64 QLocalSocket::bytesAvailable() const

   146     \reimp

   147 */

   148 

   149 /*!

   150     \fn qint64 QLocalSocket::bytesToWrite() const

   151     \reimp

   152 */

   153 

   154 /*!

   155     \fn bool QLocalSocket::canReadLine() const

   156     \reimp

   157 */

   158 

   159 /*!

   160     \fn void QLocalSocket::close()

   161     \reimp

   162 */

   163 

   164 /*!

   165     \fn bool QLocalSocket::waitForBytesWritten(int msecs)

   166     \reimp

   167 */

   168 

   169 /*!

   170     \fn bool QLocalSocket::flush()

   171 

   172     This function writes as much as possible from the internal write buffer

   173     to the socket, without blocking.  If any data was written, this function

   174     returns true; otherwise false is returned.

   175 

   176     Call this function if you need QLocalSocket to start sending buffered data

   177     immediately. The number of bytes successfully written depends on the

   178     operating system. In most cases, you do not need to call this function,

   179     because QLocalSocket will start sending data automatically once control

   180     goes back to the event loop. In the absence of an event loop, call

   181     waitForBytesWritten() instead.

   182 

   183     \sa write(), waitForBytesWritten()

   184 */

   185 

   186 /*!

   187     \fn void QLocalSocket::disconnectFromServer()

   188 

   189     Attempts to close the socket. If there is pending data waiting to be

   190     written, QLocalSocket will enter ClosingState and wait until all data

   191     has been written. Eventually, it will enter UnconnectedState and emit

   192     the disconnectedFromServer() signal.

   193 

   194     \sa connectToServer()

   195 */

   196 

   197 /*!

   198     \fn QLocalSocket::LocalSocketError QLocalSocket::error() const

   199 

   200     Returns the type of error that last occurred.

   201 

   202     \sa state(), errorString()

   203 */

   204 

   205 /*!

   206     \fn bool QLocalSocket::isValid() const

   207 

   208     Returns true if the socket is valid and ready for use; otherwise

   209     returns false.

   210 

   211     \note The socket's state must be ConnectedState before reading

   212     and writing can occur.

   213 

   214     \sa state(), connectToServer()

   215 */

   216 

   217 /*!

   218     \fn qint64 QLocalSocket::readBufferSize() const

   219 

   220     Returns the size of the internal read buffer. This limits the amount of

   221     data that the client can receive before you call read() or readAll().

   222     A read buffer size of 0 (the default) means that the buffer has no size

   223     limit, ensuring that no data is lost.

   224 

   225     \sa setReadBufferSize(), read()

   226 */

   227 

   228 /*!

   229     \fn void QLocalSocket::setReadBufferSize(qint64 size)

   230 

   231     Sets the size of QLocalSocket's internal read buffer to be \a size bytes.

   232 

   233     If the buffer size is limited to a certain size, QLocalSocket won't

   234     buffer more than this size of data. Exceptionally, a buffer size of 0

   235     means that the read buffer is unlimited and all incoming data is buffered.

   236     This is the default.

   237 

   238     This option is useful if you only read the data at certain points in

   239     time (e.g., in a real-time streaming application) or if you want to

   240     protect your socket against receiving too much data, which may eventually

   241     cause your application to run out of memory.

   242 

   243     \sa readBufferSize(), read()

   244 */

   245 

   246 /*!

   247     \fn bool QLocalSocket::waitForConnected(int msecs)

   248 

   249     Waits until the socket is connected, up to \a msecs milliseconds. If the

   250     connection has been established, this function returns true; otherwise

   251     it returns false. In the case where it returns false, you can call

   252     error() to determine the cause of the error.

   253 

   254     The following example waits up to one second for a connection

   255     to be established:

   256 

   257     \snippet doc/src/snippets/code/src_network_socket_qlocalsocket_unix.cpp 0

   258 

   259     If \a msecs is -1, this function will not time out.

   260 

   261     \sa connectToServer(), connected()

   262 */

   263 

   264 /*!

   265     \fn bool QLocalSocket::waitForDisconnected(int msecs)

   266 

   267     Waits until the socket has disconnected, up to \a msecs

   268     milliseconds. If the connection has been disconnected, this

   269     function returns true; otherwise it returns false. In the case

   270     where it returns false, you can call error() to determine

   271     the cause of the error.

   272 

   273     The following example waits up to one second for a connection

   274     to be closed:

   275 

   276     \snippet doc/src/snippets/code/src_network_socket_qlocalsocket_unix.cpp 1

   277 

   278     If \a msecs is -1, this function will not time out.

   279 

   280     \sa disconnectFromServer(), close()

   281 */

   282 

   283 /*!

   284     \fn bool QLocalSocket::waitForReadyRead(int msecs)

   285 

   286     This function blocks until data is available for reading and the

   287     \l{QIODevice::}{readyRead()} signal has been emitted. The function

   288     will timeout after \a msecs milliseconds; the default timeout is

   289     30000 milliseconds.

   290 

   291     The function returns true if data is available for reading;

   292     otherwise it returns false (if an error occurred or the

   293     operation timed out).

   294 

   295     \sa waitForBytesWritten()

   296 */

   297 

   298 /*!

   299     \fn void QLocalSocket::disconnected()

   300 

   301     This signal is emitted when the socket has been disconnected.

   302 

   303     \sa connectToServer(), disconnectFromServer(), abort(), connected()

   304 */

   305 

   306 /*!

   307     \fn void QLocalSocket::error(QLocalSocket::LocalSocketError socketError)

   308 

   309     This signal is emitted after an error occurred. The \a socketError

   310     parameter describes the type of error that occurred.

   311 

   312     QLocalSocket::LocalSocketError is not a registered metatype, so for queued

   313     connections, you will have to register it with Q_DECLARE_METATYPE() and

   314     qRegisterMetaType().

   315 

   316     \sa error(), errorString(), {Creating Custom Qt Types}

   317 */

   318 

   319 /*!

   320     \fn void QLocalSocket::stateChanged(QLocalSocket::LocalSocketState socketState)

   321 

   322     This signal is emitted whenever QLocalSocket's state changes.

   323     The \a socketState parameter is the new state.

   324 

   325     QLocalSocket::SocketState is not a registered metatype, so for queued

   326     connections, you will have to register it with Q_DECLARE_METATYPE() and

   327     qRegisterMetaType().

   328 

   329     \sa state(), {Creating Custom Qt Types}

   330 */

   331 

   332 /*!

   333     Creates a new local socket. The \a parent argument is passed to

   334     QObject's constructor.

   335  */

   336 QLocalSocket::QLocalSocket(QObject * parent)

   337     : QIODevice(*new QLocalSocketPrivate, parent)

   338 {

   339     Q_D(QLocalSocket);

   340     d->init();

   341 }

   342 

   343 /*!

   344     Destroys the socket, closing the connection if necessary.

   345  */

   346 QLocalSocket::~QLocalSocket()

   347 {

   348     close();

   349 #ifndef Q_OS_WIN

   350     Q_D(QLocalSocket);

   351     d->unixSocket.setParent(0);

   352 #endif

   353 }

   354 

   355 /*!

   356     Returns the name of the peer as specified by connectToServer(), or an

   357     empty QString if connectToServer() has not been called or it failed.

   358 

   359     \sa connectToServer(), fullServerName()

   360 

   361  */

   362 QString QLocalSocket::serverName() const

   363 {

   364     Q_D(const QLocalSocket);

   365     return d->serverName;

   366 }

   367 

   368 /*!

   369     Returns the server path that the socket is connected to.

   370 

   371     \note The return value of this function is platform specific.

   372 

   373     \sa connectToServer(), serverName()

   374  */

   375 QString QLocalSocket::fullServerName() const

   376 {

   377     Q_D(const QLocalSocket);

   378     return d->fullServerName;

   379 }

   380 

   381 /*!

   382     Returns the state of the socket.

   383 

   384     \sa error()

   385  */

   386 QLocalSocket::LocalSocketState QLocalSocket::state() const

   387 {

   388     Q_D(const QLocalSocket);

   389     return d->state;

   390 }

   391 

   392 /*! \reimp

   393 */

   394 bool QLocalSocket::isSequential() const

   395 {

   396     return true;

   397 }

   398 

   399 /*!

   400     \enum QLocalSocket::LocalSocketError

   401 

   402     The LocalServerError enumeration represents the errors that can occur.

   403     The most recent error can be retrieved through a call to

   404     \l QLocalSocket::error().

   405 

   406     \value ConnectionRefusedError The connection was refused by

   407         the peer (or timed out).

   408     \value PeerClosedError  The remote socket closed the connection.

   409         Note that the client socket (i.e., this socket) will be closed

   410         after the remote close notification has been sent.

   411     \value ServerNotFoundError  The local socket name was not found.

   412     \value SocketAccessError The socket operation failed because the

   413         application lacked the required privileges.

   414     \value SocketResourceError The local system ran out of resources

   415         (e.g., too many sockets).

   416     \value SocketTimeoutError The socket operation timed out.

   417     \value DatagramTooLargeError The datagram was larger than the operating

   418         system's limit (which can be as low as 8192 bytes).

   419     \value ConnectionError An error occurred with the connection.

   420     \value UnsupportedSocketOperationError The requested socket operation

   421         is not supported by the local operating system.

   422     \value UnknownSocketError An unidentified error occurred.

   423  */

   424 

   425 /*!

   426     \enum QLocalSocket::LocalSocketState

   427 

   428     This enum describes the different states in which a socket can be.

   429 

   430     \sa QLocalSocket::state()

   431 

   432     \value UnconnectedState The socket is not connected.

   433     \value ConnectingState The socket has started establishing a connection.

   434     \value ConnectedState A connection is established.

   435     \value ClosingState The socket is about to close

   436         (data may still be waiting to be written).

   437  */

   438 

   439 #ifndef QT_NO_DEBUG_STREAM

   440 QDebug operator<<(QDebug debug, QLocalSocket::LocalSocketError error)

   441 {

   442     switch (error) {

   443     case QLocalSocket::ConnectionRefusedError:

   444         debug << "QLocalSocket::ConnectionRefusedError";

   445         break;

   446     case QLocalSocket::PeerClosedError:

   447         debug << "QLocalSocket::PeerClosedError";

   448         break;

   449     case QLocalSocket::ServerNotFoundError:

   450         debug << "QLocalSocket::ServerNotFoundError";

   451         break;

   452     case QLocalSocket::SocketAccessError:

   453         debug << "QLocalSocket::SocketAccessError";

   454         break;

   455     case QLocalSocket::SocketResourceError:

   456         debug << "QLocalSocket::SocketResourceError";

   457         break;

   458     case QLocalSocket::SocketTimeoutError:

   459         debug << "QLocalSocket::SocketTimeoutError";

   460         break;

   461     case QLocalSocket::DatagramTooLargeError:

   462         debug << "QLocalSocket::DatagramTooLargeError";

   463         break;

   464     case QLocalSocket::ConnectionError:

   465         debug << "QLocalSocket::ConnectionError";

   466         break;

   467     case QLocalSocket::UnsupportedSocketOperationError:

   468         debug << "QLocalSocket::UnsupportedSocketOperationError";

   469         break;

   470     case QLocalSocket::UnknownSocketError:

   471         debug << "QLocalSocket::UnknownSocketError";

   472         break;

   473     default:

   474         debug << "QLocalSocket::SocketError(" << int(error) << ')';

   475         break;

   476     }

   477     return debug;

   478 }

   479 

   480 QDebug operator<<(QDebug debug, QLocalSocket::LocalSocketState state)

   481 {

   482     switch (state) {

   483     case QLocalSocket::UnconnectedState:

   484         debug << "QLocalSocket::UnconnectedState";

   485         break;

   486     case QLocalSocket::ConnectingState:

   487         debug << "QLocalSocket::ConnectingState";

   488         break;

   489     case QLocalSocket::ConnectedState:

   490         debug << "QLocalSocket::ConnectedState";

   491         break;

   492     case QLocalSocket::ClosingState:

   493         debug << "QLocalSocket::ClosingState";

   494         break;

   495     default:

   496         debug << "QLocalSocket::SocketState(" << int(state) << ')';

   497         break;

   498     }

   499     return debug;

   500 }

   501 #endif

   502 

   503 QT_END_NAMESPACE

   504 

   505 #endif

   506 

   507 #include "moc_qlocalsocket.cpp"