QAbstractSocket

PyQt5.QtNetwork.QAbstractSocket

Inherits from QIODevice.

Inherited by QTcpSocket, QUdpSocket.

Description

The QAbstractSocket class provides the base functionality common to all socket types.

QAbstractSocket is the base class for QTcpSocket and QUdpSocket and contains all common functionality of these two classes. If you need a socket, you have two options:

• Instantiate QTcpSocket or QUdpSocket.

• Create a native socket descriptor, instantiate QAbstractSocket, and call setSocketDescriptor() to wrap the native socket.

TCP (Transmission Control Protocol) is a reliable, stream-oriented, connection-oriented transport protocol. UDP (User Datagram Protocol) is an unreliable, datagram-oriented, connectionless protocol. In practice, this means that TCP is better suited for continuous transmission of data, whereas the more lightweight UDP can be used when reliability isn’t important.

QAbstractSocket’s API unifies most of the differences between the two protocols. For example, although UDP is connectionless, connectToHost() establishes a virtual connection for UDP sockets, enabling you to use QAbstractSocket in more or less the same way regardless of the underlying protocol. Internally, QAbstractSocket remembers the address and port passed to connectToHost(), and functions like read() and write() use these values.

At any time, QAbstractSocket has a state (returned by state()). The initial state is UnconnectedState. After calling connectToHost(), the socket first enters HostLookupState. If the host is found, QAbstractSocket enters ConnectingState and emits the hostFound signal. When the connection has been established, it enters ConnectedState and emits connected. If an error occurs at any stage, error is emitted. Whenever the state changes, stateChanged is emitted. For convenience, isValid() returns true if the socket is ready for reading and writing, but note that the socket’s state must be ConnectedState before reading and writing can occur.

Read or write data by calling read() or write(), or use the convenience functions readLine() and readAll(). QAbstractSocket also inherits getChar(), putChar(), and ungetChar() from QIODevice, which work on single bytes. The bytesWritten() signal is emitted when data has been written to the socket. Note that Qt does not limit the write buffer size. You can monitor its size by listening to this signal.

The readyRead() signal is emitted every time a new chunk of data has arrived. bytesAvailable() then returns the number of bytes that are available for reading. Typically, you would connect the readyRead() signal to a slot and read all available data there. If you don’t read all the data at once, the remaining data will still be available later, and any new incoming data will be appended to QAbstractSocket’s internal read buffer. To limit the size of the read buffer, call setReadBufferSize().

To close the socket, call disconnectFromHost(). QAbstractSocket enters ClosingState. After all pending data has been written to the socket, QAbstractSocket actually closes the socket, enters UnconnectedState, and emits disconnected. If you want to abort a connection immediately, discarding all pending data, call abort() instead. If the remote host closes the connection, QAbstractSocket will emit error(RemoteHostClosedError), during which the socket state will still be ConnectedState, and then the disconnected signal will be emitted.

The port and address of the connected peer is fetched by calling peerPort() and peerAddress(). peerName() returns the host name of the peer, as passed to connectToHost(). localPort() and localAddress() return the port and address of the local socket.

QAbstractSocket provides a set of functions that suspend the calling thread until certain signals are emitted. These functions can be used to implement blocking sockets:

• waitForConnected() blocks until a connection has been established.

• waitForReadyRead() blocks until new data is available for reading.

• waitForBytesWritten() blocks until one payload of data has been written to the socket.

• waitForDisconnected() blocks until the connection has closed.

We show an example:

#     int numRead = 0, numReadTotal = 0;
#     char buffer[50];

#     forever {
#         numRead  = socket.read(buffer, 50);

#         // do whatever with array

#         numReadTotal += numRead;
#         if (numRead == 0 && !socket.waitForReadyRead())
#             break;
#     }

If waitForReadyRead() returns false, the connection has been closed or an error has occurred.

Programming with a blocking socket is radically different from programming with a non-blocking socket. A blocking socket doesn’t require an event loop and typically leads to simpler code. However, in a GUI application, blocking sockets should only be used in non-GUI threads, to avoid freezing the user interface. See the fortuneclient and blockingfortuneclient examples for an overview of both approaches.

Note: We discourage the use of the blocking functions together with signals. One of the two possibilities should be used.

QAbstractSocket can be used with QTextStream and QDataStream’s stream operators (operator<<() and operator>>()). There is one issue to be aware of, though: You must make sure that enough data is available before attempting to read it using operator>>().

See also

QNetworkAccessManager, QTcpServer.

Classes

BindMode

PauseModes

Enums

BindFlag

TODO

Member	Value	Description
DefaultForPlatform	TODO	TODO
DontShareAddress	TODO	TODO
ReuseAddressHint	TODO	TODO
ShareAddress	TODO	TODO

---

NetworkLayerProtocol

This enum describes the network layer protocol values used in Qt.

See also

protocol().

Member	Value	Description
AnyIPProtocol	TODO	Either IPv4 or IPv6
IPv4Protocol	0	IPv4
IPv6Protocol	1	IPv6
UnknownNetworkLayerProtocol	-1	Other than IPv4 and IPv6

---

PauseMode

TODO

Member	Value	Description
PauseNever	TODO	TODO
PauseOnSslErrors	TODO	TODO

---

SocketError

This enum describes the socket errors that can occur.

See also

error.

Member	Value	Description
AddressInUseError	8	The address specified to QAbstractSocket::bind() is already in use and was set to be exclusive.
ConnectionRefusedError	0	The connection was refused by the peer (or timed out).
DatagramTooLargeError	6	The datagram was larger than the operating system’s limit (which can be as low as 8192 bytes).
HostNotFoundError	2	The host address was not found.
NetworkError	7	An error occurred with the network (e.g., the network cable was accidentally plugged out).
OperationError	TODO	An operation was attempted while the socket was in a state that did not permit it.
ProxyAuthenticationRequiredError	12	The socket is using a proxy, and the proxy requires authentication.
ProxyConnectionClosedError	15	The connection to the proxy server was closed unexpectedly (before the connection to the final peer was established)
ProxyConnectionRefusedError	14	Could not contact the proxy server because the connection to that server was denied
ProxyConnectionTimeoutError	16	The connection to the proxy server timed out or the proxy server stopped responding in the authentication phase.
ProxyNotFoundError	17	The proxy address set with setProxy() (or the application proxy) was not found.
ProxyProtocolError	18	The connection negotiation with the proxy server failed, because the response from the proxy server could not be understood.
RemoteHostClosedError	1	The remote host closed the connection. Note that the client socket (i.e., this socket) will be closed after the remote close notification has been sent.
SocketAccessError	3	The socket operation failed because the application lacked the required privileges.
SocketAddressNotAvailableError	9	The address specified to QAbstractSocket::bind() does not belong to the host.
SocketResourceError	4	The local system ran out of resources (e.g., too many sockets).
SocketTimeoutError	5	The socket operation timed out.
SslHandshakeFailedError	13	The SSL/TLS handshake failed, so the connection was closed (only used in QSslSocket)
SslInternalError	TODO	The SSL library being used reported an internal error. This is probably the result of a bad installation or misconfiguration of the library.
SslInvalidUserDataError	TODO	Invalid data (certificate, key, cypher, etc.) was provided and its use resulted in an error in the SSL library.
TemporaryError	TODO	A temporary error occurred (e.g., operation would block and socket is non-blocking).
UnfinishedSocketOperationError	11	Used by QAbstractSocketEngine only, The last operation attempted has not finished yet (still in progress in the background).
UnknownSocketError	-1	An unidentified error occurred.
UnsupportedSocketOperationError	10	The requested socket operation is not supported by the local operating system (e.g., lack of IPv6 support).

---

SocketOption

This enum represents the options that can be set on a socket. If desired, they can be set after having received the connected signal from the socket or after having received a new socket from a QTcpServer.

Possible values for TypeOfServiceOption are:

Value	Description
224	Network control
192	Internetwork control
160	CRITIC/ECP
128	Flash override
96	Flash
64	Immediate
32	Priority
0	Routine

See also

setSocketOption(), socketOption().

Member	Value	Description
KeepAliveOption	1	Set this to 1 to enable the SO_KEEPALIVE socket option
LowDelayOption	0	Try to optimize the socket for low latency. For a QTcpSocket this would set the TCP_NODELAY option and disable Nagle’s algorithm. Set this to 1 to enable.
MulticastLoopbackOption	3	Set this to 1 to enable the IP_MULTICAST_LOOP (multicast loopback) socket option.
MulticastTtlOption	2	Set this to an integer value to set IP_MULTICAST_TTL (TTL for multicast datagrams) socket option.
PathMtuSocketOption	TODO	Retrieves the Path Maximum Transmission Unit (PMTU) value currently known by the IP stack, if any. Some IP stacks also allow setting the MTU for transmission. This enum value was introduced in Qt 5.11.
ReceiveBufferSizeSocketOption	TODO	Sets the socket receive buffer size in bytes at the OS level. This maps to the SO_RCVBUF socket option. This option does not affect the QIODevice or QAbstractSocket buffers (see setReadBufferSize()). This enum value has been introduced in Qt 5.3.
SendBufferSizeSocketOption	TODO	Sets the socket send buffer size in bytes at the OS level. This maps to the SO_SNDBUF socket option. This option does not affect the QIODevice or QAbstractSocket buffers. This enum value has been introduced in Qt 5.3.
TypeOfServiceOption	TODO	This option is not supported on Windows. This maps to the IP_TOS socket option. For possible values, see table below.

---

SocketState

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

See also

state().

Member	Value	Description
BoundState	4	The socket is bound to an address and port.
ClosingState	6	The socket is about to close (data may still be waiting to be written).
ConnectedState	3	A connection is established.
ConnectingState	2	The socket has started establishing a connection.
HostLookupState	1	The socket is performing a host name lookup.
ListeningState	5	For internal use only.
UnconnectedState	0	The socket is not connected.

---

SocketType

This enum describes the transport layer protocol.

See also

socketType().

Member	Value	Description
SctpSocket	TODO	SCTP
TcpSocket	0	TCP
UdpSocket	1	UDP
UnknownSocketType	-1	Other than TCP, UDP and SCTP

Methods

__init__(SocketType, QObject)

TODO

---

abort()

TODO

---

atEnd() → bool

TODO

---

bind(port: int = 0, mode: Union[BindMode, BindFlag] = DefaultForPlatform) → bool

TODO

---

bind(Union[QHostAddress, SpecialAddress], port: int = 0, mode: Union[BindMode, BindFlag] = DefaultForPlatform) → bool

TODO

---

bytesAvailable() → int

TODO

---

bytesToWrite() → int

TODO

---

canReadLine() → bool

TODO

---

close()

TODO

---

connectToHost(Union[QHostAddress, SpecialAddress], int, mode: Union[OpenMode, OpenModeFlag] = ReadWrite)

TODO

---

connectToHost(str, int, mode: Union[OpenMode, OpenModeFlag] = ReadWrite, protocol: NetworkLayerProtocol = AnyIPProtocol)

TODO

---

disconnectFromHost()

TODO

---

error() → SocketError

TODO

---

flush() → bool

TODO

---

isSequential() → bool

TODO

---

isValid() → bool

TODO

---

localAddress() → QHostAddress

See also

setLocalAddress().

---

localPort() → int

See also

setLocalPort().

---

pauseMode() → PauseModes

TODO

---

peerAddress() → QHostAddress

See also

setPeerAddress().

---

peerName() → str

See also

setPeerName().

---

peerPort() → int

See also

setPeerPort().

---

protocolTag() → str

TODO

---

proxy() → QNetworkProxy

See also

setProxy().

---

readBufferSize() → int

See also

setReadBufferSize().

---

readData(int) → bytes

TODO

---

readLineData(int) → bytes

TODO

---

resume()

TODO

---

setLocalAddress(Union[QHostAddress, SpecialAddress])

See also

localAddress().

---

setLocalPort(int)

See also

localPort().

---

setPauseMode(Union[PauseModes, PauseMode])

TODO

---

setPeerAddress(Union[QHostAddress, SpecialAddress])

See also

peerAddress().

---

setPeerName(str)

See also

peerName().

---

setPeerPort(int)

See also

peerPort().

---

setProtocolTag(str)

TODO

---

setProxy(QNetworkProxy)

See also

proxy().

---

setReadBufferSize(int)

See also

readBufferSize().

---

setSocketDescriptor(sip.voidptr, state: SocketState = ConnectedState, mode: Union[OpenMode, OpenModeFlag] = ReadWrite) → bool

TODO

---

setSocketError(SocketError)

TODO

---

setSocketOption(SocketOption, Any)

See also

socketOption().

---

setSocketState(SocketState)

TODO

---

socketDescriptor() → sip.voidptr

See also

setSocketDescriptor().

---

socketOption(SocketOption) → Any

See also

setSocketOption().

---

socketType() → SocketType

TODO

---

state() → SocketState

TODO

---

waitForBytesWritten(msecs: int = 30000) → bool

TODO

---

waitForConnected(msecs: int = 30000) → bool

TODO

---

waitForDisconnected(msecs: int = 30000) → bool

TODO

---

waitForReadyRead(msecs: int = 30000) → bool

TODO

---

writeData(bytes) → int

TODO

Signals

connected()

TODO

---

disconnected()

TODO

---

error()

TODO

---

error(SocketError)

TODO

---

hostFound()

TODO

---

proxyAuthenticationRequired(QNetworkProxy, QAuthenticator)

TODO

---

stateChanged(SocketState)

TODO