Implementing QIODevice::writeData, confusing documentation

Question

I'm trying to implement a double buffer for a real-time audio application, and QAudioInput requires it to be a subclass of QIODevice. I'm finding the documentation for this method pretty confusing.

First of all, the method signature in the documentation doesn't match the header for QT 5.9.2, which has virtual qint64 writeData(const char *data, qint64 len) = 0;.

The documentation has this signature though: qint64 QIODevice::writeData(const char *data, qint64 maxSize)

The maxSize parameter confuses me because it implies that I can just buffer some of the data, which the documentation also implies with:

Writes up to maxSize bytes from data to the device. Returns the number of bytes written, or -1 if an error occurred.

However, immediately afterword the documentation says this, which seems contradictory to me:

When reimplementing this function it is important that this function writes all the data available before returning. This is required in order for QDataStream to be able to operate on the class. QDataStream assumes all the information was written and therefore does not retry writing if there was a problem.

So is my QIODevice implementation responsible for buffering all the data in a single call or not?

changing the name of a parameter has no impact on the signature of a function. or is it the virtual that disturbs you? — 463035818_is_not_a_number
Nice find! :] Current implementation of QDataStream, doesn't seem to use writeData. — bezet
It's the implication of the parameter name that disturbs me. To me maxSize implies that I needn't write all the data, while len has no implication either way. Combined with the confusing documentation I'm tying to get clarification. — nw.
starting from line 267 there is a bit more explanation: code.qt.io/cgit/qt/qtbase.git/tree/src/corelib/io/qiodevice.cpp — 463035818_is_not_a_number

Felix Felix · Accepted Answer · 2017-10-11T13:03:12

What they basically trying to say is: The passed data is maxSize bytes long. Your implementation should write all data and return the number of bytes written.

It is possible to write less data then available, but you should not. If you do, some classes that use your device may not react to this (like QDataStream). It depends on how QAudioInput handles write calls. If it checks the result and writes missing data again if not completly written, not writing all data is fine. If thats not the case, you have to always write all data.

Simply try it out: always write only 1 byte (and return 1). If it works, it's fine, if not you have to always write all passed data, or fail with -1.

Implementing QIODevice::writeData, confusing documentation

1 Answers