Swfdec Reference Manual | ||||
---|---|---|---|---|
#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);
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.
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 * |
the data. read-only |
gsize |
number of bytes in data . read-only
|
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.
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.
|
The private data registered for passing to this function |
|
The data to free |
SwfdecBuffer* swfdec_buffer_new (gsize size);
Creates a new buffer and allocates new memory of size
bytes to be used with
the buffer.
|
amount of bytes to allocate |
Returns : |
a new SwfdecBuffer with buffer->data pointing to new data |
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.
|
amount of bytes to allocate |
Returns : |
a new SwfdecBuffer with buffer->data pointing to new data |
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.
|
memory region to reference |
|
size of the provided memory region |
|
function to call for freeing the data
|
|
private data to bass to free_func
|
Returns : |
a new SwfdecBuffer pointing to data
|
#define swfdec_buffer_new_static(data, size)
Creates a buffer for static data.
|
static data |
|
size of data in bytes
|
SwfdecBuffer* swfdec_buffer_new_for_data (unsigned char *data, gsize size);
Takes ownership of data
and creates a new buffer managing it.
|
memory region allocated with g_malloc()
|
|
size of data in bytes
|
Returns : |
a new SwfdecBuffer pointing to data
|
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
.
|
SwfdecBuffer managing the region of memory |
|
starting offset into data |
|
amount of bytes to manage |
Returns : |
a new SwfdecBuffer managing the indicated region. |
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()
.
|
file to read, in filename encoding |
|
return location for a GError or NULL
|
Returns : |
a new SwfdecBuffer or NULL on failure
|
SwfdecBuffer* swfdec_buffer_ref (SwfdecBuffer *buffer);
increases the reference count of buffer
by one.
|
a SwfdecBuffer |
Returns : |
The passed in buffer .
|
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.
|
a SwfdecBuffer |
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.
|
a SwfdecBuffer |
Returns : |
The largest buffer available that contains the memory pointed to
by buffer .
|
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.
|
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.
|
a SwfdecBufferQueue |
SwfdecBufferQueue* swfdec_buffer_queue_ref (SwfdecBufferQueue *queue);
increases the reference count of queue
by one.
|
a SwfdecBufferQueue |
Returns : |
The passed in queue .
|
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.
|
a SwfdecBufferQueue |
gsize swfdec_buffer_queue_get_depth (SwfdecBufferQueue *queue);
Returns the number of bytes currently in queue
.
|
a SwfdecBufferQueue |
Returns : |
amount of bytes in queue .
|
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()
.
|
a SwfdecBufferQueue |
Returns : |
Number of bytes that were already pulled from this queue. |
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.
|
a SwfdecBufferQueue |
|
SwfdecBuffer to append to queue
|
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.
|
a SwfdecBufferQueue |
|
amount of bytes to pull |
Returns : |
a new SwfdecBuffer or NULL
|
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.
|
a SwfdecBufferQueue |
Returns : |
The first buffer in queue or NULL if queue is empty.
|
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
.
|
a SwfdecBufferQueue to read from |
|
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.
|
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.
|
a SwfdecBufferQueue |
Returns : |
The first buffer in queue or NULL if queue is empty. Use
swfdec_buffer_unref() after use.
|
void swfdec_buffer_queue_flush (SwfdecBufferQueue *queue, gsize n_bytes);
Removes the first n_bytes
bytes from the queue.
|
a SwfdecBufferQueue |
|
amount of bytes to flush from the queue |