## gstbytestream

gstbytestream — exposes a stream interface on pads.

## Synopsis

    #include <libs/bytestream/bytestream.h>

    struct      GstByteStream;
    void        gst_bytestream_destroy          (GstByteStream *bs);
    gboolean    gst_bytestream_flush            (GstByteStream *bs,
                                                 guint32 len);
    void        gst_bytestream_flush_fast       (GstByteStream *bs,
                                                 guint32 len);
    void        gst_bytestream_get_status       (GstByteStream *bs,
                                                 guint32 *avail_out,
                                                 GstEvent **event_out);
    guint64     gst_bytestream_get_timestamp    (GstByteStream *bs);
    guint64     gst_bytestream_length           (GstByteStream *bs);
    GstByteStream* gst_bytestream_new           (GstPad *pad);
    guint32     gst_bytestream_peek             (GstByteStream *bs,
                                                 GstBuffer **buf,
                                                 guint32 len);
    guint32     gst_bytestream_peek_bytes       (GstByteStream *bs,
                                                 guint8 **data,
                                                 guint32 len);
    void        gst_bytestream_print_status     (GstByteStream *bs);
    guint32     gst_bytestream_read             (GstByteStream *bs,
                                                 GstBuffer **buf,
                                                 guint32 len);
    void        gst_bytestream_reset            (GstByteStream *bs);
    gboolean    gst_bytestream_seek             (GstByteStream *bs,
                                                 gint64 offset,
                                                 GstSeekType method);
    gboolean    gst_bytestream_size_hint        (GstByteStream *bs,
                                                 guint32 size);
    guint64     gst_bytestream_tell             (GstByteStream *bs);

## Description

## Details

### struct GstByteStream

    struct GstByteStream {

      GstPad 	*pad;

      GstEvent 	*event;

      GSList 	*buflist;
      guint32 	 headbufavail;
      guint32 	 listavail;

      /* we keep state of assembled pieces */
      guint8	*assembled;
      guint32	 assembled_len; /* only valid when assembled != NULL */

      /* this is needed for gst_bytestream_tell */
      guint64	 offset;
      guint64	 last_ts;

      /* if we are in the seek state (waiting for DISCONT) */
      gboolean	 in_seek;

      gpointer _gst_reserved[GST_PADDING];
    };

### gst_bytestream_destroy ()

    void        gst_bytestream_destroy          (GstByteStream *bs);

destroy the bytestream object and free its resources.

`bs` : | the bytestream object to destroy

### gst_bytestream_flush ()

    gboolean    gst_bytestream_flush            (GstByteStream *bs,
                                                 guint32 len);

Flush len bytes from the bytestream. This function can return FALSE when the number of bytes could not be flushed due to an event. In that case, you can get the number of available bytes before the event with `gst_bytestream_get_status()`.

`bs` : | the bytestream to flush
`len` : | the number of bytes to flush
Returns : | TRUE if the number of bytes could be flushed.

### gst_bytestream_flush_fast ()

    void        gst_bytestream_flush_fast       (GstByteStream *bs,
                                                 guint32 len);

Flushes len bytes from the bytestream. This function is faster than `gst_bytestream_flush()` but only works when you have recently peeked no less than len bytes with `gst_bytestream_peek()` or `gst_bytestream_peek_bytes()`.

`bs` : | the bytestream to flush
`len` : | the number of bytes to flush

### gst_bytestream_get_status ()

    void        gst_bytestream_get_status       (GstByteStream *bs,
                                                 guint32 *avail_out,
                                                 GstEvent **event_out);

When an event occurs, the bytestream operations return a value less than the requested length. You must retrieve the event using this API before reading more bytes from the stream.

`bs` : | a bytestream
`avail_out` : | total number of bytes buffered
`event_out` : | an event

### gst_bytestream_get_timestamp ()

    guint64     gst_bytestream_get_timestamp    (GstByteStream *bs);

Get the timestamp of the first data in the bytestream. If no data exists 1 byte is read to load a new buffer.

This function will not check input buffer boundries. It is possible the next read could span two or more input buffers with different timestamps.

`bs` : | a bytestream
Returns : | a timestamp.

### gst_bytestream_length ()

    guint64     gst_bytestream_length           (GstByteStream *bs);

Get the total length of the bytestream.

`bs` : | a bytestream
Returns : | the total length or -1 on error.

### gst_bytestream_new ()

    GstByteStream* gst_bytestream_new           (GstPad *pad);

creates a bytestream from the given pad

`pad` : | the pad to attach the bytestream to
Returns : | a new GstByteStream object.

### gst_bytestream_peek ()

    guint32     gst_bytestream_peek             (GstByteStream *bs,
                                                 GstBuffer **buf,
                                                 guint32 len);

Peeks len bytes into the bytestream, the result is returned as a GstBuffer. Unref the buffer after usage. This function can return less bytes than requested. In that case, an event might have happened which you can retrieve with `gst_bytestream_get_status()`.

`bs` : | the bytestream to peek
`buf` : | pointer to a variable that can hold a buffer pointer.
`len` : | the number of bytes to peek
Returns : | The number of bytes successfully peeked.

### gst_bytestream_peek_bytes ()

    guint32     gst_bytestream_peek_bytes       (GstByteStream *bs,
                                                 guint8 **data,
                                                 guint32 len);

Peeks len bytes into the bytestream, the result is returned as a pointer to a guint8*. The data pointed to be data should not be freed and will become invalid after performing the next bytestream operation. This function can return less bytes than requested. In that case, an event might have happened which you can retrieve with `gst_bytestream_get_status()`.

`bs` : | the bytestream to peek
`data` : | pointer to a variable that can hold a guint8 pointer.
`len` : | the number of bytes to peek
Returns : | The number of bytes successfully peeked.

### gst_bytestream_print_status ()

    void        gst_bytestream_print_status     (GstByteStream *bs);

Print the current status of the bytestream object. mainly used for debugging purposes.

`bs` : | a bytestream

### gst_bytestream_read ()

    guint32     gst_bytestream_read             (GstByteStream *bs,
                                                 GstBuffer **buf,
                                                 guint32 len);

Read len bytes from the bytestream, the result is returned as a GstBuffer. Unref the buffer after usage. This function can return less bytes than requested. In that case, an event might have happened which you can retrieve with `gst_bytestream_get_status()`.

`bs` : | the bytestream to read
`buf` : | pointer to a variable that can hold a buffer pointer.
`len` : | the number of bytes to read
Returns : | The number of bytes successfully read.

### gst_bytestream_reset ()

    void        gst_bytestream_reset            (GstByteStream *bs);

`bs` : |

### gst_bytestream_seek ()

    gboolean    gst_bytestream_seek             (GstByteStream *bs,
                                                 gint64 offset,
                                                 GstSeekType method);

Perform a seek on the bytestream to the given offset. The method can be one of GST_SEEK_METHOD_CUR, GST_SEEK_METHOD_SET, GST_SEEK_METHOD_END. This seek will also flush any pending data in the bytestream or peer elements.

`bs` : | the bytestream to seek
`offset` : | the byte offset to seek to
`method` : | the seek method.
Returns : | TRUE when the seek succeeded.

### gst_bytestream_size_hint ()

    gboolean    gst_bytestream_size_hint        (GstByteStream *bs,
                                                 guint32 size);

Give a hint that we are going to read chunks of the given size. Giving size hints to the peer element might improve performance since less buffers need to be merged.

`bs` : | a bytestream
`size` : | the size to hint
Returns : | TRUE if the hint was accepted.

### gst_bytestream_tell ()

    guint64     gst_bytestream_tell             (GstByteStream *bs);

Get the current byteoffset in the bytestream.

`bs` : | a bytestream
Returns : | the offset or -1 on error.