Method

GLibIOChannelset_encoding

Declaration

GIOStatus
g_io_channel_set_encoding (
  GIOChannel* channel,
  const gchar* encoding,
  GError** error
)

Description

Sets the encoding for the input/output of the channel. The internal encoding is always UTF-8. The default encoding for the external file is UTF-8.

The encoding NULL is safe to use with binary data.

The encoding can only be set if one of the following conditions is true:

  • The channel was just created, and has not been written to or read from yet.

  • The channel is write-only.

  • The channel is a file, and the file pointer was just repositioned by a call to g_io_channel_seek_position(). (This flushes all the internal buffers.)

  • The current encoding is NULL or UTF-8.

  • One of the (new API) read functions has just returned G_IO_STATUS_EOF (or, in the case of g_io_channel_read_to_end(), G_IO_STATUS_NORMAL).

  • One of the functions g_io_channel_read_chars() or g_io_channel_read_unichar() has returned G_IO_STATUS_AGAIN or G_IO_STATUS_ERROR. This may be useful in the case of G_CONVERT_ERROR_ILLEGAL_SEQUENCE. Returning one of these statuses from g_io_channel_read_line(), g_io_channel_read_line_string(), or g_io_channel_read_to_end() does not guarantee that the encoding can be changed.

Channels which do not meet one of the above conditions cannot call g_io_channel_seek_position() with an offset of G_SEEK_CUR, and, if they are “seekable”, cannot call g_io_channel_write_chars() after calling one of the API “read” functions.

Parameters

encoding

Type: const gchar*

The encoding type.

The argument can be NULL.
The data is owned by the caller of the method.
The value is a NUL terminated UTF-8 string.
error

Type: GError **

The return location for a recoverable error.

The argument can be NULL.
If the return location is not NULL, then you must initialize it to a NULL GError*.
The argument will left initialized to NULL by the method if there are no errors.
In case of error, the argument will be set to a newly allocated GError; the caller will take ownership of the data, and be responsible for freeing it.

Return value

Type: GIOStatus

G_IO_STATUS_NORMAL if the encoding was successfully set.