QLocalSocket Class

The QLocalSocket class provides a local socket. More...

Header: #include <QLocalSocket>
qmake: QT += network
Since: Qt 4.4
Inherits: QIODevice

Public Types

enum LocalSocketError { ConnectionRefusedError, PeerClosedError, ServerNotFoundError, SocketAccessError, ..., UnknownSocketError }
enum LocalSocketState { UnconnectedState, ConnectingState, ConnectedState, ClosingState }

Public Functions

QLocalSocket(QObject *parent = nullptr)
virtual ~QLocalSocket()
void abort()
void connectToServer(QIODevice::OpenMode openMode = ReadWrite)
void connectToServer(const QString &name, QIODevice::OpenMode openMode = ReadWrite)
void disconnectFromServer()
QLocalSocket::LocalSocketError error() const
bool flush()
QString fullServerName() const
bool isValid() const
qint64 readBufferSize() const
QString serverName() const
void setReadBufferSize(qint64 size)
void setServerName(const QString &name)
bool setSocketDescriptor(qintptr socketDescriptor, QLocalSocket::LocalSocketState socketState = ConnectedState, QIODevice::OpenMode openMode = ReadWrite)
qintptr socketDescriptor() const
QLocalSocket::LocalSocketState state() const
bool waitForConnected(int msecs = 30000)
bool waitForDisconnected(int msecs = 30000)

Reimplemented Public Functions

virtual qint64 bytesAvailable() const override
virtual qint64 bytesToWrite() const override
virtual bool canReadLine() const override
virtual void close() override
virtual bool isSequential() const override
virtual bool open(QIODevice::OpenMode openMode = ReadWrite) override
virtual bool waitForBytesWritten(int msecs = 30000) override
virtual bool waitForReadyRead(int msecs = 30000) override
  • 47 public functions inherited from QIODevice
  • 34 public functions inherited from QObject

Signals

void connected()
void disconnected()
void error(QLocalSocket::LocalSocketError socketError)
void stateChanged(QLocalSocket::LocalSocketState socketState)

Reimplemented Protected Functions

virtual qint64 readData(char *, qint64) override
virtual qint64 writeData(const char *, qint64) override
  • 5 protected functions inherited from QIODevice
  • 9 protected functions inherited from QObject

Additional Inherited Members

  • 1 property inherited from QObject
  • 1 public slot inherited from QObject
  • 1 public variable inherited from QIODevice
  • 1 public variable inherited from QObject
  • 2 static public members inherited from QIODevice
  • 10 static public members inherited from QObject
  • 5 protected functions inherited from QIODevice
  • 9 protected functions inherited from QObject
  • 2 protected variables inherited from QObject

Detailed Description

The QLocalSocket class provides a local socket.

On Windows this is a named pipe and on Unix 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.

See also QLocalServer.

Member Type Documentation

enum QLocalSocket::LocalSocketError

The LocalServerError enumeration represents the errors that can occur. The most recent error can be retrieved through a call to QLocalSocket::error().

ConstantValueDescription
QLocalSocket::ConnectionRefusedErrorQAbstractSocket::ConnectionRefusedErrorThe connection was refused by the peer (or timed out).
QLocalSocket::PeerClosedErrorQAbstractSocket::RemoteHostClosedErrorThe remote socket closed the connection. Note that the client socket (i.e., this socket) will be closed after the remote close notification has been sent.
QLocalSocket::ServerNotFoundErrorQAbstractSocket::HostNotFoundErrorThe local socket name was not found.
QLocalSocket::SocketAccessErrorQAbstractSocket::SocketAccessErrorThe socket operation failed because the application lacked the required privileges.
QLocalSocket::SocketResourceErrorQAbstractSocket::SocketResourceErrorThe local system ran out of resources (e.g., too many sockets).
QLocalSocket::SocketTimeoutErrorQAbstractSocket::SocketTimeoutErrorThe socket operation timed out.
QLocalSocket::DatagramTooLargeErrorQAbstractSocket::DatagramTooLargeErrorThe datagram was larger than the operating system's limit (which can be as low as 8192 bytes).
QLocalSocket::ConnectionErrorQAbstractSocket::NetworkErrorAn error occurred with the connection.
QLocalSocket::UnsupportedSocketOperationErrorQAbstractSocket::UnsupportedSocketOperationErrorThe requested socket operation is not supported by the local operating system.
QLocalSocket::OperationErrorQAbstractSocket::OperationErrorAn operation was attempted while the socket was in a state that did not permit it.
QLocalSocket::UnknownSocketErrorQAbstractSocket::UnknownSocketErrorAn unidentified error occurred.

enum QLocalSocket::LocalSocketState

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

ConstantValueDescription
QLocalSocket::UnconnectedStateQAbstractSocket::UnconnectedStateThe socket is not connected.
QLocalSocket::ConnectingStateQAbstractSocket::ConnectingStateThe socket has started establishing a connection.
QLocalSocket::ConnectedStateQAbstractSocket::ConnectedStateA connection is established.
QLocalSocket::ClosingStateQAbstractSocket::ClosingStateThe socket is about to close (data may still be waiting to be written).

See also QLocalSocket::state().

Member Function Documentation

QLocalSocket::QLocalSocket(QObject *parent = nullptr)

Creates a new local socket. The parent argument is passed to QObject's constructor.

[virtual] QLocalSocket::~QLocalSocket()

Destroys the socket, closing the connection if necessary.

void QLocalSocket::abort()

[override virtual] qint64 QLocalSocket::bytesAvailable() const

[override virtual] qint64 QLocalSocket::bytesToWrite() const

[override virtual] bool QLocalSocket::canReadLine() const

[override virtual] void QLocalSocket::close()

void QLocalSocket::connectToServer(QIODevice::OpenMode openMode = ReadWrite)

void QLocalSocket::connectToServer(const QString &name, QIODevice::OpenMode openMode = ReadWrite)

This is an overloaded function.

Set the server name and attempts to make a connection to it.

The socket is opened in the given openMode and first enters ConnectingState. If a connection is established, QLocalSocket enters ConnectedState and emits connected().

After calling this function, the socket can emit error() to signal that an error occurred.

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

[signal] void QLocalSocket::connected()

void QLocalSocket::disconnectFromServer()

[signal] void QLocalSocket::disconnected()

QLocalSocket::LocalSocketError QLocalSocket::error() const

[signal] void QLocalSocket::error(QLocalSocket::LocalSocketError socketError)

Note: Signal error is overloaded in this class. To connect to this signal by using the function pointer syntax, Qt provides a convenient helper for obtaining the function pointer as shown in this example:


  connect(localSocket, QOverload<QLocalSocket::LocalSocketError>::of(&QLocalSocket::error),
      [=](QLocalSocket::LocalSocketError socketError){ /* ... */ });

bool QLocalSocket::flush()

QString QLocalSocket::fullServerName() const

Returns the server path that the socket is connected to.

Note: The return value of this function is platform specific.

See also connectToServer() and serverName().

[override virtual] bool QLocalSocket::isSequential() const

Reimplemented from QIODevice::isSequential().

bool QLocalSocket::isValid() const

[override virtual] bool QLocalSocket::open(QIODevice::OpenMode openMode = ReadWrite)

qint64 QLocalSocket::readBufferSize() const

See also setReadBufferSize().

[override virtual protected] qint64 QLocalSocket::readData(char *, qint64)

QString QLocalSocket::serverName() const

Returns the name of the peer as specified by setServerName(), or an empty QString if setServerName() has not been called or connectToServer() failed.

See also setServerName(), connectToServer(), and fullServerName().

void QLocalSocket::setReadBufferSize(qint64 size)

See also readBufferSize().

void QLocalSocket::setServerName(const QString &name)

Set the name of the peer to connect to. On Windows name is the name of a named pipe; on Unix name is the name of a local domain socket.

This function must be called when the socket is not connected.

This function was introduced in Qt 5.1.

See also serverName().

bool QLocalSocket::setSocketDescriptor(qintptr socketDescriptor, QLocalSocket::LocalSocketState socketState = ConnectedState, QIODevice::OpenMode openMode = ReadWrite)

See also socketDescriptor().

qintptr QLocalSocket::socketDescriptor() const

See also setSocketDescriptor().

QLocalSocket::LocalSocketState QLocalSocket::state() const

Returns the state of the socket.

See also error().

[signal] void QLocalSocket::stateChanged(QLocalSocket::LocalSocketState socketState)

[override virtual] bool QLocalSocket::waitForBytesWritten(int msecs = 30000)

bool QLocalSocket::waitForConnected(int msecs = 30000)

bool QLocalSocket::waitForDisconnected(int msecs = 30000)

[override virtual] bool QLocalSocket::waitForReadyRead(int msecs = 30000)

[override virtual protected] qint64 QLocalSocket::writeData(const char *, qint64)