The QLocalServer class provides a local socket based server. More...

#include <qlocalserver.h>

Inheritance diagram for QLocalServer:

Collaboration diagram for QLocalServer:

Public Types
enum	SocketOption { NoOptions = 0x0 , UserAccessOption = 0x01 , GroupAccessOption = 0x2 , OtherAccessOption = 0x4 , WorldAccessOption = 0x7 , AbstractNamespaceOption = 0x8 }

Signals
void	newConnection ()

Signals inherited from QObject
void	destroyed (QObject *=nullptr)

void	objectNameChanged (const QString &objectName, QPrivateSignal)

Public Member Functions
	QLocalServer (QObject *parent=nullptr)

	~QLocalServer ()

void	close ()

QString	errorString () const

virtual bool	hasPendingConnections () const

bool	isListening () const

bool	listen (const QString &name)

bool	listen (qintptr socketDescriptor)

int	maxPendingConnections () const

virtual QLocalSocket *	nextPendingConnection ()

QString	serverName () const

QString	fullServerName () const

QAbstractSocket::SocketError	serverError () const

void	setMaxPendingConnections (int numConnections)

bool	waitForNewConnection (int msec=0, bool *timedOut=nullptr)

void	setListenBacklogSize (int size)

int	listenBacklogSize () const

void	setSocketOptions (SocketOptions options)

SocketOptions	socketOptions () const

QBindable< SocketOptions >	bindableSocketOptions ()

qintptr	socketDescriptor () const

Public Member Functions inherited from QObject
Q_INVOKABLE	QObject (QObject *parent=nullptr)

virtual	~QObject ()

virtual bool	event (QEvent *event)

virtual bool	eventFilter (QObject watched, QEvent event)

QString	objectName () const

void	setObjectName (const QString &name)

QBindable< QString >	bindableObjectName ()

bool	isWidgetType () const

bool	isWindowType () const

bool	signalsBlocked () const noexcept

bool	blockSignals (bool b) noexcept

QThread *	thread () const

void	moveToThread (QThread *thread)

int	startTimer (int interval, Qt::TimerType timerType=Qt::CoarseTimer)

void	killTimer (int id)

template<typename T >
T	findChild (const QString &aName=QString(), Qt::FindChildOptions options=Qt::FindChildrenRecursively) const

template<typename T >
QList< T >	findChildren (const QString &aName, Qt::FindChildOptions options=Qt::FindChildrenRecursively) const

template<typename T >
QList< T >	findChildren (Qt::FindChildOptions options=Qt::FindChildrenRecursively) const

const QObjectList &	children () const

void	setParent (QObject *parent)

void	installEventFilter (QObject *filterObj)

void	removeEventFilter (QObject *obj)

QMetaObject::Connection	connect (const QObject sender, const char signal, const char *member, Qt::ConnectionType type=Qt::AutoConnection) const

bool	disconnect (const char signal=nullptr, const QObject receiver=nullptr, const char *member=nullptr) const

bool	disconnect (const QObject receiver, const char member=nullptr) const

void	dumpObjectTree () const

void	dumpObjectInfo () const

bool	setProperty (const char *name, const QVariant &value)

QVariant	property (const char *name) const

QList< QByteArray >	dynamicPropertyNames () const

QBindingStorage *	bindingStorage ()

const QBindingStorage *	bindingStorage () const

QObject *	parent () const

bool	inherits (const char *classname) const

Static Public Member Functions
static bool	removeServer (const QString &name)

Static Public Member Functions inherited from QObject
static QMetaObject::Connection	connect (const QObject sender, const char signal, const QObject receiver, const char member, Qt::ConnectionType=Qt::AutoConnection)

static QMetaObject::Connection	connect (const QObject sender, const QMetaMethod &signal, const QObject receiver, const QMetaMethod &method, Qt::ConnectionType type=Qt::AutoConnection)

template<typename Func1 , typename Func2 >
static QMetaObject::Connection	connect (const typename QtPrivate::FunctionPointer< Func1 >::Object sender, Func1 signal, const typename QtPrivate::FunctionPointer< Func2 >::Object receiver, Func2 slot, Qt::ConnectionType type=Qt::AutoConnection)

static QMetaObject::Connection ::type	connect (const typename QtPrivate::FunctionPointer< Func1 >::Object *sender, Func1 signal, Func2 slot)

static QMetaObject::Connection ::type	connect (const typename QtPrivate::FunctionPointer< Func1 >::Object sender, Func1 signal, const QObject context, Func2 slot, Qt::ConnectionType type=Qt::AutoConnection)

template<typename Func1 , typename Func2 >
static std::enable_if< QtPrivate::FunctionPointer< Func2 >::ArgumentCount==-1 &&!std::is_convertible_v< Func2, const char * >, QMetaObject::Connection >::type	connect (const typename QtPrivate::FunctionPointer< Func1 >::Object *sender, Func1 signal, Func2 slot)

template<typename Func1 , typename Func2 >
static std::enable_if< QtPrivate::FunctionPointer< Func2 >::ArgumentCount==-1 &&!std::is_convertible_v< Func2, const char * >, QMetaObject::Connection >::type	connect (const typename QtPrivate::FunctionPointer< Func1 >::Object sender, Func1 signal, const QObject context, Func2 slot, Qt::ConnectionType type=Qt::AutoConnection)

static bool	disconnect (const QObject sender, const char signal, const QObject receiver, const char member)

static bool	disconnect (const QObject sender, const QMetaMethod &signal, const QObject receiver, const QMetaMethod &member)

static bool	disconnect (const QMetaObject::Connection &)

template<typename Func1 , typename Func2 >
static bool	disconnect (const typename QtPrivate::FunctionPointer< Func1 >::Object sender, Func1 signal, const typename QtPrivate::FunctionPointer< Func2 >::Object receiver, Func2 slot)

template<typename Func1 >
static bool	disconnect (const typename QtPrivate::FunctionPointer< Func1 >::Object sender, Func1 signal, const QObject receiver, void **zero)

Protected Member Functions
virtual void	incomingConnection (quintptr socketDescriptor)

Protected Member Functions inherited from QObject
QObject *	sender () const

int	senderSignalIndex () const

int	receivers (const char *signal) const

bool	isSignalConnected (const QMetaMethod &signal) const

virtual void	timerEvent (QTimerEvent *event)

virtual void	childEvent (QChildEvent *event)

virtual void	customEvent (QEvent *event)

virtual void	connectNotify (const QMetaMethod &signal)

virtual void	disconnectNotify (const QMetaMethod &signal)

	QObject (QObjectPrivate &dd, QObject *parent=nullptr)

Properties
SocketOptions	socketOptions
	the socket options that control how the socket operates. More...

Properties inherited from QObject
QString	objectName
	the name of this object More...

Additional Inherited Members
Public Slots inherited from QObject
void	deleteLater ()

Protected Attributes inherited from QObject
QScopedPointer< QObjectData >	d_ptr

Related Functions inherited from QObject
template< class T > T	qobject_cast (const QObject *object)

template< typename T > T	qFindChildqFindChildren (const QObject *obj, const QString &name)()

template< typename T > QList< T >	qFindChildrenqFindChildren (const QObject *obj, const QString &name)()

	QObjectList

Detailed Description

The QLocalServer class provides a local socket based server.

Since: 4.4 \inmodule QtNetwork

This class makes it possible to accept incoming local socket connections.

Call listen() to have the server start listening for incoming connections on a specified key. The newConnection() signal is then emitted each time a client connects to the server.

Call nextPendingConnection() to accept the pending connection as a connected QLocalSocket. The function returns a pointer to a QLocalSocket that can be used for communicating with the client.

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

When listening for connections, the name which the server is listening on is available through serverName().

Calling close() makes QLocalServer stop listening for incoming connections.

Although QLocalServer is designed for use with an event loop, it's possible to use it without one. In that case, you must use waitForNewConnection(), which blocks until either a connection is available or a timeout expires.

See also: QLocalSocket, QTcpServer

Definition at line 55 of file qlocalserver.h.

Member Enumeration Documentation

◆ SocketOption

enum QLocalServer::SocketOption

Since: 5.0

This enum describes the possible options that can be used to create the socket. This changes the access permissions on platforms (Linux, Windows) that support access permissions on the socket. Both GroupAccess and OtherAccess may vary slightly in meanings depending on the platform. On Linux and Android it is possible to use sockets with abstract addresses; socket permissions have no meaning for such sockets.

\value NoOptions No access restrictions have been set. \value UserAccessOption Access is restricted to the same user as the process that created the socket. \value GroupAccessOption Access is restricted to the same group but not the user that created the socket on Linux. Access is restricted to the primary group of the process on Windows \value OtherAccessOption Access is available to everyone but the user and group that created the socket on Linux. Access is available to everyone on Windows. \value WorldAccessOption No access restrictions. \value AbstractNamespaceOption The listening socket will be created in the abstract namespace. This flag is specific to Linux. In case of other platforms, for the sake of code portability, this flag is equivalent to WorldAccessOption.

See also: socketOptions

Enumerator
NoOptions
UserAccessOption
GroupAccessOption
OtherAccessOption
WorldAccessOption
AbstractNamespaceOption

Definition at line 66 of file qlocalserver.h.

Constructor & Destructor Documentation

◆ QLocalServer()

QLocalServer::QLocalServer ( QObject * parent = nullptr )

explicit

Create a new local socket server with the given parent.

See also: listen()

Definition at line 121 of file qlocalserver.cpp.

◆ ~QLocalServer()

QLocalServer::~QLocalServer ( )

Destroys the QLocalServer object. If the server is listening for connections, it is automatically closed.

Any client QLocalSockets that are still connected must either disconnect or be reparented before the server is deleted.

See also: close()

Definition at line 137 of file qlocalserver.cpp.

Here is the call graph for this function:

Member Function Documentation

◆ bindableSocketOptions()

QBindable< QLocalServer::SocketOptions > QLocalServer::bindableSocketOptions ( )

Definition at line 199 of file qlocalserver.cpp.

◆ close()

void QLocalServer::close ( )

Stop listening for incoming connections. Existing connections are not affected, but any new connections will be refused.

See also: isListening(), listen()

Definition at line 246 of file qlocalserver.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ errorString()

QString QLocalServer::errorString ( ) const

Returns the human-readable message appropriate to the current error reported by serverError(). If no suitable string is available, an empty string is returned.

See also: serverError()

Definition at line 267 of file qlocalserver.cpp.

Here is the caller graph for this function:

◆ fullServerName()

QString QLocalServer::fullServerName ( ) const

Returns the full path that the server is listening on.

Note: This is platform specific

See also: listen(), serverName()

Definition at line 489 of file qlocalserver.cpp.

◆ hasPendingConnections()

bool QLocalServer::hasPendingConnections ( ) const

virtual

Returns true if the server has a pending connection; otherwise returns false.

See also: nextPendingConnection(), setMaxPendingConnections()

Definition at line 279 of file qlocalserver.cpp.

◆ incomingConnection()

void QLocalServer::incomingConnection ( quintptr socketDescriptor )

protectedvirtual

This virtual function is called by QLocalServer when a new connection is available. socketDescriptor is the native socket descriptor for the accepted connection.

The base implementation creates a QLocalSocket, sets the socket descriptor and then stores the QLocalSocket in an internal list of pending connections. Finally newConnection() is emitted.

Reimplement this function to alter the server's behavior when a connection is available.

See also: newConnection(), nextPendingConnection(), QLocalSocket::setSocketDescriptor()

Reimplemented in LocalServer.

Definition at line 300 of file qlocalserver.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ isListening()

bool QLocalServer::isListening ( ) const

Returns true if the server is listening for incoming connections otherwise false.

See also: listen(), close()

Definition at line 315 of file qlocalserver.cpp.

Here is the caller graph for this function:

◆ listen() [1/2]

bool QLocalServer::listen ( const QString & name )

Tells the server to listen for incoming connections on name. If the server is currently listening then it will return false. Return true on success otherwise false.

name can be a single name and QLocalServer will determine the correct platform specific path. serverName() will return the name that is passed into listen.

Usually you would just pass in a name like "foo", but on Unix this could also be a path such as "/tmp/foo" and on Windows this could be a pipe path such as "\\\\.\\pipe\\foo"

Note: On Unix if the server crashes without closing listen will fail with AddressInUseError. To create a new server the file should be removed. On Windows two local servers can listen to the same pipe at the same time, but any connections will go to one of the server.

See also: serverName(), isListening(), close()

Definition at line 341 of file qlocalserver.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ listen() [2/2]

bool QLocalServer::listen ( qintptr socketDescriptor )

Since: 5.0

Instructs the server to listen for incoming connections on socketDescriptor. The property returns false if the server is currently listening. It returns true on success; otherwise, it returns false. The socket must be ready to accept new connections with no extra platform-specific functions called. The socket is set into non-blocking mode.

serverName(), fullServerName() may return a string with a name if this option is supported by the platform; otherwise, they return an empty QString. In particular, the addresses of sockets in the abstract namespace supported by Linux will not yield useful names if they contain unprintable characters.

See also: isListening(), close()

Definition at line 384 of file qlocalserver.cpp.

Here is the call graph for this function:

◆ listenBacklogSize()

int QLocalServer::listenBacklogSize ( ) const

Returns the backlog queue size of to be accepted connections.

Since: 6.3

See also: setListenBacklogSize()

Definition at line 580 of file qlocalserver.cpp.

◆ maxPendingConnections()

int QLocalServer::maxPendingConnections ( ) const

Returns the maximum number of pending accepted connections. The default is 30.

See also: setMaxPendingConnections(), hasPendingConnections()

Definition at line 408 of file qlocalserver.cpp.

◆ newConnection

void QLocalServer::newConnection ( )

signal

This signal is emitted every time a new connection is available.

See also: hasPendingConnections(), nextPendingConnection()

Here is the caller graph for this function:

◆ nextPendingConnection()

QLocalSocket * QLocalServer::nextPendingConnection ( )

virtual

Returns the next pending connection as a connected QLocalSocket object.

The socket is created as a child of the server, which means that it is automatically deleted when the QLocalServer object is destroyed. It is still a good idea to delete the object explicitly when you are done with it, to avoid wasting memory.

\nullptr is returned if this function is called when there are no pending connections.

See also: hasPendingConnections(), newConnection(), incomingConnection()

Definition at line 435 of file qlocalserver.cpp.

◆ removeServer()

bool QLocalServer::removeServer ( const QString & name )

static

Since: 4.5

Removes any server instance that might cause a call to listen() to fail and returns true if successful; otherwise returns false. This function is meant to recover from a crash, when the previous server instance has not been cleaned up.

On Windows, this function does nothing; on Unix, it removes the socket file given by name.

Warning: Be careful to avoid removing sockets of running instances.

Definition at line 465 of file qlocalserver.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ serverError()

QAbstractSocket::SocketError QLocalServer::serverError ( ) const

Returns the type of error that occurred last or NoError.

See also: errorString()

Definition at line 500 of file qlocalserver.cpp.

◆ serverName()

QString QLocalServer::serverName ( ) const

Returns the server name if the server is listening for connections; otherwise returns QString()

See also: listen(), fullServerName()

Definition at line 476 of file qlocalserver.cpp.

◆ setListenBacklogSize()

void QLocalServer::setListenBacklogSize ( int size )

Sets the backlog queue size of to be accepted connections to size. The operating system might reduce or ignore this value. By default, the queue size is 50.

Note: This property must be set prior to calling listen().

Since: 6.3

See also: listenBacklogSize()

Definition at line 567 of file qlocalserver.cpp.

◆ setMaxPendingConnections()

void QLocalServer::setMaxPendingConnections ( int numConnections )

Sets the maximum number of pending accepted connections to numConnections. QLocalServer will accept no more than numConnections incoming connections before nextPendingConnection() is called.

Note: Even though QLocalServer will stop accepting new connections after it has reached its maximum number of pending connections, the operating system may still keep them in queue which will result in clients signaling that it is connected.

See also: maxPendingConnections(), hasPendingConnections()

Definition at line 519 of file qlocalserver.cpp.

◆ setSocketOptions()

void QLocalServer::setSocketOptions ( SocketOptions options )

Definition at line 180 of file qlocalserver.cpp.

◆ socketDescriptor()

qintptr QLocalServer::socketDescriptor ( ) const

Since: 5.10 Returns the native socket descriptor the server uses to listen for incoming instructions, or -1 if the server is not listening.

The type of the descriptor depends on the platform: \list

On Windows, the returned value is a \l{Winsock 2 Socket Handle}.

On INTEGRITY, the returned value is the QTcpServer socket descriptor and the type is defined by \l{QTcpServer::socketDescriptor}{socketDescriptor}.

On all other UNIX-like operating systems, the type is a file descriptor representing a listening socket. \endlist

See also: listen()

Definition at line 225 of file qlocalserver.cpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ socketOptions()

QLocalServer::SocketOptions QLocalServer::socketOptions ( ) const

Since: 5.0 Returns the socket options set on the socket.

See also: setSocketOptions()

Definition at line 193 of file qlocalserver.cpp.

◆ waitForNewConnection()

bool QLocalServer::waitForNewConnection	(	int	msec = `0`,
		bool *	timedOut = `nullptr`
	)

Waits for at most msec milliseconds or until an incoming connection is available. Returns true if a connection is available; otherwise returns false. If the operation timed out and timedOut is not \nullptr, *timedOut will be set to true.

This is a blocking function call. Its use is ill-advised in a single-threaded GUI application, since the whole application will stop responding until the function returns. waitForNewConnection() is mostly useful when there is no event loop available.

The non-blocking alternative is to connect to the newConnection() signal.

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

See also: hasPendingConnections(), nextPendingConnection()

Definition at line 542 of file qlocalserver.cpp.

Here is the call graph for this function:

Property Documentation

◆ socketOptions

QLocalServer::socketOptions

readwrite

the socket options that control how the socket operates.

Since: 5.0

For example, the socket may restrict access to what user ids can connect to the socket.

These options must be set before listen() is called.

In some cases, such as with Unix domain sockets on Linux, the access to the socket will be determined by file system permissions, and are created based on the umask. Setting the access flags will override this and will restrict or permit access as specified.

Other Unix-based operating systems, such as \macos, do not honor file permissions for Unix domain sockets and by default have WorldAccess and these permission flags will have no effect.

On Windows, UserAccessOption is sufficient to allow a non elevated process to connect to a local server created by an elevated process run by the same user. GroupAccessOption refers to the primary group of the process (see TokenPrimaryGroup in the Windows documentation). OtherAccessOption refers to the well known "Everyone" group.

On Linux platforms it is possible to create a socket in the abstract namespace, which is independent of the filesystem. Using this kind of socket implies ignoring permission options. On other platforms AbstractNamespaceOption is equivalent to WorldAccessOption.

By default none of the flags are set, access permissions are the platform default.

See also: listen()

Definition at line 115 of file qlocalserver.h.

The documentation for this class was generated from the following files:

src/network/socket/qlocalserver.h
src/network/socket/qlocalserver.cpp

Public Types

Signals

Public Member Functions

Static Public Member Functions

Protected Member Functions

Properties

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

◆ SocketOption

Constructor & Destructor Documentation

◆ QLocalServer()

◆ ~QLocalServer()

Member Function Documentation

◆ bindableSocketOptions()

◆ close()

◆ errorString()

◆ fullServerName()

◆ hasPendingConnections()

◆ incomingConnection()

◆ isListening()

◆ listen() [1/2]

◆ listen() [2/2]

◆ listenBacklogSize()

◆ maxPendingConnections()

◆ newConnection

◆ nextPendingConnection()

◆ removeServer()

◆ serverError()

◆ serverName()

◆ setListenBacklogSize()

◆ setMaxPendingConnections()

◆ setSocketOptions()

◆ socketDescriptor()

◆ socketOptions()

◆ waitForNewConnection()

Property Documentation

◆ socketOptions