GIOChannel

typedef struct {
} GIOChannel;

Структура данных представляющая IO Channel (канал ввода-вывода). Поля этой структуры должны рассматриваться как закрытые и могут использоваться только следующими функциями.

g_io_channel_unix_new ()

GIOChannel* g_io_channel_unix_new           (int fd);

Создаёт новую GIOChannel полученного дескриптора файла. В UNIX системах это работает для простых файлов, каналов и сокетов.

Возвращаемая GIOChannel имеет количество ссылок равное 1.

Кодировкой по умолчанию для GIOChannel является UTF-8. Если ваша программа читает вывод из команд используя via pipe, вам может понадобиться установить кодировку в текущую кодировку локали (смотрите g_get_charset()) с помощью функции g_io_channel_set_encoding().

Если вы хотите читать исходные двоичные данные без интерпретации, то вызовите g_io_channel_set_encoding() функцию с параметром кодировки равным NULL.

Эта функция GLib доступна также в Windows, но вы должны избегать использования её в Windows. Область дескрипторов файла и сокетов перекрывается. Здесь нет способа для GLib узнать что вы подразумеваете в случае помещения в качестве аргументов в эту функцию и правильного дескриптора файла и сокета. Если это происходит то выдаётся предупреждение, а GLib предполагает что это дескриптор файла который вы подразумевали.

g_io_channel_unix_get_fd ()

gint        g_io_channel_unix_get_fd        (GIOChannel *channel);

Возвращает дескриптор файла GIOChannel.

В Windows эта функция вернёт дескриптор файла или сокет GIOChannel.

g_io_channel_win32_new_fd ()

GIOChannel* g_io_channel_win32_new_fd       (gint fd);

Создаёт новую GIOChannel получая дескриптор файла в Windows. Работает для дескрипторов файлов из C runtime.

Эта функция работает для дескрипторов файлов которые возвращают open(), creat(), pipe() и fileno() вызовы в Microsoft C runtime. Для обоснованного использования этой функции ваш код должен использовать туже C runtime которую использует GLib, которой является msvcrt.dll. Помните что текущий компилятор Microsoft не подходит для сборки кода который использует msvcrt.dll. Последняя версия компилятора Microsoft которая поддерживала использование msvcrt.dll как C runtime была версия 6. Компилятор GNU и инструменты для Windows, также известные как Mingw, полностью поддерживают msvcrt.dll.

Если вы создали GIOChannel для дескриптора файла и запустили её просмотр (опрос), вы не должны вызывать read() для дескриптора файла. Это потому, что добавление опроса для дескриптора файла реализовано в GLib на платформе Windows с помощью запуска потока который остаётся блокированным в read() из дескриптора файла больше времени. Все читатели дескриптора файла должны быть выполнены этим внутренним потоком GLib. Ваш код должен вызывать только g_io_channel_read().

Эта функция доступна только в GLib для Windows.

g_io_channel_win32_new_socket ()

GIOChannel* g_io_channel_win32_new_socket   (gint socket);

Создаёт новую GIOChannel получая сокет в Windows.

Эта функция работает для сокетов созданных при помощи Winsock. Она доступна только в GLib для Windows.

Опрос GSource создаёт канал просмотра для сокета помещая сокет в не блокированный режим. Это неизбежный побочный эффект реализации.

g_io_channel_win32_new_messages ()

GIOChannel* g_io_channel_win32_new_messages (guint hwnd);

Создаёт новую GIOChannel получая обработку окна в Windows.

Эта функция создаёт GIOChannel которая может использоваться для опроса сообщений Windows запрашиваемого окна.

g_io_channel_init ()

void        g_io_channel_init               (GIOChannel *channel);

Инициализирует структуру GIOChannel. Вызывается каждой из вышеупомянутых функций когда создаётся GIOChannel, а также часто необходима для разработчиков приложений (если вы создаёте новый тип GIOChannel).

g_io_channel_new_file ()

GIOChannel* g_io_channel_new_file           (const gchar *filename,
                                             const gchar *mode,
                                             GError **error);

Открывает файл filename как GIOChannel используя режим mode. Этот канал будет закрыт при сбросе последней ссылки на него, поэтому нет необходимости вызывать g_io_channel_close() (такое выполнение не вызовет никаких проблем, пока не попытается обратиться к уже закрытому каналу).

g_io_channel_read_chars ()

GIOStatus   g_io_channel_read_chars         (GIOChannel *channel,
                                             gchar *buf,
                                             gsize count,
                                             gsize *bytes_read,
                                             GError **error);

Замена для g_io_channel_read() с новым API.

g_io_channel_read_unichar ()

GIOStatus   g_io_channel_read_unichar       (GIOChannel *channel,
                                             gunichar *thechar,
                                             GError **error);

Эта функция не может быть вызвана для канала с NULL кодировкой.

g_io_channel_read_line ()

GIOStatus   g_io_channel_read_line          (GIOChannel *channel,
                                             gchar **str_return,
                                             gsize *length,
                                             gsize *terminator_pos,
                                             GError **error);

Читает строку, включая завершающий символ(ы), из GIOChannel во вновь распределённой строке. str_return будет содержать распределённую память если возвращаемое значение G_IO_STATUS_NORMAL.

g_io_channel_read_line_string ()

GIOStatus   g_io_channel_read_line_string   (GIOChannel *channel,
                                             GString *buffer,
                                             gsize *terminator_pos,
                                             GError **error);

Читает строку из GIOChannel, используя GString как буфер.

g_io_channel_read_to_end ()

GIOStatus   g_io_channel_read_to_end        (GIOChannel *channel,
                                             gchar **str_return,
                                             gsize *length,
                                             GError **error);

Читает все оставшиеся данные из файла.

g_io_channel_write_chars ()

GIOStatus   g_io_channel_write_chars        (GIOChannel *channel,
                                             const gchar *buf,
                                             gssize count,
                                             gsize *bytes_written,
                                             GError **error);

Замена для g_io_channel_write() с новым API.

В seekable каналах с кодировкой отличающейся от NULL или UTF-8, смешивание чтения и записи недопустимо. Вызов g_io_channel_write_chars() может быть сделан только в канале из которого данные были прочитаны в случае описанном в документации для g_io_channel_set_encoding().

g_io_channel_write_unichar ()

GIOStatus   g_io_channel_write_unichar      (GIOChannel *channel,
                                             gunichar thechar,
                                             GError **error);

Эта функция не должна вызываться в канале с NULL кодировкой.

g_io_channel_flush ()

GIOStatus   g_io_channel_flush              (GIOChannel *channel,
                                             GError **error);

Синхронизирует данные буфера записанные в памяти и на диске для GIOChannel.

g_io_channel_seek_position ()

GIOStatus   g_io_channel_seek_position      (GIOChannel *channel,
                                             gint64 offset,
                                             GSeekType type,
                                             GError **error);

Замена для g_io_channel_seek() с новым API.

enum GSeekType

typedef enum
{
  G_SEEK_CUR,
  G_SEEK_SET,
  G_SEEK_END
} GSeekType;

Перечисление определяющее начальную позицию для g_io_channel_seek_position() операции.

g_io_channel_shutdown ()

GIOStatus   g_io_channel_shutdown           (GIOChannel *channel,
                                             gboolean flush,
                                             GError **err);

Закрывает IO канал. Любые данные ждущие обработки будут записаны на диск если параметр flush равен TRUE. Канал не освобождается пока последняя ссылка не сброшена с помощью g_io_channel_unref().

enum GIOStatus

typedef enum
{
  G_IO_STATUS_ERROR,
  G_IO_STATUS_NORMAL,
  G_IO_STATUS_EOF,
  G_IO_STATUS_AGAIN
} GIOStatus;

Статусы возвращаемые большинством GIOFuncs функций.

enum GIOChannelError

typedef enum
{
  /* Derived from errno */
  G_IO_CHANNEL_ERROR_FBIG,
  G_IO_CHANNEL_ERROR_INVAL,
  G_IO_CHANNEL_ERROR_IO,
  G_IO_CHANNEL_ERROR_ISDIR,
  G_IO_CHANNEL_ERROR_NOSPC,
  G_IO_CHANNEL_ERROR_NXIO,
  G_IO_CHANNEL_ERROR_OVERFLOW,
  G_IO_CHANNEL_ERROR_PIPE,
  /* Other */
  G_IO_CHANNEL_ERROR_FAILED
} GIOChannelError;

Коды ошибок возвращаемые GIOChannel операциями.

G_IO_CHANNEL_ERROR

#define G_IO_CHANNEL_ERROR g_io_channel_error_quark()

Ошибочная область для GIOChannel операций. Ошибки в этой области будут из GIOChannelError перечисления. Смотрите GError для информации об ошибочных областях.

g_io_channel_error_from_errno ()

GIOChannelError g_io_channel_error_from_errno
                                            (gint en);

Конвертирует номер ошибки errno в GIOChannelError.

g_io_channel_ref ()

GIOChannel* g_io_channel_ref                (GIOChannel *channel);

Увеличивает количество ссылок GIOChannel.

g_io_channel_unref ()

void        g_io_channel_unref              (GIOChannel *channel);

Уменьшает количество ссылок GIOChannel.

g_io_create_watch ()

GSource*    g_io_create_watch               (GIOChannel *channel,
                                             GIOCondition condition);

Создаёт GSource которая отправляется когда встретилось condition для данного channel. Например, если условие G_IO_IN, источник будет отправлен когда появятся данные доступные для чтения. g_io_add_watch() - это более простой интерфейс для тех же самых функциональных возможностей, в случае когда вы хотите добавить в основной цикл по умолчанию приоритет по умолчанию.

В Windows, опрос GSource создаётся для просматриваемого канала для сокета, помещая сокет в деблокированный режим. Этот побочный эффект реализации неизбежен.

g_io_add_watch ()

guint       g_io_add_watch                  (GIOChannel *channel,
                                             GIOCondition condition,
                                             GIOFunc func,
                                             gpointer user_data);

Добавляет GIOChannel в основной цикл собития с приоритетом по умолчанию.

g_io_add_watch_full ()

guint       g_io_add_watch_full             (GIOChannel *channel,
                                             gint priority,
                                             GIOCondition condition,
                                             GIOFunc func,
                                             gpointer user_data,
                                             GDestroyNotify notify);

Добавляет GIOChannel в основной цикл события с полученным приоритетом.

enum GIOCondition

typedef enum
{
  G_IO_IN	GLIB_SYSDEF_POLLIN,
  G_IO_OUT	GLIB_SYSDEF_POLLOUT,
  G_IO_PRI	GLIB_SYSDEF_POLLPRI,
  G_IO_ERR	GLIB_SYSDEF_POLLERR,
  G_IO_HUP	GLIB_SYSDEF_POLLHUP,
  G_IO_NVAL	GLIB_SYSDEF_POLLNVAL
} GIOCondition;

Побитовые комбинации представляющие рассматриваемые условия для источника события.

GIOFunc ()

gboolean    (*GIOFunc)                      (GIOChannel *source,
                                             GIOCondition condition,
                                             gpointer data);

Определяет тип функции помещаемой в g_io_add_watch() или g_io_add_watch_full(), которая вызывается когда запрашиваемое условие в GIOChannel удовлетворено.

GIOFuncs

typedef struct {
  GIOStatus (*io_read)           (GIOChannel   *channel, 
			          gchar        *buf, 
				  gsize         count,
				  gsize        *bytes_read,
				  GError      **err);
  GIOStatus (*io_write)          (GIOChannel   *channel, 
				  const gchar  *buf, 
				  gsize         count,
				  gsize        *bytes_written,
				  GError      **err);
  GIOStatus (*io_seek)           (GIOChannel   *channel, 
				  gint64        offset, 
				  GSeekType     type,
				  GError      **err);
  GIOStatus  (*io_close)         (GIOChannel   *channel,
				  GError      **err);
  GSource*   (*io_create_watch)  (GIOChannel   *channel,
				  GIOCondition  condition);
  void       (*io_free)          (GIOChannel   *channel);
  GIOStatus  (*io_set_flags)     (GIOChannel   *channel,
                                  GIOFlags      flags,
				  GError      **err);
  GIOFlags   (*io_get_flags)     (GIOChannel   *channel);
} GIOFuncs;

Таблица функций используемых для обработки разных типов GIOChannel обычным способом.

g_io_channel_get_buffer_size ()

gsize       g_io_channel_get_buffer_size    (GIOChannel *channel);

Получает размер буфера.

g_io_channel_set_buffer_size ()

void        g_io_channel_set_buffer_size    (GIOChannel *channel,
                                             gsize size);

Устанавливает размер буфера.

g_io_channel_get_buffer_condition ()

GIOCondition g_io_channel_get_buffer_condition
                                            (GIOChannel *channel);

Эта функция возвращает GIOCondition в зависимости от того, есть ли данные для чтения или свободное пространство для записи данных во внутренние буферы GIOChannel. Могут устанавливаться только флаги G_IO_IN и G_IO_OUT.

g_io_channel_get_flags ()

GIOFlags    g_io_channel_get_flags          (GIOChannel *channel);

Получает текущие флаги для GIOChannel, включая флаги только для чтения такие как G_IO_FLAG_IS_READABLE.

Значения флажков G_IO_FLAG_IS_READABLE и G_IO_FLAG_IS_WRITEABLE кэшируются для внутреннего использования каналом при его создании. Если они позже должны измениться (например частичное завершение сокета с помощью UNIX функции shutdown()), пользователь должен немедленно вызвать g_io_channel_get_flags() для обновления внутренних значений этих флажков.

g_io_channel_set_flags ()

GIOStatus   g_io_channel_set_flags          (GIOChannel *channel,
                                             GIOFlags flags,
                                             GError **error);

Устанавливает (записываемые) флаги в channel (flags & G_IO_CHANNEL_SET_MASK).

enum GIOFlags

typedef enum
{
  G_IO_FLAG_APPEND = 1 << 0,
  G_IO_FLAG_NONBLOCK = 1 << 1,
  G_IO_FLAG_IS_READABLE = 1 << 2,	/* флаг доступный только для чтения */
  G_IO_FLAG_IS_WRITEABLE = 1 << 3,	/* флаг доступный только для чтения */
  G_IO_FLAG_IS_SEEKABLE = 1 << 4,	/* флаг доступный только для чтения */
  G_IO_FLAG_MASK = (1 << 5) - 1,
  G_IO_FLAG_GET_MASK = G_IO_FLAG_MASK,
  G_IO_FLAG_SET_MASK = G_IO_FLAG_APPEND | G_IO_FLAG_NONBLOCK
} GIOFlags;

Определяет свойства GIOChannel. Некоторые флаги можно только читать с помощью g_io_channel_get_flags(), но нельзя изменять с помощью g_io_channel_set_flags().

g_io_channel_get_line_term ()

const gchar* g_io_channel_get_line_term     (GIOChannel *channel,
                                             gint *length);

Возвращает строку которую GIOChannel использует для определения где в файле происходит прерывание линии. Значение NULL указывает автоматическое определение.

g_io_channel_set_line_term ()

void        g_io_channel_set_line_term      (GIOChannel *channel,
                                             const gchar *line_term,
                                             gint length);

Устанавливает строку которую GIOChannel использует для определения где в файле происходит прерывание линии.

g_io_channel_get_buffered ()

gboolean    g_io_channel_get_buffered       (GIOChannel *channel);

Определяет буферизуется ли channel.

g_io_channel_set_buffered ()

void        g_io_channel_set_buffered       (GIOChannel *channel,
                                             gboolean buffered);

Состояние буферизации может быть установлено только если кодировка канала NULL. Для любых других кодировок, канал должен буферизироваться.

Буферизированный канал может быть установлен не буферизированным только если внутренние буферы канала были записаны на диск. Вновь созданные каналы или каналы вернувшие G_IO_STATUS_EOF не требуют производить такую запись. Для каналов только для записи, вызов g_io_channel_flush() достаточен. Для всех других каналов, буфер может быть синхронизирован с диском с помощью вызова g_io_channel_seek_position(). Это включает возможность перемещения позиции типа G_SEEK_CUR и нулевое смещение. Отметьте, это значит что каналы на основе сокетов не могут быть установлены не буферизированными как только из них начнётся чтение данных.

В небуферизованных каналах, безопасно смешивать вызовы чтения и записи из новых и старых APIs, если это необходимо для поддержки старого кода.

По умолчанию канал имеет буферизованное состояние.

g_io_channel_get_encoding ()

const gchar* g_io_channel_get_encoding      (GIOChannel *channel);

Получает кодировку для ввода/вывода канала. Внутренняя кодировка всегда UTF-8. Кодировка NULL делает канал безопасным для двоичных данных.

g_io_channel_set_encoding ()

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

Устанавливает кодировку для ввода/вывода канала. Внутренняя кодировка всегда UTF-8. Кодировка по умолчанию для внешних файлов UTF-8.

Кодировка NULL безопасна для использования двоичных данных.

Кодировка может быть установлена только если выполняются следующие условия:

1. Канал был только что создан и операции чтения или записи не проводились.

2. Канал только для записи.

3. Канал это файл, а указатель файла был только что установлен с помощью вызова g_io_channel_seek_position(). (Это записывает все внутренние буферы на диск.)

4. Текущая кодировка NULL или UTF-8.

5. Одна из функций (новый API) чтения возвратила G_IO_STATUS_EOF (или, в случае g_io_channel_read_to_end(), G_IO_STATUS_NORMAL).

6. Одна из функций g_io_channel_read_chars() или g_io_channel_read_unichar() вернула G_IO_STATUS_AGAIN или G_IO_STATUS_ERROR. Это может быть полезно в случае G_CONVERT_ERROR_ILLEGAL_SEQUENCE. Возвращение одного из этих статусов из g_io_channel_read_line(), g_io_channel_read_line_string(), или g_io_channel_read_to_end() не гарантирует что кодировка может быть изменена.

Каналы которые не соответствуют одному из выше упомянутых условий не могут вызывать g_io_channel_seek_position() со смещением G_SEEK_CUR, и если они "seekable", не могут вызывать g_io_channel_write_chars() после вызова одной из функций API "read".

g_io_channel_get_close_on_unref ()

gboolean    g_io_channel_get_close_on_unref (GIOChannel *channel);

Определяет будет ли закрыт любой файл/сокет связанный с каналом channel когда channel будет разрушен при удалении последней ссылки на него. По умолчанию значение TRUE для каналов созданных с помощью g_io_channel_new_file(), а FALSE для всех других каналов.

g_io_channel_set_close_on_unref ()

void        g_io_channel_set_close_on_unref (GIOChannel *channel,
                                             gboolean do_close);

Установка этого флажка в TRUE для канала который уже закрыт может вызвать проблемы.

g_io_channel_read ()

GIOError    g_io_channel_read               (GIOChannel *channel,
                                             gchar *buf,
                                             gsize count,
                                             gsize *bytes_read);

Читает данные из GIOChannel.

enum GIOError

typedef enum
{
  G_IO_ERROR_NONE,
  G_IO_ERROR_AGAIN,
  G_IO_ERROR_INVAL,
  G_IO_ERROR_UNKNOWN
} GIOError;

GIOError используется только устаревшими функциями g_io_channel_read(), g_io_channel_write(), и g_io_channel_seek().

g_io_channel_write ()

GIOError    g_io_channel_write              (GIOChannel *channel,
                                             const gchar *buf,
                                             gsize count,
                                             gsize *bytes_written);

Записывает данные в GIOChannel.

g_io_channel_seek ()

GIOError    g_io_channel_seek               (GIOChannel *channel,
                                             gint64 offset,
                                             GSeekType type);

Устанавливает текущую позицию в GIOChannel, подобна стандартной библиотечной функции fseek().

g_io_channel_close ()

void        g_io_channel_close              (GIOChannel *channel);

Закрывает IO канал. Любые данные ожидающие обработки записываются на диск, игнорируя ошибки. Канал не будет освобождён пока не сброшена последняя ссылка с помощью g_io_channel_unref().