1 | // Copyright (C) 2016 The Qt Company Ltd. |
---|---|
2 | // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only |
3 | |
4 | #include "qlocalserver.h" |
5 | #include "qlocalserver_p.h" |
6 | #include "qlocalsocket.h" |
7 | |
8 | #if defined(Q_OS_WIN) && !defined(QT_LOCALSOCKET_TCP) |
9 | #include <QtCore/qt_windows.h> |
10 | #endif |
11 | |
12 | QT_BEGIN_NAMESPACE |
13 | |
14 | using namespace Qt::StringLiterals; |
15 | |
16 | /*! |
17 | \class QLocalServer |
18 | \since 4.4 |
19 | \inmodule QtNetwork |
20 | |
21 | \brief The QLocalServer class provides a local socket based server. |
22 | |
23 | This class makes it possible to accept incoming local socket |
24 | connections. |
25 | |
26 | Call listen() to have the server start listening |
27 | for incoming connections on a specified key. The |
28 | newConnection() signal is then emitted each time a client |
29 | connects to the server. |
30 | |
31 | Call nextPendingConnection() to accept the pending connection |
32 | as a connected QLocalSocket. The function returns a pointer to a |
33 | QLocalSocket that can be used for communicating with the client. |
34 | |
35 | If an error occurs, serverError() returns the type of error, and |
36 | errorString() can be called to get a human readable description |
37 | of what happened. |
38 | |
39 | When listening for connections, the name which the server is |
40 | listening on is available through serverName(). |
41 | |
42 | Calling close() makes QLocalServer stop listening for incoming connections. |
43 | |
44 | Although QLocalServer is designed for use with an event loop, it's possible |
45 | to use it without one. In that case, you must use waitForNewConnection(), |
46 | which blocks until either a connection is available or a timeout expires. |
47 | |
48 | \sa QLocalSocket, QTcpServer |
49 | */ |
50 | |
51 | /*! |
52 | \enum QLocalServer::SocketOption |
53 | \since 5.0 |
54 | |
55 | This enum describes the possible options that can be used to create the |
56 | socket. This changes the access permissions on platforms (Linux, Windows) |
57 | that support access permissions on the socket. Both GroupAccess and OtherAccess |
58 | may vary slightly in meanings depending on the platform. |
59 | On Linux and Android it is possible to use sockets with abstract addresses; |
60 | socket permissions have no meaning for such sockets. |
61 | |
62 | \value NoOptions No access restrictions have been set. |
63 | \value UserAccessOption |
64 | Access is restricted to the same user as the process that created the socket. |
65 | \value GroupAccessOption |
66 | Access is restricted to the same group but not the user that created the socket on Linux. |
67 | Access is restricted to the primary group of the process on Windows |
68 | \value OtherAccessOption |
69 | Access is available to everyone but the user and group that created the socket on Linux. |
70 | Access is available to everyone on Windows. |
71 | \value WorldAccessOption |
72 | No access restrictions. |
73 | \value AbstractNamespaceOption |
74 | The listening socket will be created in the abstract namespace. This flag is specific to Linux. |
75 | In case of other platforms, for the sake of code portability, this flag is equivalent |
76 | to WorldAccessOption. |
77 | |
78 | \sa socketOptions |
79 | */ |
80 | |
81 | |
82 | /*! |
83 | Create a new local socket server with the given \a parent. |
84 | |
85 | \sa listen() |
86 | */ |
87 | QLocalServer::QLocalServer(QObject *parent) |
88 | : QObject(*new QLocalServerPrivate, parent) |
89 | { |
90 | Q_D(QLocalServer); |
91 | d->init(); |
92 | } |
93 | |
94 | /*! |
95 | Destroys the QLocalServer object. If the server is listening for |
96 | connections, it is automatically closed. |
97 | |
98 | Any client QLocalSockets that are still connected must either |
99 | disconnect or be reparented before the server is deleted. |
100 | |
101 | \sa close() |
102 | */ |
103 | QLocalServer::~QLocalServer() |
104 | { |
105 | if (isListening()) |
106 | close(); |
107 | } |
108 | |
109 | /*! |
110 | \property QLocalServer::socketOptions |
111 | \since 5.0 |
112 | |
113 | \brief the socket options that control how the socket operates. |
114 | |
115 | For example, the socket may restrict access to what user ids can |
116 | connect to the socket. |
117 | |
118 | These options must be set before listen() is called. |
119 | |
120 | In some cases, such as with Unix domain sockets on Linux, the |
121 | access to the socket will be determined by file system permissions, |
122 | and are created based on the umask. Setting the access flags will |
123 | override this and will restrict or permit access as specified. |
124 | |
125 | Other Unix-based operating systems, such as \macos, do not |
126 | honor file permissions for Unix domain sockets and by default |
127 | have WorldAccess and these permission flags will have no effect. |
128 | |
129 | On Windows, UserAccessOption is sufficient to allow a non |
130 | elevated process to connect to a local server created by an |
131 | elevated process run by the same user. GroupAccessOption |
132 | refers to the primary group of the process (see TokenPrimaryGroup |
133 | in the Windows documentation). OtherAccessOption refers to |
134 | the well known "Everyone" group. |
135 | |
136 | On Linux platforms it is possible to create a socket in the abstract |
137 | namespace, which is independent of the filesystem. Using this kind |
138 | of socket implies ignoring permission options. On other platforms |
139 | AbstractNamespaceOption is equivalent to WorldAccessOption. |
140 | |
141 | By default none of the flags are set, access permissions |
142 | are the platform default. |
143 | |
144 | \sa listen() |
145 | */ |
146 | void QLocalServer::setSocketOptions(SocketOptions options) |
147 | { |
148 | Q_D(QLocalServer); |
149 | |
150 | d->socketOptions = options; |
151 | } |
152 | |
153 | /*! |
154 | \since 5.0 |
155 | Returns the socket options set on the socket. |
156 | |
157 | \sa setSocketOptions() |
158 | */ |
159 | QLocalServer::SocketOptions QLocalServer::socketOptions() const |
160 | { |
161 | Q_D(const QLocalServer); |
162 | return d->socketOptions; |
163 | } |
164 | |
165 | QBindable<QLocalServer::SocketOptions> QLocalServer::bindableSocketOptions() |
166 | { |
167 | Q_D(QLocalServer); |
168 | return &d->socketOptions; |
169 | } |
170 | |
171 | /*! |
172 | \since 5.10 |
173 | Returns the native socket descriptor the server uses to listen |
174 | for incoming instructions, or -1 if the server is not listening. |
175 | |
176 | The type of the descriptor depends on the platform: |
177 | \list |
178 | \li On Windows, the returned value is a |
179 | \l{Winsock 2 Socket Handle}. |
180 | |
181 | \li On INTEGRITY, the returned value is the |
182 | QTcpServer socket descriptor and the type is defined by |
183 | \l{QTcpServer::socketDescriptor}{socketDescriptor}. |
184 | |
185 | \li On all other UNIX-like operating systems, the type is |
186 | a file descriptor representing a listening socket. |
187 | \endlist |
188 | |
189 | \sa listen() |
190 | */ |
191 | qintptr QLocalServer::socketDescriptor() const |
192 | { |
193 | Q_D(const QLocalServer); |
194 | if (!isListening()) |
195 | return -1; |
196 | #if defined(QT_LOCALSOCKET_TCP) |
197 | return d->tcpServer.socketDescriptor(); |
198 | #elif defined(Q_OS_WIN) |
199 | const auto handle = d->connectionEventNotifier->handle(); |
200 | return handle != INVALID_HANDLE_VALUE ? qintptr(handle) : -1; |
201 | #else |
202 | return d->socketNotifier->socket(); |
203 | #endif |
204 | } |
205 | |
206 | /*! |
207 | Stop listening for incoming connections. Existing connections are not |
208 | affected, but any new connections will be refused. |
209 | |
210 | \sa isListening(), listen() |
211 | */ |
212 | void QLocalServer::close() |
213 | { |
214 | Q_D(QLocalServer); |
215 | if (!isListening()) |
216 | return; |
217 | qDeleteAll(c: d->pendingConnections); |
218 | d->pendingConnections.clear(); |
219 | d->closeServer(); |
220 | d->serverName.clear(); |
221 | d->fullServerName.clear(); |
222 | d->errorString.clear(); |
223 | d->error = QAbstractSocket::UnknownSocketError; |
224 | } |
225 | |
226 | /*! |
227 | Returns the human-readable message appropriate to the current error |
228 | reported by serverError(). If no suitable string is available, an empty |
229 | string is returned. |
230 | |
231 | \sa serverError() |
232 | */ |
233 | QString QLocalServer::errorString() const |
234 | { |
235 | Q_D(const QLocalServer); |
236 | return d->errorString; |
237 | } |
238 | |
239 | /*! |
240 | Returns \c true if the server has a pending connection; otherwise |
241 | returns \c false. |
242 | |
243 | \sa nextPendingConnection(), setMaxPendingConnections() |
244 | */ |
245 | bool QLocalServer::hasPendingConnections() const |
246 | { |
247 | Q_D(const QLocalServer); |
248 | return !(d->pendingConnections.isEmpty()); |
249 | } |
250 | |
251 | /*! |
252 | This virtual function is called by QLocalServer when a new connection |
253 | is available. \a socketDescriptor is the native socket descriptor for |
254 | the accepted connection. |
255 | |
256 | The base implementation creates a QLocalSocket, sets the socket descriptor |
257 | and then stores the QLocalSocket in an internal list of pending |
258 | connections. Finally newConnection() is emitted. |
259 | |
260 | Reimplement this function to alter the server's behavior |
261 | when a connection is available. |
262 | |
263 | \sa newConnection(), nextPendingConnection(), |
264 | QLocalSocket::setSocketDescriptor() |
265 | */ |
266 | void QLocalServer::incomingConnection(quintptr socketDescriptor) |
267 | { |
268 | QLocalSocket *socket = new QLocalSocket(this); |
269 | socket->setSocketDescriptor(socketDescriptor); |
270 | addPendingConnection(socket); |
271 | } |
272 | |
273 | /*! |
274 | This function is called by QLocalServer::incomingConnection() |
275 | to add the \a socket to the list of pending incoming connections. |
276 | |
277 | \note Don't forget to call this member from reimplemented |
278 | incomingConnection() if you do not want to break the |
279 | Pending Connections mechanism. This function emits the |
280 | newConnection() signal after the socket has been |
281 | added. |
282 | |
283 | \sa incomingConnection(), newConnection() |
284 | \since 6.8 |
285 | */ |
286 | void QLocalServer::addPendingConnection(QLocalSocket *socket) |
287 | { |
288 | Q_D(QLocalServer); |
289 | d->pendingConnections.enqueue(t: socket); |
290 | emit newConnection(); |
291 | } |
292 | |
293 | /*! |
294 | Returns \c true if the server is listening for incoming connections |
295 | otherwise false. |
296 | |
297 | \sa listen(), close() |
298 | */ |
299 | bool QLocalServer::isListening() const |
300 | { |
301 | Q_D(const QLocalServer); |
302 | return !(d->serverName.isEmpty()); |
303 | } |
304 | |
305 | /*! |
306 | Tells the server to listen for incoming connections on \a name. |
307 | If the server is currently listening then it will return false. |
308 | Return true on success otherwise false. |
309 | |
310 | \a name can be a single name and QLocalServer will determine |
311 | the correct platform specific path. serverName() will return |
312 | the name that is passed into listen. |
313 | |
314 | Usually you would just pass in a name like "foo", but on Unix this |
315 | could also be a path such as "/tmp/foo" and on Windows this could |
316 | be a pipe path such as "\\\\.\\pipe\\foo" |
317 | |
318 | \note On Unix if the server crashes without closing listen will fail |
319 | with AddressInUseError. To create a new server the file should be removed. |
320 | On Windows two local servers can listen to the same pipe at the same |
321 | time, but any connections will go to one of the server. |
322 | |
323 | \sa serverName(), isListening(), close() |
324 | */ |
325 | bool QLocalServer::listen(const QString &name) |
326 | { |
327 | Q_D(QLocalServer); |
328 | if (isListening()) { |
329 | qWarning(msg: "QLocalServer::listen() called when already listening"); |
330 | return false; |
331 | } |
332 | |
333 | if (name.isEmpty()) { |
334 | d->error = QAbstractSocket::HostNotFoundError; |
335 | QString function = "QLocalServer::listen"_L1; |
336 | d->errorString = tr(s: "%1: Name error").arg(a: function); |
337 | return false; |
338 | } |
339 | |
340 | if (!d->listen(name)) { |
341 | d->serverName.clear(); |
342 | d->fullServerName.clear(); |
343 | return false; |
344 | } |
345 | |
346 | d->serverName = name; |
347 | return true; |
348 | } |
349 | |
350 | /*! |
351 | \since 5.0 |
352 | |
353 | Instructs the server to listen for incoming connections on |
354 | \a socketDescriptor. The property returns \c false if the server is |
355 | currently listening. It returns \c true on success; otherwise, |
356 | it returns \c false. The socket must be ready to accept |
357 | new connections with no extra platform-specific functions |
358 | called. The socket is set into non-blocking mode. |
359 | |
360 | serverName(), fullServerName() may return a string with |
361 | a name if this option is supported by the platform; |
362 | otherwise, they return an empty QString. In particular, the addresses |
363 | of sockets in the abstract namespace supported by Linux will |
364 | not yield useful names if they contain unprintable characters. |
365 | |
366 | \sa isListening(), close() |
367 | */ |
368 | bool QLocalServer::listen(qintptr socketDescriptor) |
369 | { |
370 | Q_D(QLocalServer); |
371 | if (isListening()) { |
372 | qWarning(msg: "QLocalServer::listen() called when already listening"); |
373 | return false; |
374 | } |
375 | |
376 | d->serverName.clear(); |
377 | d->fullServerName.clear(); |
378 | |
379 | if (!d->listen(socketDescriptor)) { |
380 | return false; |
381 | } |
382 | |
383 | return true; |
384 | } |
385 | |
386 | /*! |
387 | Returns the maximum number of pending accepted connections. |
388 | The default is 30. |
389 | |
390 | \sa setMaxPendingConnections(), hasPendingConnections() |
391 | */ |
392 | int QLocalServer::maxPendingConnections() const |
393 | { |
394 | Q_D(const QLocalServer); |
395 | return d->maxPendingConnections; |
396 | } |
397 | |
398 | /*! |
399 | \fn void QLocalServer::newConnection() |
400 | |
401 | This signal is emitted every time a new connection is available. |
402 | |
403 | \sa hasPendingConnections(), nextPendingConnection() |
404 | */ |
405 | |
406 | /*! |
407 | Returns the next pending connection as a connected QLocalSocket object. |
408 | |
409 | The socket is created as a child of the server, which means that it is |
410 | automatically deleted when the QLocalServer object is destroyed. It is |
411 | still a good idea to delete the object explicitly when you are done with |
412 | it, to avoid wasting memory. |
413 | |
414 | \nullptr is returned if this function is called when there are no pending |
415 | connections. |
416 | |
417 | \sa hasPendingConnections(), newConnection(), incomingConnection() |
418 | */ |
419 | QLocalSocket *QLocalServer::nextPendingConnection() |
420 | { |
421 | Q_D(QLocalServer); |
422 | if (d->pendingConnections.isEmpty()) |
423 | return nullptr; |
424 | QLocalSocket *nextSocket = d->pendingConnections.dequeue(); |
425 | #ifndef QT_LOCALSOCKET_TCP |
426 | if (d->pendingConnections.size() <= d->maxPendingConnections) |
427 | #ifndef Q_OS_WIN |
428 | d->socketNotifier->setEnabled(true); |
429 | #else |
430 | d->connectionEventNotifier->setEnabled(true); |
431 | #endif |
432 | #endif |
433 | return nextSocket; |
434 | } |
435 | |
436 | /*! |
437 | \since 4.5 |
438 | |
439 | Removes any server instance that might cause a call to listen() to fail |
440 | and returns \c true if successful; otherwise returns \c false. |
441 | This function is meant to recover from a crash, when the previous server |
442 | instance has not been cleaned up. |
443 | |
444 | On Windows, this function does nothing; on Unix, it removes the socket file |
445 | given by \a name. |
446 | |
447 | \warning Be careful to avoid removing sockets of running instances. |
448 | */ |
449 | bool QLocalServer::removeServer(const QString &name) |
450 | { |
451 | return QLocalServerPrivate::removeServer(name); |
452 | } |
453 | |
454 | /*! |
455 | Returns the server name if the server is listening for connections; |
456 | otherwise returns QString() |
457 | |
458 | \sa listen(), fullServerName() |
459 | */ |
460 | QString QLocalServer::serverName() const |
461 | { |
462 | Q_D(const QLocalServer); |
463 | return d->serverName; |
464 | } |
465 | |
466 | /*! |
467 | Returns the full path that the server is listening on. |
468 | |
469 | Note: This is platform specific |
470 | |
471 | \sa listen(), serverName() |
472 | */ |
473 | QString QLocalServer::fullServerName() const |
474 | { |
475 | Q_D(const QLocalServer); |
476 | return d->fullServerName; |
477 | } |
478 | |
479 | /*! |
480 | Returns the type of error that occurred last or NoError. |
481 | |
482 | \sa errorString() |
483 | */ |
484 | QAbstractSocket::SocketError QLocalServer::serverError() const |
485 | { |
486 | Q_D(const QLocalServer); |
487 | return d->error; |
488 | } |
489 | |
490 | /*! |
491 | Sets the maximum number of pending accepted connections to |
492 | \a numConnections. QLocalServer will accept no more than |
493 | \a numConnections incoming connections before nextPendingConnection() |
494 | is called. |
495 | |
496 | Note: Even though QLocalServer will stop accepting new connections |
497 | after it has reached its maximum number of pending connections, |
498 | the operating system may still keep them in queue which will result |
499 | in clients signaling that it is connected. |
500 | |
501 | \sa maxPendingConnections(), hasPendingConnections() |
502 | */ |
503 | void QLocalServer::setMaxPendingConnections(int numConnections) |
504 | { |
505 | Q_D(QLocalServer); |
506 | d->maxPendingConnections = numConnections; |
507 | } |
508 | |
509 | /*! |
510 | Waits for at most \a msec milliseconds or until an incoming connection |
511 | is available. Returns \c true if a connection is available; otherwise |
512 | returns \c false. If the operation timed out and \a timedOut is not |
513 | \nullptr, *timedOut will be set to true. |
514 | |
515 | This is a blocking function call. Its use is ill-advised in a |
516 | single-threaded GUI application, since the whole application will stop |
517 | responding until the function returns. waitForNewConnection() is mostly |
518 | useful when there is no event loop available. |
519 | |
520 | The non-blocking alternative is to connect to the newConnection() signal. |
521 | |
522 | If msec is -1, this function will not time out. |
523 | |
524 | \sa hasPendingConnections(), nextPendingConnection() |
525 | */ |
526 | bool QLocalServer::waitForNewConnection(int msec, bool *timedOut) |
527 | { |
528 | Q_D(QLocalServer); |
529 | if (timedOut) |
530 | *timedOut = false; |
531 | |
532 | if (!isListening()) |
533 | return false; |
534 | |
535 | d->waitForNewConnection(msec, timedOut); |
536 | |
537 | return !d->pendingConnections.isEmpty(); |
538 | } |
539 | |
540 | /*! |
541 | Sets the backlog queue size of to be accepted connections to \a |
542 | size. The operating system might reduce or ignore this value. |
543 | By default, the queue size is 50. |
544 | |
545 | \note This property must be set prior to calling listen(). |
546 | |
547 | \since 6.3 |
548 | |
549 | \sa listenBacklogSize() |
550 | */ |
551 | void QLocalServer::setListenBacklogSize(int size) |
552 | { |
553 | Q_D(QLocalServer); |
554 | d->listenBacklog = size; |
555 | } |
556 | |
557 | /*! |
558 | Returns the backlog queue size of to be accepted connections. |
559 | |
560 | \since 6.3 |
561 | |
562 | \sa setListenBacklogSize() |
563 | */ |
564 | int QLocalServer::listenBacklogSize() const |
565 | { |
566 | Q_D(const QLocalServer); |
567 | return d->listenBacklog; |
568 | } |
569 | |
570 | QT_END_NAMESPACE |
571 | |
572 | #include "moc_qlocalserver.cpp" |
573 | |
574 |
Definitions
- QLocalServer
- ~QLocalServer
- setSocketOptions
- socketOptions
- bindableSocketOptions
- socketDescriptor
- close
- errorString
- hasPendingConnections
- incomingConnection
- addPendingConnection
- isListening
- listen
- listen
- maxPendingConnections
- nextPendingConnection
- removeServer
- serverName
- fullServerName
- serverError
- setMaxPendingConnections
- waitForNewConnection
- setListenBacklogSize
Learn Advanced QML with KDAB
Find out more