QSctpSocket Class

The QSctpSocket class provides an SCTP socket. More...

Header: #include <QSctpSocket>
CMake: find_package(Qt6 REQUIRED COMPONENTS Network)
target_link_libraries(mytarget PRIVATE Qt6::Network)
qmake: QT += network
Inherits: QTcpSocket

Public Functions

QSctpSocket(QObject *parent = nullptr)
virtual ~QSctpSocket()
bool isInDatagramMode() const
int maximumChannelCount() const
QNetworkDatagram readDatagram()
void setMaximumChannelCount(int count)
bool writeDatagram(const QNetworkDatagram &datagram)

Reimplemented Public Functions

virtual void close() override
virtual void disconnectFromHost() override

Reimplemented Protected Functions

virtual qint64 readData(char *data, qint64 maxSize) override
virtual qint64 readLineData(char *data, qint64 maxlen) override

Detailed Description

SCTP (Stream Control Transmission Protocol) is a transport layer protocol serving in a similar role as the popular protocols TCP and UDP. Like UDP, SCTP is message-oriented, but it ensures reliable, in-sequence transport of messages with congestion control like TCP.

SCTP is connection-oriented protocol, which provides the complete simultaneous transmission of multiple data streams between endpoints. This multi-streaming allows data to be delivered by independent channels, so that if there is data loss in one stream, delivery will not be affected for the other streams.

Being message-oriented, SCTP transports a sequence of messages, rather than transporting an unbroken stream of bytes as does TCP. Like in UDP, in SCTP a sender sends a message in one operation, and that exact message is passed to the receiving application process in one operation. But unlike UDP, the delivery is guaranteed.

It also supports multi-homing, meaning that a connected endpoint can have alternate IP addresses associated with it in order to route around network failure or changing conditions.

QSctpSocket is a convenience subclass of QTcpSocket that allows you to emulate TCP data stream over SCTP or establish an SCTP connection for reliable datagram service.

QSctpSocket can operate in one of two possible modes:

  • Continuous byte stream (TCP emulation).
  • Multi-streamed datagram mode.

To set a continuous byte stream mode, instantiate QSctpSocket and call setMaximumChannelCount() with a negative value. This gives the ability to use QSctpSocket as a regular buffered QTcpSocket. You can call connectToHost() to initiate connection with endpoint, write() to transmit and read() to receive data from the peer, but you cannot distinguish message boundaries.

By default, QSctpSocket operates in datagram mode. Before connecting, call setMaximumChannelCount() to set the maximum number of channels that the application is prepared to support. This number is a parameter negotiated with the remote endpoint and its value can be bounded by the operating system. The default value of 0 indicates to use the peer's value. If both endpoints have default values, then number of connection channels is system-dependent. After establishing a connection, you can fetch the actual number of channels by calling readChannelCount() and writeChannelCount().

 QSctpSocket *socket = new QSctpSocket(this);

 socket->setMaxChannelCount(16);
 socket->connectToHost(QHostAddress::LocalHost, 1973);

 if (socket->waitForConnected(1000)) {
     int inputChannels = socket->readChannelCount();
     int outputChannels = socket->writeChannelCount();

     ....
 }

In datagram mode, QSctpSocket performs the buffering of datagrams independently for each channel. You can queue a datagram to the buffer of the current channel by calling writeDatagram() and read a pending datagram by calling readDatagram() respectively.

Using the standard QIODevice functions read(), readLine(), write(), etc. is allowed in datagram mode with the same limitations as in continuous byte stream mode.

Note: This class is not supported on the Windows platform.

See also QSctpServer, QTcpSocket, and QAbstractSocket.

Member Function Documentation

[explicit] QSctpSocket::QSctpSocket(QObject *parent = nullptr)

Creates a QSctpSocket object in state UnconnectedState.

Sets the datagram operation mode. The parent argument is passed to QObject's constructor.

See also socketType() and setMaximumChannelCount().

[virtual noexcept] QSctpSocket::~QSctpSocket()

Destroys the socket, closing the connection if necessary.

See also close().

[override virtual] void QSctpSocket::close()

Reimplements: QAbstractSocket::close().

[override virtual] void QSctpSocket::disconnectFromHost()

Reimplements: QAbstractSocket::disconnectFromHost().

bool QSctpSocket::isInDatagramMode() const

Returns true if the socket is running in datagram mode.

See also setMaximumChannelCount().

int QSctpSocket::maximumChannelCount() const

Returns the maximum number of channels that QSctpSocket is able to support.

A value of 0 (the default) means that the number of connection channels would be set by the remote endpoint.

Returns -1 if QSctpSocket is running in continuous byte stream mode.

See also setMaximumChannelCount(), readChannelCount(), and writeChannelCount().

[override virtual protected] qint64 QSctpSocket::readData(char *data, qint64 maxSize)

Reimplements: QAbstractSocket::readData(char *data, qint64 maxSize).

QNetworkDatagram QSctpSocket::readDatagram()

Reads a datagram from the buffer of the current read channel, and returns it as a QNetworkDatagram object, along with the sender's host address and port. If possible, this function will also try to determine the datagram's destination address, port, and the number of hop counts at reception time.

On failure, returns a QNetworkDatagram that reports not valid.

See also writeDatagram(), isInDatagramMode(), and currentReadChannel().

[override virtual protected] qint64 QSctpSocket::readLineData(char *data, qint64 maxlen)

Reimplements: QAbstractSocket::readLineData(char *data, qint64 maxlen).

void QSctpSocket::setMaximumChannelCount(int count)

Sets the maximum number of channels that the application is prepared to support in datagram mode, to count. If count is 0, endpoint's value for maximum number of channels is used. Negative count sets a continuous byte stream mode.

Call this method only when QSctpSocket is in UnconnectedState.

See also maximumChannelCount(), readChannelCount(), and writeChannelCount().

bool QSctpSocket::writeDatagram(const QNetworkDatagram &datagram)

Writes a datagram to the buffer of the current write channel. Returns true on success; otherwise returns false.

See also readDatagram(), isInDatagramMode(), and currentWriteChannel().