Top |
Functions
Properties
GDataStreamByteOrder | byte-order | Read / Write |
GDataStreamNewlineType | newline-type | Read / Write |
Object Hierarchy
GObject ╰── GInputStream ╰── GFilterInputStream ╰── GBufferedInputStream ╰── GDataInputStream
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
.
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
.
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.
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.
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
.
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, |
[nullable] |
error |
GError for error reporting. |
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, |
[nullable] |
error |
GError for error reporting. |
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, |
[nullable] |
error |
GError for error reporting. |
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, |
[nullable] |
error |
GError for error reporting. |
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()
.
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, |
[nullable] |
error |
GError for error reporting. |
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()
.
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, |
[nullable] |
error |
GError for error reporting. |
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()
.
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, |
[nullable] |
error |
GError for error reporting. |
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.
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. |
|
length |
a gsize to get the length of the data read in. |
[out][optional] |
cancellable |
optional GCancellable object, |
[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.
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. |
|
length |
a gsize to get the length of the data read in. |
[out][optional] |
cancellable |
optional GCancellable object, |
[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, |
[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 |
||
stop_chars |
characters to terminate the read |
|
stop_chars_len |
length of |
|
length |
a gsize to get the length of the data read in. |
[out][optional] |
cancellable |
optional GCancellable object, |
[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.
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.
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 |
||
stop_chars |
characters to terminate the read |
|
stop_chars_len |
length of |
|
io_priority |
the I/O priority of the request |
|
cancellable |
optional GCancellable object, |
[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 |
||
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, |
[nullable] |
error |
GError for error reporting. |
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, |
[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.
enum GDataStreamNewlineType
GDataStreamNewlineType is used when checking for or setting the line endings for a given file.
Property Details
The “byte-order”
property
“byte-order” GDataStreamByteOrder
The byte order.
Flags: Read / Write
Default value: G_DATA_STREAM_BYTE_ORDER_BIG_ENDIAN
The “newline-type”
property
“newline-type” GDataStreamNewlineType
The accepted types of line ending.
Flags: Read / Write
Default value: G_DATA_STREAM_NEWLINE_TYPE_LF