GDataInputStream: GIO Reference Manual

GDataInputStream

GDataInputStream — Data Input Stream

Functions

GDataInputStream *	g_data_input_stream_new ()
void	g_data_input_stream_set_byte_order ()
GDataStreamByteOrder	g_data_input_stream_get_byte_order ()
void	g_data_input_stream_set_newline_type ()
GDataStreamNewlineType	g_data_input_stream_get_newline_type ()
guchar	g_data_input_stream_read_byte ()
gint16	g_data_input_stream_read_int16 ()
guint16	g_data_input_stream_read_uint16 ()
gint32	g_data_input_stream_read_int32 ()
guint32	g_data_input_stream_read_uint32 ()
gint64	g_data_input_stream_read_int64 ()
guint64	g_data_input_stream_read_uint64 ()
char *	g_data_input_stream_read_line ()
char *	g_data_input_stream_read_line_utf8 ()
void	g_data_input_stream_read_line_async ()
char *	g_data_input_stream_read_line_finish ()
char *	g_data_input_stream_read_line_finish_utf8 ()
char *	g_data_input_stream_read_upto ()
void	g_data_input_stream_read_upto_async ()
char *	g_data_input_stream_read_upto_finish ()
char *	g_data_input_stream_read_until ()
void	g_data_input_stream_read_until_async ()
char *	g_data_input_stream_read_until_finish ()

Properties

GDataStreamByteOrder	byte-order	Read / Write
GDataStreamNewlineType	newline-type	Read / Write

Types and Values

	GDataInputStream
enum	GDataStreamByteOrder
enum	GDataStreamNewlineType

Object Hierarchy

    GEnum
    ├── GDataStreamByteOrder
    ╰── GDataStreamNewlineType
    GObject
    ╰── GInputStream
        ╰── GFilterInputStream
            ╰── GBufferedInputStream
                ╰── GDataInputStream

Implemented Interfaces

GDataInputStream implements GSeekable.

Includes

#include <gio/gio.h>

Description

Data input stream implements GInputStream and includes functions for reading structured data directly from a binary input stream.

Functions

g_data_input_stream_new ()

GDataInputStream *
g_data_input_stream_new (GInputStream *base_stream);

Creates a new data input stream for the base_stream .

Parameters

base_stream

a GInputStream.

Returns

a new GDataInputStream.

g_data_input_stream_set_byte_order ()

void
g_data_input_stream_set_byte_order (GDataInputStream *stream,
                                    GDataStreamByteOrder order);

This function sets the byte order for the given stream . All subsequent reads from the stream will be read in the given order .

Parameters

stream	a given GDataInputStream.
order	a GDataStreamByteOrder to set.

g_data_input_stream_get_byte_order ()

GDataStreamByteOrder
g_data_input_stream_get_byte_order (GDataInputStream *stream);

Gets the byte order for the data input stream.

Parameters

stream

a given GDataInputStream.

Returns

the stream 's current GDataStreamByteOrder.

g_data_input_stream_set_newline_type ()

void
g_data_input_stream_set_newline_type (GDataInputStream *stream,
                                      GDataStreamNewlineType type);

Sets the newline type for the stream .

Note that using G_DATA_STREAM_NEWLINE_TYPE_ANY is slightly unsafe. If a read chunk ends in "CR" we must read an additional byte to know if this is "CR" or "CR LF", and this might block if there is no more data available.

Parameters

stream	a GDataInputStream.
type	the type of new line return as GDataStreamNewlineType.

g_data_input_stream_get_newline_type ()

GDataStreamNewlineType
g_data_input_stream_get_newline_type (GDataInputStream *stream);

Gets the current newline type for the stream .

Parameters

stream

a given GDataInputStream.

Returns

GDataStreamNewlineType for the given stream .

g_data_input_stream_read_byte ()

guchar
g_data_input_stream_read_byte (GDataInputStream *stream,
                               GCancellable *cancellable,
                               GError **error);

Reads an unsigned 8-bit/1-byte value from stream .

Parameters

stream	a given GDataInputStream.
cancellable	optional GCancellable object, `NULL` to ignore.	[nullable]
error	GError for error reporting.

Returns

an unsigned 8-bit/1-byte value read from the stream or 0 if an error occurred.

g_data_input_stream_read_int16 ()

gint16
g_data_input_stream_read_int16 (GDataInputStream *stream,
                                GCancellable *cancellable,
                                GError **error);

Reads a 16-bit/2-byte value from stream .

In order to get the correct byte order for this read operation, see g_data_input_stream_get_byte_order() and g_data_input_stream_set_byte_order().

Parameters

stream	a given GDataInputStream.
cancellable	optional GCancellable object, `NULL` to ignore.	[nullable]
error	GError for error reporting.

Returns

a signed 16-bit/2-byte value read from stream or 0 if an error occurred.

g_data_input_stream_read_uint16 ()

guint16
g_data_input_stream_read_uint16 (GDataInputStream *stream,
                                 GCancellable *cancellable,
                                 GError **error);

Reads an unsigned 16-bit/2-byte value from stream .

In order to get the correct byte order for this read operation, see g_data_input_stream_get_byte_order() and g_data_input_stream_set_byte_order().

Parameters

stream	a given GDataInputStream.
cancellable	optional GCancellable object, `NULL` to ignore.	[nullable]
error	GError for error reporting.

Returns

an unsigned 16-bit/2-byte value read from the stream or 0 if an error occurred.

g_data_input_stream_read_int32 ()

gint32
g_data_input_stream_read_int32 (GDataInputStream *stream,
                                GCancellable *cancellable,
                                GError **error);

Reads a signed 32-bit/4-byte value from stream .

In order to get the correct byte order for this read operation, see g_data_input_stream_get_byte_order() and g_data_input_stream_set_byte_order().

If cancellable is not NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error G_IO_ERROR_CANCELLED will be returned.

Parameters

stream	a given GDataInputStream.
cancellable	optional GCancellable object, `NULL` to ignore.	[nullable]
error	GError for error reporting.

Returns

a signed 32-bit/4-byte value read from the stream or 0 if an error occurred.

g_data_input_stream_read_uint32 ()

guint32
g_data_input_stream_read_uint32 (GDataInputStream *stream,
                                 GCancellable *cancellable,
                                 GError **error);

Reads an unsigned 32-bit/4-byte value from stream .

In order to get the correct byte order for this read operation, see g_data_input_stream_get_byte_order() and g_data_input_stream_set_byte_order().

Parameters

stream	a given GDataInputStream.
cancellable	optional GCancellable object, `NULL` to ignore.	[nullable]
error	GError for error reporting.

Returns

an unsigned 32-bit/4-byte value read from the stream or 0 if an error occurred.

g_data_input_stream_read_int64 ()

gint64
g_data_input_stream_read_int64 (GDataInputStream *stream,
                                GCancellable *cancellable,
                                GError **error);

Reads a 64-bit/8-byte value from stream .

In order to get the correct byte order for this read operation, see g_data_input_stream_get_byte_order() and g_data_input_stream_set_byte_order().

Parameters

stream	a given GDataInputStream.
cancellable	optional GCancellable object, `NULL` to ignore.	[nullable]
error	GError for error reporting.

Returns

a signed 64-bit/8-byte value read from stream or 0 if an error occurred.

g_data_input_stream_read_uint64 ()

guint64
g_data_input_stream_read_uint64 (GDataInputStream *stream,
                                 GCancellable *cancellable,
                                 GError **error);

Reads an unsigned 64-bit/8-byte value from stream .

In order to get the correct byte order for this read operation, see g_data_input_stream_get_byte_order().

Parameters

stream	a given GDataInputStream.
cancellable	optional GCancellable object, `NULL` to ignore.	[nullable]
error	GError for error reporting.

Returns

an unsigned 64-bit/8-byte read from stream or 0 if an error occurred.

g_data_input_stream_read_line ()

char *
g_data_input_stream_read_line (GDataInputStream *stream,
                               gsize *length,
                               GCancellable *cancellable,
                               GError **error);

Reads a line from the data input stream. Note that no encoding checks or conversion is performed; the input is not guaranteed to be UTF-8, and may in fact have embedded NUL characters.

Parameters

stream	a given GDataInputStream.
length	a gsize to get the length of the data read in.	[out][optional]
cancellable	optional GCancellable object, `NULL` to ignore.	[nullable]
error	GError for error reporting.

Returns

a NUL terminated byte array with the line that was read in (without the newlines). Set length to a gsize to get the length of the read line. On an error, it will return NULL and error will be set. If there's no content to read, it will still return NULL, but error won't be set.

[nullable][transfer full][array zero-terminated=1][element-type guint8]

g_data_input_stream_read_line_utf8 ()

char *
g_data_input_stream_read_line_utf8 (GDataInputStream *stream,
                                    gsize *length,
                                    GCancellable *cancellable,
                                    GError **error);

Reads a UTF-8 encoded line from the data input stream.

Parameters

stream	a given GDataInputStream.
length	a gsize to get the length of the data read in.	[out][optional]
cancellable	optional GCancellable object, `NULL` to ignore.	[nullable]
error	GError for error reporting.

Returns

a NUL terminated UTF-8 string with the line that was read in (without the newlines). Set length to a gsize to get the length of the read line. On an error, it will return NULL and error will be set. For UTF-8 conversion errors, the set error domain is G_CONVERT_ERROR. If there's no content to read, it will still return NULL, but error won't be set.

[nullable][transfer full]

Since: 2.30

g_data_input_stream_read_line_async ()

void
g_data_input_stream_read_line_async (GDataInputStream *stream,
                                     gint io_priority,
                                     GCancellable *cancellable,
                                     GAsyncReadyCallback callback,
                                     gpointer user_data);

The asynchronous version of g_data_input_stream_read_line(). It is an error to have two outstanding calls to this function.

When the operation is finished, callback will be called. You can then call g_data_input_stream_read_line_finish() to get the result of the operation.

Parameters

stream	a given GDataInputStream.
io_priority	the I/O priority of the request
cancellable	optional GCancellable object, `NULL` to ignore.	[nullable]
callback	callback to call when the request is satisfied.	[scope async]
user_data	the data to pass to callback function.	[closure]

Since: 2.20

g_data_input_stream_read_line_finish ()

char *
g_data_input_stream_read_line_finish (GDataInputStream *stream,
                                      GAsyncResult *result,
                                      gsize *length,
                                      GError **error);

Finish an asynchronous call started by g_data_input_stream_read_line_async(). Note the warning about string encoding in g_data_input_stream_read_line() applies here as well.

Parameters

stream	a given GDataInputStream.
result	the GAsyncResult that was provided to the callback.
length	a gsize to get the length of the data read in.	[out][optional]
error	GError for error reporting.

Returns

a NUL-terminated byte array with the line that was read in (without the newlines). Set length to a gsize to get the length of the read line. On an error, it will return NULL and error will be set. If there's no content to read, it will still return NULL, but error won't be set.

[nullable][transfer full][array zero-terminated=1][element-type guint8]

Since: 2.20

g_data_input_stream_read_line_finish_utf8 ()

char *
g_data_input_stream_read_line_finish_utf8
                               (GDataInputStream *stream,
                                GAsyncResult *result,
                                gsize *length,
                                GError **error);

Finish an asynchronous call started by g_data_input_stream_read_line_async().

Parameters

stream	a given GDataInputStream.
result	the GAsyncResult that was provided to the callback.
length	a gsize to get the length of the data read in.	[out][optional]
error	GError for error reporting.

Returns

a string with the line that was read in (without the newlines). Set length to a gsize to get the length of the read line. On an error, it will return NULL and error will be set. For UTF-8 conversion errors, the set error domain is G_CONVERT_ERROR. If there's no content to read, it will still return NULL, but error won't be set.

[nullable][transfer full]

Since: 2.30

g_data_input_stream_read_upto ()

char *
g_data_input_stream_read_upto (GDataInputStream *stream,
                               const gchar *stop_chars,
                               gssize stop_chars_len,
                               gsize *length,
                               GCancellable *cancellable,
                               GError **error);

Reads a string from the data input stream, up to the first occurrence of any of the stop characters.

In contrast to g_data_input_stream_read_until(), this function does not consume the stop character. You have to use g_data_input_stream_read_byte() to get it before calling g_data_input_stream_read_upto() again.

Note that stop_chars may contain '\0' if stop_chars_len is specified.

The returned string will always be nul-terminated on success.

Parameters

stream	a GDataInputStream
stop_chars	characters to terminate the read
stop_chars_len	length of `stop_chars` . May be -1 if `stop_chars` is nul-terminated
length	a gsize to get the length of the data read in.	[out][optional]
cancellable	optional GCancellable object, `NULL` to ignore.	[nullable]
error	GError for error reporting

Returns

a string with the data that was read before encountering any of the stop characters. Set length to a gsize to get the length of the string. This function will return NULL on an error.

[transfer full]

Since: 2.26

g_data_input_stream_read_upto_async ()

void
g_data_input_stream_read_upto_async (GDataInputStream *stream,
                                     const gchar *stop_chars,
                                     gssize stop_chars_len,
                                     gint io_priority,
                                     GCancellable *cancellable,
                                     GAsyncReadyCallback callback,
                                     gpointer user_data);

The asynchronous version of g_data_input_stream_read_upto(). It is an error to have two outstanding calls to this function.

Note that stop_chars may contain '\0' if stop_chars_len is specified.

When the operation is finished, callback will be called. You can then call g_data_input_stream_read_upto_finish() to get the result of the operation.

Parameters

stream	a GDataInputStream
stop_chars	characters to terminate the read
stop_chars_len	length of `stop_chars` . May be -1 if `stop_chars` is nul-terminated
io_priority	the I/O priority of the request
cancellable	optional GCancellable object, `NULL` to ignore.	[nullable]
callback	callback to call when the request is satisfied.	[scope async]
user_data	the data to pass to callback function.	[closure]

Since: 2.26

g_data_input_stream_read_upto_finish ()

char *
g_data_input_stream_read_upto_finish (GDataInputStream *stream,
                                      GAsyncResult *result,
                                      gsize *length,
                                      GError **error);

Finish an asynchronous call started by g_data_input_stream_read_upto_async().

Note that this function does not consume the stop character. You have to use g_data_input_stream_read_byte() to get it before calling g_data_input_stream_read_upto_async() again.

The returned string will always be nul-terminated on success.

Parameters

stream	a GDataInputStream
result	the GAsyncResult that was provided to the callback
length	a gsize to get the length of the data read in.	[out][optional]
error	GError for error reporting

Returns

a string with the data that was read before encountering any of the stop characters. Set length to a gsize to get the length of the string. This function will return NULL on an error.

[transfer full]

Since: 2.24

g_data_input_stream_read_until ()

char *
g_data_input_stream_read_until (GDataInputStream *stream,
                                const gchar *stop_chars,
                                gsize *length,
                                GCancellable *cancellable,
                                GError **error);

g_data_input_stream_read_until has been deprecated since version 2.56 and should not be used in newly-written code.

Use g_data_input_stream_read_upto() instead, which has more consistent behaviour regarding the stop character.

Reads a string from the data input stream, up to the first occurrence of any of the stop characters.

Note that, in contrast to g_data_input_stream_read_until_async(), this function consumes the stop character that it finds.

Don't use this function in new code. Its functionality is inconsistent with g_data_input_stream_read_until_async(). Both functions will be marked as deprecated in a future release. Use g_data_input_stream_read_upto() instead, but note that that function does not consume the stop character.

Parameters

stream	a given GDataInputStream.
stop_chars	characters to terminate the read.
length	a gsize to get the length of the data read in.	[out][optional]
cancellable	optional GCancellable object, `NULL` to ignore.	[nullable]
error	GError for error reporting.

Returns

a string with the data that was read before encountering any of the stop characters. Set length to a gsize to get the length of the string. This function will return NULL on an error.

[transfer full]

g_data_input_stream_read_until_async ()

void
g_data_input_stream_read_until_async (GDataInputStream *stream,
                                      const gchar *stop_chars,
                                      gint io_priority,
                                      GCancellable *cancellable,
                                      GAsyncReadyCallback callback,
                                      gpointer user_data);

g_data_input_stream_read_until_async has been deprecated since version 2.56 and should not be used in newly-written code.

Use g_data_input_stream_read_upto_async() instead, which has more consistent behaviour regarding the stop character.

The asynchronous version of g_data_input_stream_read_until(). It is an error to have two outstanding calls to this function.

Note that, in contrast to g_data_input_stream_read_until(), this function does not consume the stop character that it finds. You must read it for yourself.

When the operation is finished, callback will be called. You can then call g_data_input_stream_read_until_finish() to get the result of the operation.

Don't use this function in new code. Its functionality is inconsistent with g_data_input_stream_read_until(). Both functions will be marked as deprecated in a future release. Use g_data_input_stream_read_upto_async() instead.

Parameters

stream	a given GDataInputStream.
stop_chars	characters to terminate the read.
io_priority	the I/O priority of the request
cancellable	optional GCancellable object, `NULL` to ignore.	[nullable]
callback	callback to call when the request is satisfied.	[scope async]
user_data	the data to pass to callback function.	[closure]

Since: 2.20

g_data_input_stream_read_until_finish ()

char *
g_data_input_stream_read_until_finish (GDataInputStream *stream,
                                       GAsyncResult *result,
                                       gsize *length,
                                       GError **error);

g_data_input_stream_read_until_finish has been deprecated since version 2.56 and should not be used in newly-written code.

Use g_data_input_stream_read_upto_finish() instead, which has more consistent behaviour regarding the stop character.

Finish an asynchronous call started by g_data_input_stream_read_until_async().

Parameters

stream	a given GDataInputStream.
result	the GAsyncResult that was provided to the callback.
length	a gsize to get the length of the data read in.	[out][optional]
error	GError for error reporting.

Returns

a string with the data that was read before encountering any of the stop characters. Set length to a gsize to get the length of the string. This function will return NULL on an error.

[transfer full]

Since: 2.20

Types and Values

GDataInputStream

typedef struct _GDataInputStream GDataInputStream;

An implementation of GBufferedInputStream that allows for high-level data manipulation of arbitrary data (including binary operations).

enum GDataStreamByteOrder

GDataStreamByteOrder is used to ensure proper endianness of streaming data sources across various machine architectures.

Members

G_DATA_STREAM_BYTE_ORDER_BIG_ENDIAN	Selects Big Endian byte order.
G_DATA_STREAM_BYTE_ORDER_LITTLE_ENDIAN	Selects Little Endian byte order.
G_DATA_STREAM_BYTE_ORDER_HOST_ENDIAN	Selects endianness based on host machine's architecture.

enum GDataStreamNewlineType

GDataStreamNewlineType is used when checking for or setting the line endings for a given file.

Members

G_DATA_STREAM_NEWLINE_TYPE_LF	Selects "LF" line endings, common on most modern UNIX platforms.
G_DATA_STREAM_NEWLINE_TYPE_CR	Selects "CR" line endings.
G_DATA_STREAM_NEWLINE_TYPE_CR_LF	Selects "CR, LF" line ending, common on Microsoft Windows.
G_DATA_STREAM_NEWLINE_TYPE_ANY	Automatically try to handle any line ending type.

Property Details

The `“byte-order”` property

  “byte-order”               GDataStreamByteOrder

The :byte-order property determines the byte ordering that is used when reading multi-byte entities (such as integers) from the stream.

Owner: GDataInputStream

Flags: Read / Write

Default value: G_DATA_STREAM_BYTE_ORDER_BIG_ENDIAN

The `“newline-type”` property

  “newline-type”             GDataStreamNewlineType

The :newline-type property determines what is considered as a line ending when reading complete lines from the stream.

Owner: GDataInputStream

Flags: Read / Write

Default value: G_DATA_STREAM_NEWLINE_TYPE_LF