GMemoryOutputStream

GMemoryOutputStream — Streaming output operations on memory chunks

Synopsis

#include <gio/gio.h>

gpointer            (*GReallocFunc)                     (gpointer data,
                                                         gsize size);
                    GMemoryOutputStream;
GOutputStream *     g_memory_output_stream_new          (gpointer data,
                                                         gsize size,
                                                         GReallocFunc realloc_function,
                                                         GDestroyNotify destroy_function);
GOutputStream *     g_memory_output_stream_new_resizable
                                                        (void);
gpointer            g_memory_output_stream_get_data     (GMemoryOutputStream *ostream);
gsize               g_memory_output_stream_get_size     (GMemoryOutputStream *ostream);
gsize               g_memory_output_stream_get_data_size
                                                        (GMemoryOutputStream *ostream);
gpointer            g_memory_output_stream_steal_data   (GMemoryOutputStream *ostream);
GBytes *            g_memory_output_stream_steal_as_bytes
                                                        (GMemoryOutputStream *ostream);

Object Hierarchy

  GObject
   +----GOutputStream
         +----GMemoryOutputStream

Implemented Interfaces

GMemoryOutputStream implements GSeekable and GPollableOutputStream.

Properties

  "data"                     gpointer              : Read / Write / Construct Only
  "data-size"                gulong                : Read
  "destroy-function"         gpointer              : Read / Write / Construct Only
  "realloc-function"         gpointer              : Read / Write / Construct Only
  "size"                     gulong                : Read / Write / Construct Only

Description

GMemoryOutputStream is a class for using arbitrary memory chunks as output for GIO streaming output operations.

As of GLib 2.34, GMemoryOutputStream trivially implements GPollableOutputStream: it always polls as ready.

Details

GReallocFunc ()

gpointer            (*GReallocFunc)                     (gpointer data,
                                                         gsize size);

Changes the size of the memory block pointed to by data to size bytes.

The function should have the same semantics as realloc().

data :

memory block to reallocate

size :

size to reallocate data to

Returns :

a pointer to the reallocated memory

GMemoryOutputStream

typedef struct _GMemoryOutputStream GMemoryOutputStream;

Implements GOutputStream for arbitrary memory chunks.


g_memory_output_stream_new ()

GOutputStream *     g_memory_output_stream_new          (gpointer data,
                                                         gsize size,
                                                         GReallocFunc realloc_function,
                                                         GDestroyNotify destroy_function);

Creates a new GMemoryOutputStream.

In most cases this is not the function you want. See g_memory_output_stream_new_resizable() instead.

If data is non-NULL, the stream will use that for its internal storage.

If realloc_fn is non-NULL, it will be used for resizing the internal storage when necessary and the stream will be considered resizable. In that case, the stream will start out being (conceptually) empty. size is used only as a hint for how big data is. Specifically, seeking to the end of a newly-created stream will seek to zero, not size. Seeking past the end of the stream and then writing will introduce a zero-filled gap.

If realloc_fn is NULL then the stream is fixed-sized. Seeking to the end will seek to size exactly. Writing past the end will give an 'out of space' error. Attempting to seek past the end will fail. Unlike the resizable case, seeking to an offset within the stream and writing will preserve the bytes passed in as data before that point and will return them as part of g_memory_output_stream_steal_data(). If you intend to seek you should probably therefore ensure that data is properly initialised.

It is probably only meaningful to provide data and size in the case that you want a fixed-sized stream. Put another way: if realloc_fn is non-NULL then it makes most sense to give data as NULL and size as 0 (allowing GMemoryOutputStream to do the initial allocation for itself).

1
2
3
4
5
6
7
8
9
/* a stream that can grow */
stream = g_memory_output_stream_new (NULL, 0, realloc, free);

/* another stream that can grow */
stream2 = g_memory_output_stream_new (NULL, 0, g_realloc, g_free);

/* a fixed-size stream */
data = malloc (200);
stream3 = g_memory_output_stream_new (data, 200, NULL, free);

data :

pointer to a chunk of memory to use, or NULL. [allow-none]

size :

the size of data

realloc_function :

a function with realloc() semantics (like g_realloc()) to be called when data needs to be grown, or NULL. [allow-none]

destroy_function :

a function to be called on data when the stream is finalized, or NULL. [allow-none]

Returns :

A newly created GMemoryOutputStream object.

g_memory_output_stream_new_resizable ()

GOutputStream *     g_memory_output_stream_new_resizable
                                                        (void);

Creates a new GMemoryOutputStream, using g_realloc() and g_free() for memory allocation.

Since 2.36


g_memory_output_stream_get_data ()

gpointer            g_memory_output_stream_get_data     (GMemoryOutputStream *ostream);

Gets any loaded data from the ostream.

Note that the returned pointer may become invalid on the next write or truncate operation on the stream.

ostream :

a GMemoryOutputStream

Returns :

pointer to the stream's data. [transfer none]

g_memory_output_stream_get_size ()

gsize               g_memory_output_stream_get_size     (GMemoryOutputStream *ostream);

Gets the size of the currently allocated data area (available from g_memory_output_stream_get_data()).

You probably don't want to use this function on resizable streams. See g_memory_output_stream_get_data_size() instead. For resizable streams the size returned by this function is an implementation detail and may be change at any time in response to operations on the stream.

If the stream is fixed-sized (ie: no realloc was passed to g_memory_output_stream_new()) then this is the maximum size of the stream and further writes will return G_IO_ERROR_NO_SPACE.

In any case, if you want the number of bytes currently written to the stream, use g_memory_output_stream_get_data_size().

ostream :

a GMemoryOutputStream

Returns :

the number of bytes allocated for the data buffer

g_memory_output_stream_get_data_size ()

gsize               g_memory_output_stream_get_data_size
                                                        (GMemoryOutputStream *ostream);

Returns the number of bytes from the start up to including the last byte written in the stream that has not been truncated away.

ostream :

a GMemoryOutputStream

Returns :

the number of bytes written to the stream

Since 2.18


g_memory_output_stream_steal_data ()

gpointer            g_memory_output_stream_steal_data   (GMemoryOutputStream *ostream);

Gets any loaded data from the ostream. Ownership of the data is transferred to the caller; when no longer needed it must be freed using the free function set in ostream's "destroy-function" property.

ostream must be closed before calling this function.

ostream :

a GMemoryOutputStream

Returns :

the stream's data. [transfer full]

Since 2.26


g_memory_output_stream_steal_as_bytes ()

GBytes *            g_memory_output_stream_steal_as_bytes
                                                        (GMemoryOutputStream *ostream);

Returns data from the ostream as a GBytes. ostream must be closed before calling this function.

ostream :

a GMemoryOutputStream

Returns :

the stream's data. [transfer full]

Since 2.34

Property Details

The "data" property

  "data"                     gpointer              : Read / Write / Construct Only

Pointer to buffer where data will be written.

Since 2.24


The "data-size" property

  "data-size"                gulong                : Read

Size of data written to the buffer.

Since 2.24


The "destroy-function" property

  "destroy-function"         gpointer              : Read / Write / Construct Only

Function called with the buffer as argument when the stream is destroyed.

Since 2.24


The "realloc-function" property

  "realloc-function"         gpointer              : Read / Write / Construct Only

Function with realloc semantics called to enlarge the buffer.

Since 2.24


The "size" property

  "size"                     gulong                : Read / Write / Construct Only

Current size of the data buffer.

Since 2.24

See Also

GMemoryInputStream