Gio.DataInputStream

g GObject.GInterface GObject.GInterface Gio.Seekable Gio.Seekable GObject.GInterface->Gio.Seekable GObject.Object GObject.Object Gio.InputStream Gio.InputStream GObject.Object->Gio.InputStream Gio.BufferedInputStream Gio.BufferedInputStream Gio.DataInputStream Gio.DataInputStream Gio.BufferedInputStream->Gio.DataInputStream Gio.FilterInputStream Gio.FilterInputStream Gio.FilterInputStream->Gio.BufferedInputStream Gio.InputStream->Gio.FilterInputStream Gio.Seekable->Gio.BufferedInputStream

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

The byte order

newline-type

Gio.DataStreamNewlineType

r/w

The accepted types of line ending

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 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:

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:
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:

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:

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.