QPacketProtocol Class Reference
[QtBaseModule]

Detailed Description

The QPacketProtocol class encapsulates communicating discrete packets across fragmented IO channels, such as TCP sockets.

QPacketProtocol makes it simple to send arbitrary sized data "packets" across fragmented transports such as TCP and UDP.

As transmission boundaries are not respected, sending packets over protocols like TCP frequently involves "stitching" them back together at the receiver. QPacketProtocol makes this easier by performing this task for you. Packet data sent using QPacketProtocol is prepended with a 4-byte size header allowing the receiving QPacketProtocol to buffer the packet internally until it has all been received. QPacketProtocol does not perform any sanity checking on the size or on the data, so this class should only be used in prototyping or trusted situations where DOS attacks are unlikely.

QPacketProtocol does not perform any communications itself. Instead it can operate on any QIODevice that supports the QIODevice::readyRead() signal. A logical "packet" is encapsulated by the companion QPacket class. The following example shows two ways to send data using QPacketProtocol. The transmitted data is equivalent in both.

    QTcpSocket socket;
    // ... connect socket ...

    QPacketProtocol protocol(&socket);

    // Send packet the quick way
    protocol.send() << "Hello world" << 123;

    // Send packet the longer way
    QPacket packet;
    packet << "Hello world" << 123;
    protocol.send(packet);

Likewise, the following shows how to read data from QPacketProtocol, assuming that the QPacketProtocol::readyRead() signal has been emitted.

    // ... QPacketProtocol::readyRead() is emitted ...

    int a;
    QByteArray b;

    // Receive packet the quick way
    protocol.read() >> a >> b;

    // Receive packet the longer way
    QPacket packet = protocol.read();
    p >> a >> b;

See also QPacket.

Member Function Documentation

QPacketProtocol::QPacketProtocol ( QIODevice * dev, QObject * parent = 0 )

Construct a QPacketProtocol instance that works on dev with the specified parent.

QPacketProtocol::~QPacketProtocol ()   [virtual]

Destroys the QPacketProtocol instance.

void QPacketProtocol::clear ()

Discard any unread packets.

QIODevice * QPacketProtocol::device ()

Return the QIODevice passed to the QPacketProtocol constructor.

void QPacketProtocol::invalidPacket ()   [signal]

A packet larger than the maximum allowable packet size was received. The packet will be discarded and, as it indicates corruption in the protocol, no further packets will be received.

qint32 QPacketProtocol::maximumPacketSize () const

Returns the maximum packet size allowed. By default this is 2,147,483,647 bytes.

If a packet claiming to be larger than the maximum packet size is received, the QPacketProtocol::invalidPacket() signal is emitted.

See also QPacketProtocol::setMaximumPacketSize().

void QPacketProtocol::packetWritten ()   [signal]

Emitted each time a packet is completing written to the device. This signal may be used for communications flow control.

qint64 QPacketProtocol::packetsAvailable () const

Returns the number of received packets yet to be read.

QPacket QPacketProtocol::read ()

Return the next unread packet, or an invalid QPacket instance if no packets are available. This method does NOT block.

void QPacketProtocol::readyRead ()   [signal]

Emitted whenever a new packet is received. Applications may use QPacketProtocol::read() to retrieve this packet.

QPacketAutoSend QPacketProtocol::send ()

Returns a streamable object that is transmitted on destruction. For example

    protocol.send() << "Hello world" << 123;

will send a packet containing "Hello world" and 123. To construct more complex packets, explicitly construct a QPacket instance.

void QPacketProtocol::send ( const QPacket & packet )

This is an overloaded member function, provided for convenience.

Transmit the packet.

qint32 QPacketProtocol::setMaximumPacketSize ( qint32 max )

Sets the maximum allowable packet size to max.

See also QPacketProtocol::maximumPacketSize().