QWebSocketServer#
Implements a WebSocket-based server. More…
Synopsis#
Functions#
def
close
()def
error
()def
errorString
()def
handleConnection
(socket)def
handshakeTimeoutMS
()def
hasPendingConnections
()def
isListening
()def
listen
([address=QHostAddress.Any[, port=0]])def
maxPendingConnections
()def
nativeDescriptor
()def
pauseAccepting
()def
proxy
()def
resumeAccepting
()def
secureMode
()def
serverAddress
()def
serverName
()def
serverPort
()def
serverUrl
()def
setHandshakeTimeout
(msec)def
setMaxPendingConnections
(numConnections)def
setNativeDescriptor
(descriptor)def
setProxy
(networkProxy)def
setServerName
(serverName)def
setSocketDescriptor
(socketDescriptor)def
setSslConfiguration
(sslConfiguration)def
setSupportedSubprotocols
(protocols)def
socketDescriptor
()def
sslConfiguration
()def
supportedSubprotocols
()def
supportedVersions
()
Virtual functions#
def
nextPendingConnection
()
Signals#
def
acceptError
(socketError)def
alertReceived
(level, type, description)def
alertSent
(level, type, description)def
closed
()def
handshakeInterruptedOnError
(error)def
newConnection
()def
originAuthenticationRequired
(pAuthenticator)def
peerVerifyError
(error)def
preSharedKeyAuthenticationRequired
(authenticator)def
serverError
(closeCode)def
sslErrors
(errors)
Note
This documentation may contain snippets that were automatically translated from C++ to Python. We always welcome contributions to the snippet translation. If you see an issue with the translation, you can also let us know by creating a ticket on https:/bugreports.qt.io/projects/PYSIDE
Detailed Description#
It is modeled after QTcpServer, and behaves the same. So, if you know how to use QTcpServer, you know how to use QWebSocketServer
. This class makes it possible to accept incoming WebSocket connections. You can specify the port or have QWebSocketServer
pick one automatically. You can listen on a specific address or on all the machine’s addresses. Call listen()
to have the server listen for incoming connections.
The newConnection()
signal is then emitted each time a client connects to the server. Call nextPendingConnection()
to accept the pending connection as a connected QWebSocket
. The function returns a pointer to a QWebSocket
in QAbstractSocket::ConnectedState that you can use 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 address and port on which the server is listening are available as serverAddress()
and serverPort()
.
Calling close()
makes QWebSocketServer
stop listening for incoming connections.
QWebSocketServer
currently does not support WebSocket Extensions .
Note
When working with self-signed certificates, Firefox bug 594502 prevents Firefox to connect to a secure WebSocket server. To work around this problem, first browse to the secure WebSocket server using HTTPS. FireFox will indicate that the certificate is invalid. From here on, the certificate can be added to the exceptions. After this, the secure WebSockets connection should work.
QWebSocketServer
only supports version 13 of the WebSocket protocol, as outlined in RFC 6455 .
There is a default connection handshake timeout of 10 seconds to avoid denial of service, which can be customized using setHandshakeTimeout()
.
See also
- class PySide6.QtWebSockets.QWebSocketServer(serverName, secureMode[, parent=None])#
- Parameters:
secureMode –
SslMode
serverName – str
parent –
PySide6.QtCore.QObject
Constructs a new QWebSocketServer
with the given serverName
. The serverName
will be used in the HTTP handshake phase to identify the server. It can be empty, in which case no server name will be sent to the client. The secureMode
parameter indicates whether the server operates over wss ( SecureMode
) or over ws ( NonSecureMode
).
parent
is passed to the QObject constructor.
- PySide6.QtWebSockets.QWebSocketServer.SslMode#
Indicates whether the server operates over wss (SecureMode) or ws (NonSecureMode)
Constant
Description
QWebSocketServer.SecureMode
The server operates in secure mode (over wss)
QWebSocketServer.NonSecureMode
The server operates in non-secure mode (over ws)
- PySide6.QtWebSockets.QWebSocketServer.acceptError(socketError)#
- Parameters:
socketError –
SocketError
This signal is emitted when the acceptance of a new connection results in an error. The socketError
parameter describes the type of error that occurred.
See also
- PySide6.QtWebSockets.QWebSocketServer.alertReceived(level, type, description)#
- Parameters:
level –
AlertLevel
type –
AlertType
description – str
QWebSocketServer
emits this signal if an alert message was received from a peer. level
tells if the alert was fatal or it was a warning. type
is the code explaining why the alert was sent. When a textual description of the alert message is available, it is supplied in description
.
Note
The signal is mostly for informational and debugging purposes and does not require any handling in the application. If the alert was fatal, underlying backend will handle it and close the connection.
- PySide6.QtWebSockets.QWebSocketServer.alertSent(level, type, description)#
- Parameters:
level –
AlertLevel
type –
AlertType
description – str
QWebSocketServer
emits this signal if an alert message was sent to a peer. level
describes if it was a warning or a fatal error. type
gives the code of the alert message. When a textual description of the alert message is available, it is supplied in description
.
Note
This signal is mostly informational and can be used for debugging purposes, normally it does not require any actions from the application.
- PySide6.QtWebSockets.QWebSocketServer.close()#
Closes the server. The server will no longer listen for incoming connections.
- PySide6.QtWebSockets.QWebSocketServer.closed()#
This signal is emitted when the server closed its connection.
See also
Returns an error code for the last error that occurred. If no error occurred, CloseCodeNormal
is returned.
See also
- PySide6.QtWebSockets.QWebSocketServer.errorString()#
- Return type:
str
Returns a human readable description of the last error that occurred. If no error occurred, an empty string is returned.
See also
- PySide6.QtWebSockets.QWebSocketServer.handleConnection(socket)#
- Parameters:
socket –
PySide6.QtNetwork.QTcpSocket
Upgrades a tcp socket
to websocket.
The QWebSocketServer
object will take ownership of the socket object and delete it when appropriate.
- PySide6.QtWebSockets.QWebSocketServer.handshakeInterruptedOnError(error)#
- Parameters:
error –
PySide6.QtNetwork.QSslError
QWebSocketServer
emits this signal if a certificate verification error
was found and if early error reporting was enabled in QSslConfiguration.
See also
sslErrors()
setHandshakeMustInterruptOnError()
- PySide6.QtWebSockets.QWebSocketServer.handshakeTimeoutMS()#
- Return type:
int
Returns the handshake timeout for new connections in milliseconds.
The default is 10 seconds. If a peer uses more time to complete the handshake their connection is closed.
See also
setHandshakeTimeout()
handshakeTimeout()
- PySide6.QtWebSockets.QWebSocketServer.hasPendingConnections()#
- Return type:
bool
Returns true if the server has pending connections; otherwise returns false.
- PySide6.QtWebSockets.QWebSocketServer.isListening()#
- Return type:
bool
Returns true if the server is currently listening for incoming connections; otherwise returns false. If listening fails, error()
will return the reason.
- PySide6.QtWebSockets.QWebSocketServer.listen([address=QHostAddress.Any[, port=0]])#
- Parameters:
address –
PySide6.QtNetwork.QHostAddress
port – int
- Return type:
bool
Tells the server to listen for incoming connections on address address
and port port
. If port
is 0, a port is chosen automatically. If address
is QHostAddress::Any, the server will listen on all network interfaces.
Returns true on success; otherwise returns false.
See also
- PySide6.QtWebSockets.QWebSocketServer.maxPendingConnections()#
- Return type:
int
Returns the maximum number of pending accepted connections. The default is 30.
- PySide6.QtWebSockets.QWebSocketServer.nativeDescriptor()#
- Return type:
qintptr
Note
This function is deprecated.
Returns the native socket descriptor the server uses to listen for incoming instructions, or -1 if the server is not listening. If the server is using QNetworkProxy, the returned descriptor may not be usable with native socket functions.
- PySide6.QtWebSockets.QWebSocketServer.newConnection()#
This signal is emitted every time a new connection is available.
- PySide6.QtWebSockets.QWebSocketServer.nextPendingConnection()#
- Return type:
Returns the next pending connection as a connected QWebSocket
object. QWebSocketServer
does not take ownership of the returned QWebSocket
object. It is up to the caller to delete the object explicitly when it will no longer be used, otherwise a memory leak will occur. nullptr is returned if this function is called when there are no pending connections.
Note: The returned QWebSocket
object cannot be used from another thread.
See also
- PySide6.QtWebSockets.QWebSocketServer.originAuthenticationRequired(pAuthenticator)#
- Parameters:
pAuthenticator –
PySide6.QtWebSockets.QWebSocketCorsAuthenticator
This signal is emitted when a new connection is requested. The slot connected to this signal should indicate whether the origin (which can be determined by the origin() call) is allowed in the authenticator
object (by issuing setAllowed()
).
If no slot is connected to this signal, all origins will be accepted by default.
Note
It is not possible to use a QueuedConnection to connect to this signal, as the connection will always succeed.
- PySide6.QtWebSockets.QWebSocketServer.pauseAccepting()#
Pauses incoming new connections. Queued connections will remain in queue.
See also
- PySide6.QtWebSockets.QWebSocketServer.peerVerifyError(error)#
- Parameters:
error –
PySide6.QtNetwork.QSslError
QWebSocketServer
can emit this signal several times during the SSL handshake, before encryption has been established, to indicate that an error has occurred while establishing the identity of the peer. The error
is usually an indication that QWebSocketServer
is unable to securely identify the peer.
This signal provides you with an early indication when something is wrong. By connecting to this signal, you can manually choose to tear down the connection from inside the connected slot before the handshake has completed. If no action is taken, QWebSocketServer
will proceed to emitting sslErrors()
.
See also
- Parameters:
authenticator –
PySide6.QtNetwork.QSslPreSharedKeyAuthenticator
QWebSocketServer
emits this signal when it negotiates a PSK ciphersuite, and therefore a PSK authentication is then required.
When using PSK, the client must send to the server a valid identity and a valid pre shared key, in order for the SSL handshake to continue. Applications can provide this information in a slot connected to this signal, by filling in the passed authenticator
object according to their needs.
Note
Ignoring this signal, or failing to provide the required credentials, will cause the handshake to fail, and therefore the connection to be aborted.
Note
The authenticator
object is owned by the socket and must not be deleted by the application.
See also
preSharedKeyAuthenticationRequired()
- PySide6.QtWebSockets.QWebSocketServer.proxy()#
- Return type:
Returns the network proxy for this server. By default QNetworkProxy::DefaultProxy is used.
See also
- PySide6.QtWebSockets.QWebSocketServer.resumeAccepting()#
Resumes accepting new connections.
See also
Returns the secure mode the server is running in.
See also
QWebSocketServer()
SslMode
- PySide6.QtWebSockets.QWebSocketServer.serverAddress()#
- Return type:
Returns the server’s address if the server is listening for connections; otherwise returns QHostAddress::Null.
See also
This signal is emitted when an error occurs during the setup of a WebSocket connection. The closeCode
parameter describes the type of error that occurred
See also
- PySide6.QtWebSockets.QWebSocketServer.serverName()#
- Return type:
str
Returns the server name that is used during the http handshake phase.
See also
- PySide6.QtWebSockets.QWebSocketServer.serverPort()#
- Return type:
int
Returns the server’s port if the server is listening for connections; otherwise returns 0.
See also
- PySide6.QtWebSockets.QWebSocketServer.serverUrl()#
- Return type:
Returns a URL clients can use to connect to this server if the server is listening for connections. Otherwise an invalid URL is returned.
See also
- PySide6.QtWebSockets.QWebSocketServer.setHandshakeTimeout(msec)#
- Parameters:
msec – int
This is an overloaded function.
- PySide6.QtWebSockets.QWebSocketServer.setMaxPendingConnections(numConnections)#
- Parameters:
numConnections – int
Sets the maximum number of pending accepted connections to numConnections
. WebSocketServer will accept no more than numConnections
incoming connections before nextPendingConnection()
is called. By default, the limit is 30 pending connections.
QWebSocketServer
will emit the error()
signal with the CloseCodeAbnormalDisconnection
close code when the maximum of connections has been reached. The WebSocket handshake will fail and the socket will be closed.
- PySide6.QtWebSockets.QWebSocketServer.setNativeDescriptor(descriptor)#
- Parameters:
descriptor –
qintptr
- Return type:
bool
Note
This function is deprecated.
Sets the socket descriptor this server should use when listening for incoming connections to socketDescriptor
.
Returns true if the socket is set successfully; otherwise returns false. The socket is assumed to be in listening state.
- PySide6.QtWebSockets.QWebSocketServer.setProxy(networkProxy)#
- Parameters:
networkProxy –
PySide6.QtNetwork.QNetworkProxy
Sets the explicit network proxy for this server to networkProxy
.
To disable the use of a proxy, use the QNetworkProxy::NoProxy proxy type:
server->setProxy(QNetworkProxy::NoProxy);See also
- PySide6.QtWebSockets.QWebSocketServer.setServerName(serverName)#
- Parameters:
serverName – str
Sets the server name that will be used during the HTTP handshake phase to the given serverName
. The serverName
can be empty, in which case an empty server name will be sent to the client. Existing connected clients will not be notified of this change, only newly connecting clients will see this new name.
See also
- PySide6.QtWebSockets.QWebSocketServer.setSocketDescriptor(socketDescriptor)#
- Parameters:
socketDescriptor –
qintptr
- Return type:
bool
Sets the socket descriptor this server should use when listening for incoming connections to socketDescriptor
.
Returns true if the socket is set successfully; otherwise returns false. The socket is assumed to be in listening state.
See also
- PySide6.QtWebSockets.QWebSocketServer.setSslConfiguration(sslConfiguration)#
- Parameters:
sslConfiguration –
PySide6.QtNetwork.QSslConfiguration
Sets the SSL configuration for the QWebSocketServer
to sslConfiguration
. This method has no effect if QWebSocketServer
runs in non-secure mode ( NonSecureMode
).
See also
sslConfiguration()
SslMode
- PySide6.QtWebSockets.QWebSocketServer.setSupportedSubprotocols(protocols)#
- Parameters:
protocols – list of strings
Sets the list of protocols supported by the server to protocols
.
See also
- PySide6.QtWebSockets.QWebSocketServer.socketDescriptor()#
- Return type:
qintptr
Returns the native socket descriptor the server uses to listen for incoming instructions, or -1 if the server is not listening. If the server is using QNetworkProxy, the returned descriptor may not be usable with native socket functions.
See also
- PySide6.QtWebSockets.QWebSocketServer.sslConfiguration()#
- Return type:
Returns the SSL configuration used by the QWebSocketServer
. If the server is not running in secure mode ( SecureMode
), this method returns QSslConfiguration::defaultConfiguration().
See also
setSslConfiguration()
SslMode
defaultConfiguration()
- PySide6.QtWebSockets.QWebSocketServer.sslErrors(errors)#
- Parameters:
errors – .list of QSslError
QWebSocketServer
emits this signal after the SSL handshake to indicate that one or more errors have occurred while establishing the identity of the peer. The errors are usually an indication that QWebSocketServer
is unable to securely identify the peer. Unless any action is taken, the connection will be dropped after this signal has been emitted.
errors
contains one or more errors that prevent QSslSocket from verifying the identity of the peer.
See also
- PySide6.QtWebSockets.QWebSocketServer.supportedSubprotocols()#
- Return type:
list of strings
Returns the list of protocols supported by the server.
See also
- PySide6.QtWebSockets.QWebSocketServer.supportedVersions()#
- Return type:
.list of QWebSocketProtocol.Version
Returns a list of WebSocket versions that this server is supporting.