[gst-devel] bytestream api needs changing?

[Baker, Steve]

I have been thinking that the current bytestream api doesn't handle events
correctly.  Currently the following functions return the exact number of
bytes requested, or return null  if there is an event somewhere in the
buffer queue. The data in the buffers before the event is lost, which isn't
good for events like EOS because that data is lost forever.
GstBuffer* gst_bytestream_read       (GstByteStream *bs, guint32 len);
GstBuffer* gst_bytestream_peek       (GstByteStream *bs, guint32 len);
guint8*    gst_bytestream_peek_bytes (GstByteStream *bs, guint32 len);

What I am proposing is a file IO style of API where the functions return the
number of bytes actually retrieved, while populating a passed-in pointer
with the data:
guint32 gst_bytestream_read       (GstByteStream *bs, GstBuffer** buffer,
guint32 len);
guint32 gst_bytestream_peek       (GstByteStream *bs, GstBuffer** buffer,
guint32 len);
guint32 gst_bytestream_peek_bytes (GstByteStream *bs, guint8** data, guint32
len);

Elements should check the return value to confirm that they got the number
of bytes they expected. If bytes returned is less than len, then you know
that there will be an event waiting.  This conforms to a file IO style of
API which has proved itself for around 30 years, so I don't think the change
should be seen as making bs more complex or hard to maintain.

Existing elements can be converted to the new API with minimal changes by
doing things like changing:
if ((buf = gst_bytestream_read (bs, size)))
to:
if (size == gst_bytestream_read (bs, &buf, size))

In the longer term elements should handle the case where returned bytes <
size but if they don't do this then they won't be any less broken than they
already are.

Are there any objections to this change?

cheers