Gio.DataInputStream¶

Subclasses:: None

Methods¶

Inherited:: Gio.BufferedInputStream (11), Gio.FilterInputStream (3), Gio.InputStream (19), GObject.Object (37), Gio.Seekable (5)
Structs:: GObject.ObjectClass (5)

class	`new` (base_stream)
	`get_byte_order` ()
	`get_newline_type` ()
	`read_byte` (cancellable)
	`read_int16` (cancellable)
	`read_int32` (cancellable)
	`read_int64` (cancellable)
	`read_line` (cancellable)
	`read_line_async` (io_priority, cancellable, callback, *user_data)
	`read_line_finish` (result)
	`read_line_finish_utf8` (result)
	`read_line_utf8` (cancellable)
	`read_uint16` (cancellable)
	`read_uint32` (cancellable)
	`read_uint64` (cancellable)
	`read_until` (stop_chars, cancellable)
	`read_until_async` (stop_chars, io_priority, cancellable, callback, *user_data)
	`read_until_finish` (result)
	`read_upto` (stop_chars, stop_chars_len, cancellable)
	`read_upto_async` (stop_chars, stop_chars_len, io_priority, cancellable, callback, *user_data)
	`read_upto_finish` (result)
	`set_byte_order` (order)
	`set_newline_type` (type)

Virtual Methods¶

Inherited:: Gio.BufferedInputStream (3), Gio.InputStream (9), GObject.Object (7), Gio.Seekable (5)

Properties¶

Inherited:: Gio.BufferedInputStream (1), Gio.FilterInputStream (2)

Name	Type	Flags	Short Description
`byte-order`	`Gio.DataStreamByteOrder`	r/w
`newline-type`	`Gio.DataStreamNewlineType`	r/w

Signals¶

Inherited:: GObject.Object (1)

Fields¶

Inherited:: GObject.Object (1)

Name	Type	Access	Description
parent_instance	`Gio.BufferedInputStream`	r

Class Details¶

class Gio.DataInputStream(**kwargs)¶

Bases:: Gio.BufferedInputStream
Abstract:: No
Structure:: Gio.DataInputStreamClass

Data input stream implements [class`Gio`.InputStream] and includes functions for reading structured data directly from a binary input stream.

classmethod new(base_stream)[source]¶

Parameters:: base_stream (Gio.InputStream) – a Gio.InputStream.
Returns:: a new Gio.DataInputStream.
Return type:: Gio.DataInputStream

Creates a new data input stream for the base_stream.

get_byte_order()[source]¶

Returns:: the self's current Gio.DataStreamByteOrder.
Return type:: Gio.DataStreamByteOrder

Gets the byte order for the data input stream.

get_newline_type()[source]¶

Returns:: Gio.DataStreamNewlineType for the given self.
Return type:: Gio.DataStreamNewlineType

Gets the current newline type for the self.

read_byte(cancellable)[source]¶

Parameters:: cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, None to ignore.
Raises:: GLib.Error
Returns:: an unsigned 8-bit/1-byte value read from the self or 0 if an error occurred.
Return type:: int

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

read_int16(cancellable)[source]¶

Parameters:: cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, None to ignore.
Raises:: GLib.Error
Returns:: a signed 16-bit/2-byte value read from self or 0 if an error occurred.
Return type:: int

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

In order to get the correct byte order for this read operation, see Gio.DataInputStream.get_byte_order() and Gio.DataInputStream.set_byte_order().

read_int32(cancellable)[source]¶

Parameters:: cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, None to ignore.
Raises:: GLib.Error
Returns:: a signed 32-bit/4-byte value read from the self or 0 if an error occurred.
Return type:: int

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

In order to get the correct byte order for this read operation, see Gio.DataInputStream.get_byte_order() and Gio.DataInputStream.set_byte_order().

If cancellable is not None, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error Gio.IOErrorEnum.CANCELLED will be returned.

read_int64(cancellable)[source]¶

Parameters:: cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, None to ignore.
Raises:: GLib.Error
Returns:: a signed 64-bit/8-byte value read from self or 0 if an error occurred.
Return type:: int

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

In order to get the correct byte order for this read operation, see Gio.DataInputStream.get_byte_order() and Gio.DataInputStream.set_byte_order().

If cancellable is not None, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error Gio.IOErrorEnum.CANCELLED will be returned.

read_line(cancellable)[source]¶

Parameters:

cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, None to ignore.

Raises:

GLib.Error

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 None and error will be set. If there’s no content to read, it will still return None, but error won’t be set.

length:: a #gsize to get the length of the data read in.

Return type:

(bytes or None, length: int)

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 None, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error Gio.IOErrorEnum.CANCELLED will be returned.

read_line_async(io_priority, cancellable, callback, *user_data)[source]¶

Parameters:

io_priority (int) – the I/O priority of the request
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, None to ignore.
callback (Gio.AsyncReadyCallback or None) – callback to call when the request is satisfied.
user_data (object or None) – the data to pass to callback function.

The asynchronous version of Gio.DataInputStream.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 Gio.DataInputStream.read_line_finish() to get the result of the operation.

New in version 2.20.

read_line_finish(result)[source]¶

Parameters:

result (Gio.AsyncResult) – the Gio.AsyncResult that was provided to the callback.

Raises:

GLib.Error

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 None and error will be set. If there’s no content to read, it will still return None, but error won’t be set.

length:: a #gsize to get the length of the data read in.

Return type:

(bytes or None, length: int)

Finish an asynchronous call started by Gio.DataInputStream.read_line_async(). Note the warning about string encoding in Gio.DataInputStream.read_line() applies here as well.

New in version 2.20.

read_line_finish_utf8(result)[source]¶

Parameters:

result (Gio.AsyncResult) – the Gio.AsyncResult that was provided to the callback.

Raises:

GLib.Error

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 None 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 None, but error won’t be set.

length:: a #gsize to get the length of the data read in.

Return type:

(str or None, length: int)

Finish an asynchronous call started by Gio.DataInputStream.read_line_async().

New in version 2.30.

read_line_utf8(cancellable)[source]¶

Parameters:

cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, None to ignore.

Raises:

GLib.Error

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 None 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 None, but error won’t be set.

length:: a #gsize to get the length of the data read in.

Return type:

(str or None, length: int)

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

If cancellable is not None, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error Gio.IOErrorEnum.CANCELLED will be returned.

New in version 2.30.

read_uint16(cancellable)[source]¶

Parameters:: cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, None to ignore.
Raises:: GLib.Error
Returns:: an unsigned 16-bit/2-byte value read from the self or 0 if an error occurred.
Return type:: int

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

In order to get the correct byte order for this read operation, see Gio.DataInputStream.get_byte_order() and Gio.DataInputStream.set_byte_order().

read_uint32(cancellable)[source]¶

Parameters:: cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, None to ignore.
Raises:: GLib.Error
Returns:: an unsigned 32-bit/4-byte value read from the self or 0 if an error occurred.
Return type:: int

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

In order to get the correct byte order for this read operation, see Gio.DataInputStream.get_byte_order() and Gio.DataInputStream.set_byte_order().

If cancellable is not None, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error Gio.IOErrorEnum.CANCELLED will be returned.

read_uint64(cancellable)[source]¶

Parameters:: cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, None to ignore.
Raises:: GLib.Error
Returns:: an unsigned 64-bit/8-byte read from self or 0 if an error occurred.
Return type:: int

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

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

If cancellable is not None, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error Gio.IOErrorEnum.CANCELLED will be returned.

read_until(stop_chars, cancellable)[source]¶

Parameters:

stop_chars (str) – characters to terminate the read.
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, None to ignore.

Raises:

GLib.Error

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 None on an error.

length:: a #gsize to get the length of the data read in.

Return type:

(str, length: int)

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

Note that, in contrast to Gio.DataInputStream.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 Gio.DataInputStream.read_until_async(). Both functions will be marked as deprecated in a future release. Use Gio.DataInputStream.read_upto() instead, but note that that function does not consume the stop character.

Deprecated since version 2.56: Use Gio.DataInputStream.read_upto() instead, which has more consistent behaviour regarding the stop character.

read_until_async(stop_chars, io_priority, cancellable, callback, *user_data)[source]¶

Parameters:

stop_chars (str) – characters to terminate the read.
io_priority (int) – the I/O priority of the request
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, None to ignore.
callback (Gio.AsyncReadyCallback or None) – callback to call when the request is satisfied.
user_data (object or None) – the data to pass to callback function.

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

Note that, in contrast to Gio.DataInputStream.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 Gio.DataInputStream.read_until_finish() to get the result of the operation.

Don’t use this function in new code. Its functionality is inconsistent with Gio.DataInputStream.read_until(). Both functions will be marked as deprecated in a future release. Use Gio.DataInputStream.read_upto_async() instead.

New in version 2.20.

Deprecated since version 2.56: Use Gio.DataInputStream.read_upto_async() instead, which has more consistent behaviour regarding the stop character.

read_until_finish(result)[source]¶

Parameters:

result (Gio.AsyncResult) – the Gio.AsyncResult that was provided to the callback.

Raises:

GLib.Error

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 None on an error.

length:: a #gsize to get the length of the data read in.

Return type:

(str, length: int)

Finish an asynchronous call started by Gio.DataInputStream.read_until_async().

New in version 2.20.

Deprecated since version 2.56: Use Gio.DataInputStream.read_upto_finish() instead, which has more consistent behaviour regarding the stop character.

read_upto(stop_chars, stop_chars_len, cancellable)[source]¶

Parameters:

stop_chars (str) – characters to terminate the read
stop_chars_len (int) – length of stop_chars. May be -1 if stop_chars is nul-terminated
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, None to ignore

Raises:

GLib.Error

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 None on an error

length:: a #gsize to get the length of the data read in

Return type:

(str, length: int)

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

In contrast to Gio.DataInputStream.read_until(), this function does not consume the stop character. You have to use Gio.DataInputStream.read_byte() to get it before calling Gio.DataInputStream.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.

New in version 2.26.

read_upto_async(stop_chars, stop_chars_len, io_priority, cancellable, callback, *user_data)[source]¶

Parameters:

stop_chars (str) – characters to terminate the read
stop_chars_len (int) – length of stop_chars. May be -1 if stop_chars is nul-terminated
io_priority (int) – the I/O priority of the request
cancellable (Gio.Cancellable or None) – optional Gio.Cancellable object, None to ignore
callback (Gio.AsyncReadyCallback or None) – callback to call when the request is satisfied
user_data (object or None) – the data to pass to callback function

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

In contrast to Gio.DataInputStream.read_until(), this function does not consume the stop character. You have to use Gio.DataInputStream.read_byte() to get it before calling Gio.DataInputStream.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 Gio.DataInputStream.read_upto_finish() to get the result of the operation.

New in version 2.26.

read_upto_finish(result)[source]¶

Parameters:

result (Gio.AsyncResult) – the Gio.AsyncResult that was provided to the callback

Raises:

GLib.Error

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 None on an error.

length:: a #gsize to get the length of the data read in

Return type:

(str, length: int)

Finish an asynchronous call started by Gio.DataInputStream.read_upto_async().

Note that this function does not consume the stop character. You have to use Gio.DataInputStream.read_byte() to get it before calling Gio.DataInputStream.read_upto_async() again.

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

New in version 2.24.

set_byte_order(order)[source]¶

Parameters:: order (Gio.DataStreamByteOrder) – a Gio.DataStreamByteOrder to set.

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

set_newline_type(type)[source]¶

Parameters:: type (Gio.DataStreamNewlineType) – the type of new line return as Gio.DataStreamNewlineType.

Sets the newline type for the self.

Note that using Gio.DataStreamNewlineType.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.

Property Details¶

Gio.DataInputStream.props.byte_order¶

Name:: byte-order
Type:: Gio.DataStreamByteOrder
Default Value:: Gio.DataStreamByteOrder.BIG_ENDIAN
Flags:: READABLE, WRITABLE

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

Gio.DataInputStream.props.newline_type¶

Name:: newline-type
Type:: Gio.DataStreamNewlineType
Default Value:: Gio.DataStreamNewlineType.LF
Flags:: READABLE, WRITABLE

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