source: trunk/src/network/socket/qlocalsocket.cpp@ 788

/****************************************************************************
**
** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
** All rights reserved.
** Contact: Nokia Corporation ([email protected])
**
** This file is part of the QtNetwork module of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** Commercial Usage
** Licensees holding valid Qt Commercial licenses may use this file in
** accordance with the Qt Commercial License Agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and Nokia.
**
** GNU Lesser General Public License Usage
** Alternatively, this file may be used under the terms of the GNU Lesser
** General Public License version 2.1 as published by the Free Software
** Foundation and appearing in the file LICENSE.LGPL included in the
** packaging of this file.  Please review the following information to
** ensure the GNU Lesser General Public License version 2.1 requirements
** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
**
** In addition, as a special exception, Nokia gives you certain additional
** rights.  These rights are described in the Nokia Qt LGPL Exception
** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
**
** GNU General Public License Usage
** Alternatively, this file may be used under the terms of the GNU
** General Public License version 3.0 as published by the Free Software
** Foundation and appearing in the file LICENSE.GPL included in the
** packaging of this file.  Please review the following information to
** ensure the GNU General Public License version 3.0 requirements will be
** met: http://www.gnu.org/copyleft/gpl.html.
**
** If you have questions regarding the use of this file, please contact
** Nokia at [email protected].
** $QT_END_LICENSE$
**
****************************************************************************/

#include "qlocalsocket.h"
#include "qlocalsocket_p.h"

#ifndef QT_NO_LOCALSOCKET

QT_BEGIN_NAMESPACE

/*!
    \class QLocalSocket
    \since 4.4

    \brief The QLocalSocket class provides a local socket.

    On Windows this is a named pipe, on Unix and OS/2 this is a local domain
    socket.

    If an error occurs, socketError() returns the type of error, and
    errorString() can be called to get a human readable description
    of what happened.

    Although QLocalSocket is designed for use with an event loop, it's possible
    to use it without one. In that case, you must use waitForConnected(),
    waitForReadyRead(), waitForBytesWritten(), and waitForDisconnected()
    which blocks until the operation is complete or the timeout expires.

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

    \sa QLocalServer
*/

/*!
    \fn void QLocalSocket::connectToServer(const QString &name, OpenMode openMode)

    Attempts to make a connection to \a name.

    The socket is opened in the given \a openMode and first enters ConnectingState.
    It then attempts to connect to the address or addresses returned by the lookup.
    Finally, if a connection is established, QLocalSocket enters ConnectedState
    and emits connected().

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

    See also state(), serverName(), and waitForConnected().
*/

/*!
    \fn void QLocalSocket::connected()

    This signal is emitted after connectToServer() has been called and
    a connection has been successfully established.

    \sa connectToServer(), disconnected()
*/

/*!
    \fn bool QLocalSocket::setSocketDescriptor(quintptr socketDescriptor,
        LocalSocketState socketState, OpenMode openMode)

    Initializes QLocalSocket with the native socket descriptor
    \a socketDescriptor. Returns true if socketDescriptor is accepted
    as a valid socket descriptor; otherwise returns false. The socket is
    opened in the mode specified by \a openMode, and enters the socket state
    specified by \a socketState.

    \note It is not possible to initialize two local sockets with the same
    native socket descriptor.

    \sa socketDescriptor(), state(), openMode()
*/

/*!
    \fn quintptr QLocalSocket::socketDescriptor() const

    Returns the native socket descriptor of the QLocalSocket object if
    this is available; otherwise returns -1.

    The socket descriptor is not available when QLocalSocket
    is in UnconnectedState.

    \sa setSocketDescriptor()
*/

/*!
    \fn qint64 QLocalSocket::readData(char *data, qint64 c)
    \reimp
*/

/*!
    \fn qint64 QLocalSocket::writeData(const char *data, qint64 c)
    \reimp
*/

/*!
    \fn void QLocalSocket::abort()

    Aborts the current connection and resets the socket.
    Unlike disconnectFromServer(), this function immediately closes the socket,
    clearing any pending data in the write buffer.

    \sa disconnectFromServer(), close()
*/

/*!
    \fn qint64 QLocalSocket::bytesAvailable() const
    \reimp
*/

/*!
    \fn qint64 QLocalSocket::bytesToWrite() const
    \reimp
*/

/*!
    \fn bool QLocalSocket::canReadLine() const
    \reimp
*/

/*!
    \fn void QLocalSocket::close()
    \reimp
*/

/*!
    \fn bool QLocalSocket::waitForBytesWritten(int msecs)
    \reimp
*/

/*!
    \fn bool QLocalSocket::flush()

    This function writes as much as possible from the internal write buffer
    to the socket, without blocking.  If any data was written, this function
    returns true; otherwise false is returned.

    Call this function if you need QLocalSocket to start sending buffered data
    immediately. The number of bytes successfully written depends on the
    operating system. In most cases, you do not need to call this function,
    because QLocalSocket will start sending data automatically once control
    goes back to the event loop. In the absence of an event loop, call
    waitForBytesWritten() instead.

    \sa write(), waitForBytesWritten()
*/

/*!
    \fn void QLocalSocket::disconnectFromServer()

    Attempts to close the socket. If there is pending data waiting to be
    written, QLocalSocket will enter ClosingState and wait until all data
    has been written. Eventually, it will enter UnconnectedState and emit
    the disconnectedFromServer() signal.

    \sa connectToServer()