CopperSpice API  1.7.2
QLocalSocket Class Reference

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

Inheritance diagram for QLocalSocket:
QIODevice QObject

Public Types

enum  LocalSocketError
 
enum  LocalSocketState
 
- Public Types inherited from QIODevice
enum  OpenModeFlag
 

Public Signals

void connected ()
 
void disconnected ()
 
void error (QLocalSocket::LocalSocketError socketError)
 
void stateChanged (QLocalSocket::LocalSocketState socketState)
 
- Public Signals inherited from QIODevice
void aboutToClose ()
 
void bytesWritten (qint64 bytes)
 
void readChannelFinished ()
 
void readyRead ()
 
- Public Signals inherited from QObject
void destroyed (QObject *obj=nullptr)
 
void objectNameChanged (const QString &objectName)
 

Public Methods

 QLocalSocket (QObject *parent=nullptr)
 
 ~QLocalSocket ()
 
void abort ()
 
qint64 bytesAvailable () const override
 
qint64 bytesToWrite () const override
 
bool canReadLine () const override
 
void close () override
 
void connectToServer (const QString &name, OpenMode openMode=ReadWrite)
 
void connectToServer (OpenMode openMode=ReadWrite)
 
void disconnectFromServer ()
 
LocalSocketError error () const
 
bool flush ()
 
QString fullServerName () const
 
bool isSequential () const override
 
bool isValid () const
 
bool open (OpenMode openMode=ReadWrite) override
 
qint64 readBufferSize () const
 
QString serverName () const
 
void setReadBufferSize (qint64 size)
 
bool setSocketDescriptor (qintptr socketDescriptor, LocalSocketState socketState=ConnectedState, OpenMode openMode=ReadWrite)
 
qintptr socketDescriptor () const
 
LocalSocketState state () const
 
bool waitForBytesWritten (int msecs=30000) override
 
bool waitForConnected (int msecs=30000)
 
bool waitForDisconnected (int msecs=30000)
 
bool waitForReadyRead (int msecs=30000) override
 
- Public Methods inherited from QIODevice
 QIODevice ()
 
 QIODevice (QObject *parent)
 
virtual ~QIODevice ()
 
virtual bool atEnd () const
 
QString errorString () const
 
bool getChar (char *c)
 
bool isOpen () const
 
bool isReadable () const
 
bool isTextModeEnabled () const
 
bool isWritable () const
 
OpenMode openMode () const
 
qint64 peek (char *data, qint64 maxSize)
 
QByteArray peek (qint64 maxSize)
 
virtual qint64 pos () const
 
bool putChar (char c)
 
qint64 read (char *data, qint64 maxSize)
 
QByteArray read (qint64 maxSize)
 
QByteArray readAll ()
 
qint64 readLine (char *data, qint64 maxSize)
 
QByteArray readLine (qint64 maxSize=0)
 
virtual bool reset ()
 
virtual bool seek (qint64 pos)
 
void setTextModeEnabled (bool enabled)
 
virtual qint64 size () const
 
void ungetChar (char c)
 
qint64 write (const char *data)
 
qint64 write (const char *data, qint64 maxSize)
 
qint64 write (const QByteArray &data)
 
- Public Methods inherited from QObject
 QObject (QObject *parent=nullptr)
 
 ~QObject ()
 
bool blockSignals (bool block)
 
const QList< QObject * > & children () const
 
bool connect (const QObject *sender, const QString &signalMethod, const QString &location, const QString &slotMethod, Qt::ConnectionType type=Qt::AutoConnection)
 
bool connect (const QObject *sender, const QString &signalMethod, const QString &slotMethod, Qt::ConnectionType type=Qt::AutoConnection)
 
bool disconnect (const QObject *receiver, const QString &slotMethod=QString ()) const
 
bool disconnect (const QString &signalMethod, const QString &location, const QObject *receiver=nullptr, const QString &slotMethod=QString ()) const
 
bool disconnect (const QString &signalMethod=QString (), const QObject *receiver=nullptr, const QString &slotMethod=QString ()) const
 
void dumpObjectInfo ()
 
void dumpObjectTree ()
 
QList< QStringdynamicPropertyNames () const
 
virtual bool event (QEvent *event)
 
virtual bool eventFilter (QObject *watched, QEvent *event)
 
template<typename T >
findChild (const QString &childName=QString ()) const
 
template<class T >
QList< T > findChildren (const QRegularExpression &regExp, Qt::FindChildOptions options=Qt::FindChildrenRecursively) const
 
template<class T >
QList< T > findChildren (const QString &objName=QString (), Qt::FindChildOptions options=Qt::FindChildrenRecursively) const
 
bool inherits (const QString &className) const
 
void installEventFilter (QObject *filterObj)
 
bool isWidgetType () const
 
bool isWindowType () const
 
void killTimer (int id)
 
const QMetaObjectmetaObject () const
 
void moveToThread (QThread *targetThread)
 
QString objectName () const
 
QObject * parent () const
 
template<class T = QVariant>
property (const QString &name) const
 
void removeEventFilter (QObject *obj)
 
void setObjectName (const QString &name)
 
void setParent (QObject *parent)
 
bool setProperty (const QString &name, const QVariant &value)
 
bool signalsBlocked () const
 
int startTimer (int interval, Qt::TimerType timerType=Qt::CoarseTimer)
 
QThreadthread () const
 

Protected Methods

qint64 readData (char *data, qint64 ch) override
 
qint64 writeData (const char *data, qint64 ch) override
 
- Protected Methods inherited from QIODevice
virtual qint64 readLineData (char *data, qint64 maxSize)
 
void setErrorString (const QString &errorString)
 
void setOpenMode (OpenMode openMode)
 
- Protected Methods inherited from QObject
virtual void childEvent (QChildEvent *event)
 
virtual void connectNotify (const QMetaMethod &signalMethod) const
 
virtual void customEvent (QEvent *event)
 
virtual void disconnectNotify (const QMetaMethod &signalMethod) const
 
bool isSignalConnected (const QMetaMethod &signalMethod) const
 
int receivers (const QString &signal) const
 
QObject * sender () const
 
int senderSignalIndex () const
 
virtual void timerEvent (QTimerEvent *event)
 

Additional Inherited Members

- Public Typedefs inherited from QIODevice
using OpenMode = QFlags< OpenModeFlag >
 
- Public Slots inherited from QObject
void deleteLater ()
 
- Static Public Methods inherited from QObject
static bool connect (const QObject *sender, const QMetaMethod &signalMethod, const QObject *receiver, const QMetaMethod &slotMethod, Qt::ConnectionType type=Qt::AutoConnection)
 
static bool connect (const QObject *sender, const QString &signalMethod, const QObject *receiver, const QString &slotMethod, Qt::ConnectionType type=Qt::AutoConnection, const QString &location=QString ())
 
static bool connect (const QObject *sender, const QString &signalMethod, const QString &location, const QObject *receiver, const QString &slotMethod, Qt::ConnectionType type=Qt::AutoConnection)
 
template<class Sender , class SignalClass , class... SignalArgs, class Receiver , class SlotClass , class... SlotArgs, class SlotReturn >
static bool connect (const Sender *sender, void (SignalClass::*signalMethod)(SignalArgs...), const Receiver *receiver, SlotReturn (SlotClass::*slotMethod)(SlotArgs...), Qt::ConnectionType type=Qt::AutoConnection)
 
template<class Sender , class SignalClass , class... SignalArgs, class Receiver , class T >
static bool connect (const Sender *sender, void (SignalClass::*signalMethod)(SignalArgs...), const Receiver *receiver, T slotLambda, Qt::ConnectionType type=Qt::AutoConnection)
 
static bool disconnect (const QObject *sender, const QMetaMethod &signalMethod, const QObject *receiver, const QMetaMethod &slotMethod)
 
static bool disconnect (const QObject *sender, const QString &signalMethod, const QObject *receiver, const QString &slotMethod)
 
static bool disconnect (const QObject *sender, const QString &signalMethod, const QString &location, const QObject *receiver, const QString &slotMethod)
 
template<class Sender , class SignalClass , class... SignalArgs, class Receiver , class SlotClass , class... SlotArgs, class SlotReturn >
static bool disconnect (const Sender *sender, void (SignalClass::*signalMethod)(SignalArgs...), const Receiver *receiver, SlotReturn (SlotClass::*slotMethod)(SlotArgs...))
 
template<class Sender , class SignalClass , class... SignalArgs, class Receiver >
static bool disconnect (const Sender *sender, void (SignalClass::*signalMethod)(SignalArgs...), const Receiver *receiver, std::nullptr_t slotMethod=nullptr)
 
template<class Sender , class SignalClass , class... SignalArgs, class Receiver , class T >
static bool disconnect (const Sender *sender, void (SignalClass::*signalMethod)(SignalArgs...), const Receiver *receiver, T slotMethod)
 
static QMetaObjectstaticMetaObject ()
 
static QString tr (const char *text, const char *comment=nullptr, std::optional< int > numArg=std::optional< int >())
 
- Properties inherited from QObject
 objectName
 

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 Enumeration Documentation

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::UnknownSocketErrorQAbstractSocket::UnknownSocketErrorAn unidentified error occurred.

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()

Constructor & Destructor Documentation

QLocalSocket::QLocalSocket ( QObject parent = nullptr)

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

QLocalSocket::~QLocalSocket ( )

Destroys the socket, closing the connection if necessary.

Method Documentation

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.

See also
disconnectFromServer(), close()
qint64 QLocalSocket::bytesAvailable ( ) const
overridevirtual

Reimplemented from QIODevice::bytesAvailable().

Reimplemented from QIODevice.

qint64 QLocalSocket::bytesToWrite ( ) const
overridevirtual

Reimplemented from QIODevice::bytesToWrite().

Reimplemented from QIODevice.

bool QLocalSocket::canReadLine ( ) const
overridevirtual

Reimplemented from QIODevice::canReadLine().

Reimplemented from QIODevice.

void QLocalSocket::close ( )
overridevirtual

Reimplemented from QIODevice::close().

Reimplemented from QIODevice.

void QLocalSocket::connected ( )
signal

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

See also
connectToServer(), disconnected()
void QLocalSocket::connectToServer ( const QString name,
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 method the socket can emit error() to signal that an error occurred.

See also
state(), serverName(), waitForConnected()
void QLocalSocket::connectToServer ( OpenMode  openMode = ReadWrite)

Attempts to make a connection to serverName(). setServerName() must be called before you open the connection. Alternatively you can use connectToServer(const QString &name, OpenMode openMode);

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 method the socket can emit error() to signal that an error occurred.

See also
state(), serverName(), waitForConnected()
void QLocalSocket::disconnected ( )
signal

This signal is emitted when the socket has been disconnected.

See also
connectToServer(), disconnectFromServer(), abort(), connected()
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.

See also
connectToServer()
LocalSocketError QLocalSocket::error ( ) const

Returns the type of error that last occurred.

See also
state(), errorString()
void QLocalSocket::error ( QLocalSocket::LocalSocketError  socketError)
signal

This signal is emitted after an error occurred. The socketError parameter describes the type of error that occurred.

See also
error(), errorString(), Creating Custom Types
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.

See also
write(), waitForBytesWritten()
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(), serverName()
bool QLocalSocket::isSequential ( ) const
overridevirtual

Reimplemented from QIODevice::isSequential().

Reimplemented from QIODevice.

bool QLocalSocket::isValid ( ) const

Returns true if the socket is valid and ready for use, otherwise returns false.

Note
The socket's state must be ConnectedState before reading and writing can occur.
See also
state(), connectToServer()
bool QLocalSocket::open ( OpenMode  mode = ReadWrite)
overridevirtual

Opens the device and sets its OpenMode to mode. Returns true if successful, otherwise returns false. This method should be called from any existing reimplementation of open() or other functions that open the device.

See also
openMode(), OpenMode

Reimplemented from QIODevice.

qint64 QLocalSocket::readBufferSize ( ) const

Returns the size of the internal read buffer. This limits the amount of data that the client can receive before you call read() or readAll(). A read buffer size of 0 (the default) means that the buffer has no size limit, ensuring that no data is lost.

See also
setReadBufferSize(), read()
qint64 QLocalSocket::readData ( char *  data,
qint64  ch 
)
overrideprotectedvirtual

Reimplemented from QIODevice::readData().

Implements QIODevice.

QString QLocalSocket::serverName ( ) const

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

See also
connectToServer(), fullServerName()
void QLocalSocket::setReadBufferSize ( qint64  size)

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

If the buffer size is limited to a certain size, QLocalSocket will not buffer more than this size of data. Exceptionally, a buffer size of 0 means that the read buffer is unlimited and all incoming data is buffered. This is the default.

This option is useful if you only read the data at certain points in time (e.g., in a real-time streaming application) or if you want to protect your socket against receiving too much data, which may eventually cause your application to run out of memory.

See also
readBufferSize(), read()
bool QLocalSocket::setSocketDescriptor ( qintptr  socketDescriptor,
LocalSocketState  socketState = ConnectedState,
OpenMode  openMode = ReadWrite 
)

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

Note
It is not possible to initialize two local sockets with the same native socket descriptor.
See also
socketDescriptor(), state(), openMode()
qintptr 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.

See also
setSocketDescriptor()
LocalSocketState QLocalSocket::state ( ) const

Returns the state of the socket.

See also
error()
void QLocalSocket::stateChanged ( QLocalSocket::LocalSocketState  socketState)
signal

This signal is emitted whenever QLocalSocket's state changes. The socketState parameter is the new state.

See also
state(), Creating Custom Types
bool QLocalSocket::waitForBytesWritten ( int  msecs = 30000)
overridevirtual

Reimplemented from QIODevice::waitForBytesWritten().

Reimplemented from QIODevice.

bool QLocalSocket::waitForConnected ( int  msecs = 30000)

Waits until the socket is connected, up to msecs milliseconds. If the connection has been established, this function returns true, otherwise it returns false. In the case where it returns false, you can call error() to determine the cause of the error.

The following example waits up to one second for a connection to be established:

socket->connectToServer("market");
if (socket->waitForConnected(1000)) {
qDebug("Connected!");
}

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

See also
connectToServer(), connected()
bool QLocalSocket::waitForDisconnected ( int  msecs = 30000)

Waits until the socket has disconnected, up to msecs milliseconds. If the connection has been disconnected, this function returns true, otherwise it returns false. In the case where it returns false, you can call error() to determine the cause of the error.

The following example waits up to one second for a connection to be closed:

socket->disconnectFromServer();
if (socket->waitForDisconnected(1000))
qDebug("Disconnected!");

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

See also
disconnectFromServer(), close()
bool QLocalSocket::waitForReadyRead ( int  msecs = 30000)
overridevirtual

Reimplemented from QIODevice::waitForReadyRead().

This function blocks until data is available for reading and the readyRead() signal has been emitted. The function will timeout after msecs milliseconds; the default timeout is 30000 milliseconds.

The function returns true if data is available for reading, otherwise it returns false (if an error occurred or the operation timed out).

See also
waitForBytesWritten()

Reimplemented from QIODevice.

qint64 QLocalSocket::writeData ( const char *  data,
qint64  ch 
)
overrideprotectedvirtual

Reimplemented from QIODevice::writeData().

Implements QIODevice.