Contents

• Public Types
• Public Functions
• Reimplemented Public Functions
• Signals
• Reimplemented Protected Functions
• Detailed Description

Detailed Description

TheQLocalSocket 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, anderrorString() can be called to get a human readable description of what happened.

AlthoughQLocalSocket is designed for use with an event loop, it's possible to use it without one. In that case, you must usewaitForConnected(),waitForReadyRead(),waitForBytesWritten(), andwaitForDisconnected() 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.

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 toQLocalSocket::error().

enum QLocalSocket::LocalSocketState

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

See alsoQLocalSocket::state().

Member Function Documentation

QLocalSocket::QLocalSocket(QObject * parent = 0)

Creates a new local socket. Theparent argument is passed toQObject's constructor.

QLocalSocket::~QLocalSocket()

Destroys the socket, closing the connection if necessary.

void QLocalSocket::abort()

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

See alsodisconnectFromServer() andclose().

[virtual]qint64 QLocalSocket::bytesAvailable() const

Reimplemented fromQIODevice::bytesAvailable().

[virtual]qint64 QLocalSocket::bytesToWrite() const

Reimplemented fromQIODevice::bytesToWrite().

[virtual]bool QLocalSocket::canReadLine() const

Reimplemented fromQIODevice::canReadLine().

[virtual]void QLocalSocket::close()

Reimplemented fromQIODevice::close().

void QLocalSocket::connectToServer(constQString & name,OpenMode openMode = ReadWrite)

Attempts to make a connection toname.

The socket is opened in the givenopenMode and first entersConnectingState. It then attempts to connect to the address or addresses returned by the lookup. Finally, if a connection is established,QLocalSocket entersConnectedState and emitsconnected().

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

See alsostate(),serverName(), andwaitForConnected().

[signal]void QLocalSocket::connected()

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

See alsoconnectToServer() anddisconnected().

void QLocalSocket::disconnectFromServer()

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

See alsoconnectToServer().

[signal]void QLocalSocket::disconnected()

This signal is emitted when the socket has been disconnected.

See alsoconnectToServer(),disconnectFromServer(),abort(), andconnected().

LocalSocketError QLocalSocket::error() const

Returns the type of error that last occurred.

See alsostate() anderrorString().

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

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

QLocalSocket::LocalSocketError is not a registered metatype, so for queued connections, you will have to register it withQ_DECLARE_METATYPE() andqRegisterMetaType().

Note:Signalerror is overloaded in this class. To connect to this one using the function pointer syntax, you must specify the signal type in a static cast, as shown in this example:

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

See alsoerror(),errorString(), andCreating Custom Qt 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 needQLocalSocket 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, becauseQLocalSocket will start sending data automatically once control goes back to the event loop. In the absence of an event loop, callwaitForBytesWritten() instead.

See alsowrite() andwaitForBytesWritten().

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 alsoconnectToServer() andserverName().

[virtual]bool QLocalSocket::isSequential() const

Reimplemented fromQIODevice::isSequential().

bool QLocalSocket::isValid() const

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

Note:The socket's state must beConnectedState before reading and writing can occur.

See alsostate() andconnectToServer().

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 callread() orreadAll(). A read buffer size of 0 (the default) means that the buffer has no size limit, ensuring that no data is lost.

See alsosetReadBufferSize() andread().

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

Reimplemented fromQIODevice::readData().

QString QLocalSocket::serverName() const

Returns the name of the peer as specified byconnectToServer(), or an emptyQString ifconnectToServer() has not been called or it failed.

See alsoconnectToServer() andfullServerName().

void QLocalSocket::setReadBufferSize(qint64 size)

Sets the size ofQLocalSocket's internal read buffer to besize bytes.

If the buffer size is limited to a certain size,QLocalSocket won't 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 alsoreadBufferSize() andread().

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

InitializesQLocalSocket with the native socket descriptorsocketDescriptor. Returns true ifsocketDescriptor is accepted as a valid socket descriptor; otherwise returns false. The socket is opened in the mode specified byopenMode, and enters the socket state specified bysocketState.

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

See alsosocketDescriptor(),state(), andopenMode().

quintptr QLocalSocket::socketDescriptor() const

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

The socket descriptor is not available whenQLocalSocket is inUnconnectedState.

See alsosetSocketDescriptor().

LocalSocketState QLocalSocket::state() const

Returns the state of the socket.

See alsoerror().

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

This signal is emitted wheneverQLocalSocket's state changes. ThesocketState parameter is the new state.

QLocalSocket::SocketState is not a registered metatype, so for queued connections, you will have to register it withQ_DECLARE_METATYPE() andqRegisterMetaType().

See alsostate() andCreating Custom Qt Types.

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

Reimplemented fromQIODevice::waitForBytesWritten().

bool QLocalSocket::waitForConnected(int msecs = 30000)

Waits until the socket is connected, up tomsecs milliseconds. If the connection has been established, this function returns true; otherwise it returns false. In the case where it returns false, you can callerror() 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!");

Ifmsecs is -1, this function will not time out.

See alsoconnectToServer() andconnected().

bool QLocalSocket::waitForDisconnected(int msecs = 30000)

Waits until the socket has disconnected, up tomsecs milliseconds. If the connection has been disconnected, this function returns true; otherwise it returns false. In the case where it returns false, you can callerror() 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!");

Ifmsecs is -1, this function will not time out.

See alsodisconnectFromServer() andclose().

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

Reimplemented fromQIODevice::waitForReadyRead().

This function blocks until data is available for reading and thereadyRead() signal has been emitted. The function will timeout aftermsecs 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 alsowaitForBytesWritten().

[virtual protected]qint64 QLocalSocket::writeData(constchar * data,qint64 c)

Reimplemented fromQIODevice::writeData().