SwfdecBuffer

SwfdecBuffer — memory region handling

Functions

Types and Values

Includes

#include <swfdec/swfdec.h>

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.

Functions

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

data

static data

 

size

size of data in bytes

 

Returns

a new SwfdecBuffer pointing to data


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.

Parameters

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 .

Parameters

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().

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

queue

a SwfdecBufferQueue

 

swfdec_buffer_queue_ref ()

SwfdecBufferQueue *
swfdec_buffer_queue_ref (SwfdecBufferQueue *queue);

increases the reference count of queue by one.

Parameters

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.

Parameters

queue

a SwfdecBufferQueue

 

swfdec_buffer_queue_get_depth ()

gsize
swfdec_buffer_queue_get_depth (SwfdecBufferQueue *queue);

Returns the number of bytes currently in queue .

Parameters

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().

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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 .

Parameters

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.

Parameters

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.

Parameters

queue

a SwfdecBufferQueue

 

n_bytes

amount of bytes to flush from the queue

 

Types and Values

struct SwfdecBuffer

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

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.

Members

unsigned char *data;

the data. read-only

 

gsize length;

number of bytes in data . read-only

 

struct SwfdecBufferQueue

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.