## SwfdecBuffer SwfdecBuffer — memory region handling |

## Synopsis

    #include <swfdec/swfdec.h>

                        SwfdecBuffer;
                        SwfdecBufferQueue;
    void                (*SwfdecBufferFreeFunc)             (gpointer *priv,
                                                             unsigned char *data);
    SwfdecBuffer*       swfdec_buffer_new                   (gsize size);
    SwfdecBuffer*       swfdec_buffer_new0                  (gsize size);
    SwfdecBuffer*       swfdec_buffer_new_full              (unsigned char *data,
                                                             gsize size,
                                                             SwfdecBufferFreeFunc free_func,
                                                             gpointer priv);
    #define             swfdec_buffer_new_static            (data, size)
    SwfdecBuffer*       swfdec_buffer_new_for_data          (unsigned char *data,
                                                             gsize size);
    SwfdecBuffer*       swfdec_buffer_new_subbuffer         (SwfdecBuffer *buffer,
                                                             gsize offset,
                                                             gsize length);
    SwfdecBuffer*       swfdec_buffer_new_from_file         (const char *filename,
                                                             GError **error);
    SwfdecBuffer*       swfdec_buffer_ref                   (SwfdecBuffer *buffer);
    void                swfdec_buffer_unref                 (SwfdecBuffer *buffer);
    SwfdecBuffer*       swfdec_buffer_get_super             (SwfdecBuffer *buffer);
    SwfdecBufferQueue*  swfdec_buffer_queue_new             (void);
    void                swfdec_buffer_queue_clear           (SwfdecBufferQueue *queue);
    SwfdecBufferQueue*  swfdec_buffer_queue_ref             (SwfdecBufferQueue *queue);
    void                swfdec_buffer_queue_unref           (SwfdecBufferQueue *queue);
    gsize               swfdec_buffer_queue_get_depth       (SwfdecBufferQueue *queue);
    gsize               swfdec_buffer_queue_get_offset      (SwfdecBufferQueue *queue);
    void                swfdec_buffer_queue_push            (SwfdecBufferQueue *queue,
                                                             SwfdecBuffer *buffer);
    SwfdecBuffer*       swfdec_buffer_queue_pull            (SwfdecBufferQueue *queue,
                                                             gsize length);
    SwfdecBuffer*       swfdec_buffer_queue_pull_buffer     (SwfdecBufferQueue *queue);
    SwfdecBuffer*       swfdec_buffer_queue_peek            (SwfdecBufferQueue *queue,
                                                             gsize length);
    SwfdecBuffer*       swfdec_buffer_queue_peek_buffer     (SwfdecBufferQueue *queue);
    void                swfdec_buffer_queue_flush           (SwfdecBufferQueue *queue,
                                                             gsize n_bytes);

## Description

This section describes how memory is to be handled when interacting with the Swfdec library. Memory regions are refcounted and passed using a SwfdecBuffer. If large memory segments need to be handled that may span multiple buffers, Swfdec uses a SwfdecBufferQueue.

## Details

### SwfdecBuffer

    typedef struct {
      unsigned char *	data;		/* memory region (consider as read only) */
      gsize			length;		/* length of the memory region pointer do by @data */
    } SwfdecBuffer;

To allow for easy sharing of memory regions, SwfdecBuffer was created. Every buffer refers to a memory region and its size and takes care of freeing that region when the buffer is no longer needed. They are reference countedto make it easy to refer to the same region from various independant parts of your code. Buffers also support some advanced functionalities like extracting parts of the buffer using `swfdec_buffer_new_subbuffer()` or using mmapped files with `swfdec_buffer_new_from_file()` without the need for a different API.

unsigned char *`data`; | the data. read-only
gsize `length`; | number of bytes in `data`. read-only

### SwfdecBufferQueue

    typedef struct {
    } SwfdecBufferQueue;

A SwfdecBufferQueue is a queue of continuous buffers that allows reading its data in chunks of pre-defined sizes. It is used to transform a data stream that was provided by buffers of random sizes to buffers of the right size.

### SwfdecBufferFreeFunc ()

    void                (*SwfdecBufferFreeFunc)             (gpointer *priv,
                                                             unsigned char *data);

This is the function prototype for the function that is called for freeing the memory pointed to by a buffer. See `swfdec_buffer_new()` for an example.

`priv` : | The private data registered for passing to this function
`data` : | The data to free

### swfdec_buffer_new ()

    SwfdecBuffer*       swfdec_buffer_new                   (gsize size);

Creates a new buffer and allocates new memory of `size` bytes to be used with the buffer.

`size` : | amount of bytes to allocate
Returns : | a new SwfdecBuffer with buffer->data pointing to new data

### swfdec_buffer_new0 ()

    SwfdecBuffer*       swfdec_buffer_new0                  (gsize size);

Createsa new buffer just like `swfdec_buffer_new()`, but ensures that the returned data gets initialized to be 0.

`size` : | amount of bytes to allocate
Returns : | a new SwfdecBuffer with buffer->data pointing to new data

### swfdec_buffer_new_full ()

    SwfdecBuffer*       swfdec_buffer_new_full              (unsigned char *data,
                                                             gsize size,
                                                             SwfdecBufferFreeFunc free_func,
                                                             gpointer priv);

Creates a new SwfdecBuffer for managing `data`. The provided `free_func` will be called when the returned buffer is not referenced anymore, the provided data needs to stay valid until that point.

`data` : | memory region to reference
`size` : | size of the provided memory region
`free_func` : | function to call for freeing the `data`
`priv` : | private data to bass to `free_func`
Returns : | a new SwfdecBuffer pointing to `data`

### swfdec_buffer_new_static()

    #define             swfdec_buffer_new_static(data, size)

Creates a buffer for static data.

`data` : | static data
`size` : | size of `data` in bytes

### swfdec_buffer_new_for_data ()

    SwfdecBuffer*       swfdec_buffer_new_for_data          (unsigned char *data,
                                                             gsize size);

Takes ownership of `data` and creates a new buffer managing it.

`data` : | memory region allocated with `g_malloc()`
`size` : | size of `data` in bytes
Returns : | a new SwfdecBuffer pointing to `data`

### swfdec_buffer_new_subbuffer ()

    SwfdecBuffer*       swfdec_buffer_new_subbuffer         (SwfdecBuffer *buffer,
                                                             gsize offset,
                                                             gsize length);

Creates a SwfdecBuffer for managing a partial section of the memory pointed to by `buffer`.

`buffer` : | SwfdecBuffer managing the region of memory
`offset` : | starting offset into data
`length` : | amount of bytes to manage
Returns : | a new SwfdecBuffer managing the indicated region.

### swfdec_buffer_new_from_file ()

    SwfdecBuffer*       swfdec_buffer_new_from_file         (const char *filename,
                                                             GError **error);

Creates a buffer containing the contents of the given file. If loading the file fails, `NULL` is returned and `error` is set. The error can be any of the errors that are valid for `g_file_get_contents()`.

`filename` : | file to read, in filename encoding
`error` : | return location for a GError or `NULL`
Returns : | a new SwfdecBuffer or `NULL` on failure

### swfdec_buffer_ref ()

    SwfdecBuffer*       swfdec_buffer_ref                   (SwfdecBuffer *buffer);

increases the reference count of `buffer` by one.

`buffer` : | a SwfdecBuffer
Returns : | The passed in `buffer`.

### swfdec_buffer_unref ()

    void                swfdec_buffer_unref                 (SwfdecBuffer *buffer);

Decreases the reference count of `buffer` by one. If no reference to this buffer exists anymore, the buffer and the memory it manages are freed.

`buffer` : | a SwfdecBuffer

### swfdec_buffer_get_super ()

    SwfdecBuffer*       swfdec_buffer_get_super             (SwfdecBuffer *buffer);

Returns the largest buffer that contains the memory pointed to by `buffer`. This will either be the passed `buffer` itself, or if the buffer was created via `swfdec_buffer_new_subbuffer()`, the buffer used for that.

`buffer` : | a SwfdecBuffer
Returns : | The largest `buffer` available that contains the memory pointed to by `buffer`.

### swfdec_buffer_queue_new ()

    SwfdecBufferQueue*  swfdec_buffer_queue_new             (void);

Creates a new empty buffer queue.

Returns : | a new buffer queue. Use `swfdec_buffer_queue_unref()` to free it.

### swfdec_buffer_queue_clear ()

    void                swfdec_buffer_queue_clear           (SwfdecBufferQueue *queue);

Resets `queue` into to initial state. All buffers it contains will be released and the offset will be reset to 0.

`queue` : | a SwfdecBufferQueue

### swfdec_buffer_queue_ref ()

    SwfdecBufferQueue*  swfdec_buffer_queue_ref             (SwfdecBufferQueue *queue);

increases the reference count of `queue` by one.

`queue` : | a SwfdecBufferQueue
Returns : | The passed in `queue`.

### swfdec_buffer_queue_unref ()

    void                swfdec_buffer_queue_unref           (SwfdecBufferQueue *queue);

Decreases the reference count of `queue` by one. If no reference to this buffer exists anymore, the buffer and the memory it manages are freed.

`queue` : | a SwfdecBufferQueue

### swfdec_buffer_queue_get_depth ()

    gsize               swfdec_buffer_queue_get_depth       (SwfdecBufferQueue *queue);

Returns the number of bytes currently in `queue`.

`queue` : | a SwfdecBufferQueue
Returns : | amount of bytes in `queue`.

### swfdec_buffer_queue_get_offset ()

    gsize               swfdec_buffer_queue_get_offset      (SwfdecBufferQueue *queue);

Queries the amount of bytes that has already been pulled out of `queue` using functions like `swfdec_buffer_queue_pull()`.

`queue` : | a SwfdecBufferQueue
Returns : | Number of bytes that were already pulled from this queue.

### swfdec_buffer_queue_push ()

    void                swfdec_buffer_queue_push            (SwfdecBufferQueue *queue,
                                                             SwfdecBuffer *buffer);

Appends the given `buffer` to the buffers already in `queue`. This function will take ownership of the given `buffer`. Use `swfdec_buffer_ref()` before calling this function to keep a reference.

`queue` : | a SwfdecBufferQueue
`buffer` : | SwfdecBuffer to append to `queue`

### swfdec_buffer_queue_pull ()

    SwfdecBuffer*       swfdec_buffer_queue_pull            (SwfdecBufferQueue *queue,
                                                             gsize length);

If enough data is still available in `queue`, the first `length` bytes are put into a new buffer and that buffer is returned. The `length` bytes are removed from the head of the queue. If not enough data is available, `NULL` is returned.

`queue` : | a SwfdecBufferQueue
`length` : | amount of bytes to pull
Returns : | a new SwfdecBuffer or `NULL`

### swfdec_buffer_queue_pull_buffer ()

    SwfdecBuffer*       swfdec_buffer_queue_pull_buffer     (SwfdecBufferQueue *queue);

Pulls the first buffer out of `queue` and returns it. This function is equivalent to calling `swfdec_buffer_queue_pull()` with the size of the first buffer in it.

`queue` : | a SwfdecBufferQueue
Returns : | The first buffer in `queue` or `NULL` if `queue` is empty.

### swfdec_buffer_queue_peek ()

    SwfdecBuffer*       swfdec_buffer_queue_peek            (SwfdecBufferQueue *queue,
                                                             gsize length);

Creates a new buffer with the first `length` bytes from `queue`, but unlike `swfdec_buffer_queue_pull()`, does not remove them from `queue`.

`queue` : | a SwfdecBufferQueue to read from
`length` : | amount of bytes to peek
Returns : | NULL if the requested amount of data wasn't available or a new readonly SwfdecBuffer. Use `swfdec_buffer_unref()` after use.

### swfdec_buffer_queue_peek_buffer ()

    SwfdecBuffer*       swfdec_buffer_queue_peek_buffer     (SwfdecBufferQueue *queue);

Gets the first buffer out of `queue` and returns it. This function is equivalent to calling `swfdec_buffer_queue_peek()` with the size of the first buffer in it.

`queue` : | a SwfdecBufferQueue
Returns : | The first buffer in `queue` or `NULL` if `queue` is empty. Use `swfdec_buffer_unref()` after use.

### swfdec_buffer_queue_flush ()

    void                swfdec_buffer_queue_flush           (SwfdecBufferQueue *queue,
                                                             gsize n_bytes);

Removes the first `n_bytes` bytes from the queue.

`queue` : | a SwfdecBufferQueue
`n_bytes` : | amount of bytes to flush from the queue