- Qt 6.10
- Qt Network
- C++ Classes
- QLocalSocket
- Qt 6.10.2 Reference Documentation

# QLocalSocket Class

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

Header: | `#include <QLocalSocket>`
CMake: | `find_package(Qt6 REQUIRED COMPONENTS Network)` `target_link_libraries(mytarget PRIVATE Qt6::Network)`
qmake: | `QT += network`
Inherits: | QIODevice

- List of all members, including inherited members

## Public Types

enum | LocalSocketError { ConnectionRefusedError, PeerClosedError, ServerNotFoundError, SocketAccessError, SocketResourceError, …, UnknownSocketError }
enum | LocalSocketState { UnconnectedState, ConnectingState, ConnectedState, ClosingState }
`(since 6.2)` enum | SocketOption { NoOptions, AbstractNamespaceOption }
flags | SocketOptions

## Properties

- `(since 6.2)` socketOptions : SocketOptions

## Public Functions

| QLocalSocket(QObject *parent = nullptr)
virtual | ~QLocalSocket()
QBindable<QLocalSocket::SocketOptions> | bindableSocketOptions()
void | connectToServer(const QString &name, QIODeviceBase::OpenMode openMode = ReadWrite)
QString | fullServerName() const
QString | serverName() const
void | setServerName(const QString &name)
void | setSocketOptions(QLocalSocket::SocketOptions option)
QLocalSocket::SocketOptions | socketOptions() const
QLocalSocket::LocalSocketState | state() const

## Reimplemented Public Functions

virtual bool | isSequential() const override

## Detailed Description

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

If an error occurs, error() 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().

Constant | Value | Description
--- | --- | ---
`QLocalSocket::ConnectionRefusedError` | `QAbstractSocket::ConnectionRefusedError` | The connection was refused by the peer (or timed out).
`QLocalSocket::PeerClosedError` | `QAbstractSocket::RemoteHostClosedError` | The 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::ServerNotFoundError` | `QAbstractSocket::HostNotFoundError` | The local socket name was not found.
`QLocalSocket::SocketAccessError` | `QAbstractSocket::SocketAccessError` | The socket operation failed because the application lacked the required privileges.
`QLocalSocket::SocketResourceError` | `QAbstractSocket::SocketResourceError` | The local system ran out of resources (e.g., too many sockets).
`QLocalSocket::SocketTimeoutError` | `QAbstractSocket::SocketTimeoutError` | The socket operation timed out.
`QLocalSocket::DatagramTooLargeError` | `QAbstractSocket::DatagramTooLargeError` | The datagram was larger than the operating system's limit (which can be as low as 8192 bytes).
`QLocalSocket::ConnectionError` | `QAbstractSocket::NetworkError` | An error occurred with the connection.
`QLocalSocket::UnsupportedSocketOperationError` | `QAbstractSocket::UnsupportedSocketOperationError` | The requested socket operation is not supported by the local operating system.
`QLocalSocket::OperationError` | `QAbstractSocket::OperationError` | An operation was attempted while the socket was in a state that did not permit it.
`QLocalSocket::UnknownSocketError` | `QAbstractSocket::UnknownSocketError` | An unidentified error occurred.

### enum QLocalSocket::LocalSocketState

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

Constant | Value | Description
--- | --- | ---
`QLocalSocket::UnconnectedState` | `QAbstractSocket::UnconnectedState` | The socket is not connected.
`QLocalSocket::ConnectingState` | `QAbstractSocket::ConnectingState` | The socket has started establishing a connection.
`QLocalSocket::ConnectedState` | `QAbstractSocket::ConnectedState` | A connection is established.
`QLocalSocket::ClosingState` | `QAbstractSocket::ClosingState` | The socket is about to close (data may still be waiting to be written).

See also QLocalSocket::state().

### `[since 6.2]` enum QLocalSocket::SocketOption
flags QLocalSocket::SocketOptions

This enum describes the possible options that can be used to connect to a server. Currently, on Linux and Android it is used for specifying connection to a server listening to a socket bound to an abstract address.

Constant | Value | Description
--- | --- | ---
`QLocalSocket::NoOptions` | `0x00` | No options have been set.
`QLocalSocket::AbstractNamespaceOption` | `0x01` | The socket will try to connect to an abstract address. This flag is specific to Linux and Android. On other platforms is ignored.

This enum was introduced in Qt 6.2.

The SocketOptions type is a typedef for QFlags<SocketOption>. It stores an OR combination of SocketOption values.

See also socketOptions.

## Property Documentation

### `[bindable, since 6.2]` socketOptions : SocketOptions

Note: This property supports QProperty bindings.

This property holds the socket options.

Options must be set while the socket is in UnconnectedState state.

This property was introduced in Qt 6.2.

Access functions:

QLocalSocket::SocketOptions | socketOptions() const
void | setSocketOptions(QLocalSocket::SocketOptions option)

See also connectToServer().

## Member Function Documentation

### QLocalSocket::QLocalSocket(QObject *parent = nullptr)

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

### `[virtual noexcept]` QLocalSocket::~QLocalSocket()

Destroys the socket, closing the connection if necessary.

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

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 errorOccurred() to signal that an error occurred.

This is an overloaded function.

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

### 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

Reimplements: QIODevice::isSequential() const.

### 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::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.

See also serverName().

### QLocalSocket::LocalSocketState QLocalSocket::state() const

Returns the state of the socket.

See also error().