![]() |
![]() |
![]() |
Swfdec Reference Manual | ![]() |
---|---|---|---|---|
SwfdecBuffer; #define SWFDEC_TYPE_BUFFER SwfdecBufferQueue; #define SWFDEC_TYPE_BUFFER_QUEUE SwfdecBuffer* swfdec_buffer_new (void); SwfdecBuffer* swfdec_buffer_new_and_alloc (guint size); SwfdecBuffer* swfdec_buffer_new_and_alloc0 (guint size); SwfdecBuffer* swfdec_buffer_new_for_data (unsigned char *data, guint size); SwfdecBuffer* swfdec_buffer_new_subbuffer (SwfdecBuffer *buffer, guint offset, guint length); SwfdecBuffer* swfdec_buffer_new_from_file (const char *filename, GError **error); SwfdecBuffer* swfdec_buffer_ref (SwfdecBuffer *buffer); void swfdec_buffer_unref (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); guint swfdec_buffer_queue_get_depth (SwfdecBufferQueue *queue); guint swfdec_buffer_queue_get_offset (SwfdecBufferQueue *queue); void swfdec_buffer_queue_push (SwfdecBufferQueue *queue, SwfdecBuffer *buffer); SwfdecBuffer* swfdec_buffer_queue_pull (SwfdecBufferQueue *queue, guint length); SwfdecBuffer* swfdec_buffer_queue_pull_buffer (SwfdecBufferQueue *queue); SwfdecBuffer* swfdec_buffer_queue_peek (SwfdecBufferQueue *queue, guint length);
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; guint length; } 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 |
guint length; | number of bytes in data. read-only |
#define SWFDEC_TYPE_BUFFER swfdec_buffer_get_type()
SwfdecBuffer is a boxed type for the glib type system. This macro
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.
#define SWFDEC_TYPE_BUFFER_QUEUE swfdec_buffer_queue_get_type()
SwfdecBufferQueue is a boxed type for the glib type system. This macro
SwfdecBuffer* swfdec_buffer_new (void);
Creates a new SwfdecBuffer to be filled by the user. Use like this:
SwfdecBuffer *buffer = swfdec_buffer_new (); buffer->data = mydata; buffer->length = mydata_length; buffer->free = mydata_freefunc;
Returns : | a new SwfdecBuffer referencing nothing. |
SwfdecBuffer* swfdec_buffer_new_and_alloc (guint 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 |
SwfdecBuffer* swfdec_buffer_new_and_alloc0 (guint size);
Createsa new buffer just like swfdec_buffer_new_and_alloc(), 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 |
SwfdecBuffer* swfdec_buffer_new_for_data (unsigned char *data, guint 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 |
SwfdecBuffer* swfdec_buffer_new_subbuffer (SwfdecBuffer *buffer, guint offset, guint 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. |
SwfdecBuffer* swfdec_buffer_new_from_file (const char *filename, GError **error);
Tries to create a buffer for the given filename using a GMappedFile. If the creation fails, NULL is returned and error is set. The error can be any of the errors that are valid from g_mapped_file_new().
filename : | file to read |
error : | 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.
buffer : | 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.
buffer : | a SwfdecBuffer |
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.
queue : | a SwfdecBufferQueue |
SwfdecBufferQueue* swfdec_buffer_queue_ref (SwfdecBufferQueue *queue);
increases the reference count of queue by one.
queue : | 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.
queue : | a SwfdecBufferQueue |
guint swfdec_buffer_queue_get_depth (SwfdecBufferQueue *queue);
Returns the number of bytes currently in queue.
queue : | a SwfdecBufferQueue |
Returns : | amount of bytes in queue. |
guint 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. |
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 |
SwfdecBuffer* swfdec_buffer_queue_pull (SwfdecBufferQueue *queue, guint 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 |
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. |
SwfdecBuffer* swfdec_buffer_queue_peek (SwfdecBufferQueue *queue, guint 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. |