The OpenNET Project / Index page

[ новости /+++ | форум | wiki | теги | ]

Каталог документации / Раздел "Программирование, языки" / Оглавление документа

IO Channels

IO Channels — Переносимая поддержка использования файлов, каналов и сокетов.

Краткое описание


#include <glib.h>


            GIOChannel;

GIOChannel* g_io_channel_unix_new           (int fd);
gint        g_io_channel_unix_get_fd        (GIOChannel *channel);
GIOChannel* g_io_channel_win32_new_fd       (gint fd);
GIOChannel* g_io_channel_win32_new_socket   (gint socket);
GIOChannel* g_io_channel_win32_new_messages (guint hwnd);

void        g_io_channel_init               (GIOChannel *channel);

GIOChannel* g_io_channel_new_file           (const gchar *filename,
                                             const gchar *mode,
                                             GError **error);
GIOStatus   g_io_channel_read_chars         (GIOChannel *channel,
                                             gchar *buf,
                                             gsize count,
                                             gsize *bytes_read,
                                             GError **error);
GIOStatus   g_io_channel_read_unichar       (GIOChannel *channel,
                                             gunichar *thechar,
                                             GError **error);
GIOStatus   g_io_channel_read_line          (GIOChannel *channel,
                                             gchar **str_return,
                                             gsize *length,
                                             gsize *terminator_pos,
                                             GError **error);
GIOStatus   g_io_channel_read_line_string   (GIOChannel *channel,
                                             GString *buffer,
                                             gsize *terminator_pos,
                                             GError **error);
GIOStatus   g_io_channel_read_to_end        (GIOChannel *channel,
                                             gchar **str_return,
                                             gsize *length,
                                             GError **error);
GIOStatus   g_io_channel_write_chars        (GIOChannel *channel,
                                             const gchar *buf,
                                             gssize count,
                                             gsize *bytes_written,
                                             GError **error);
GIOStatus   g_io_channel_write_unichar      (GIOChannel *channel,
                                             gunichar thechar,
                                             GError **error);
GIOStatus   g_io_channel_flush              (GIOChannel *channel,
                                             GError **error);
GIOStatus   g_io_channel_seek_position      (GIOChannel *channel,
                                             gint64 offset,
                                             GSeekType type,
                                             GError **error);
enum        GSeekType;
GIOStatus   g_io_channel_shutdown           (GIOChannel *channel,
                                             gboolean flush,
                                             GError **err);

enum        GIOStatus;
enum        GIOChannelError;
#define     G_IO_CHANNEL_ERROR
GIOChannelError g_io_channel_error_from_errno
                                            (gint en);

GIOChannel* g_io_channel_ref                (GIOChannel *channel);
void        g_io_channel_unref              (GIOChannel *channel);

GSource*    g_io_create_watch               (GIOChannel *channel,
                                             GIOCondition condition);
guint       g_io_add_watch                  (GIOChannel *channel,
                                             GIOCondition condition,
                                             GIOFunc func,
                                             gpointer user_data);
guint       g_io_add_watch_full             (GIOChannel *channel,
                                             gint priority,
                                             GIOCondition condition,
                                             GIOFunc func,
                                             gpointer user_data,
                                             GDestroyNotify notify);
enum        GIOCondition;
gboolean    (*GIOFunc)                      (GIOChannel *source,
                                             GIOCondition condition,
                                             gpointer data);

            GIOFuncs;

gsize       g_io_channel_get_buffer_size    (GIOChannel *channel);
void        g_io_channel_set_buffer_size    (GIOChannel *channel,
                                             gsize size);
GIOCondition g_io_channel_get_buffer_condition
                                            (GIOChannel *channel);
GIOFlags    g_io_channel_get_flags          (GIOChannel *channel);
GIOStatus   g_io_channel_set_flags          (GIOChannel *channel,
                                             GIOFlags flags,
                                             GError **error);
enum        GIOFlags;
const gchar* g_io_channel_get_line_term     (GIOChannel *channel,
                                             gint *length);
void        g_io_channel_set_line_term      (GIOChannel *channel,
                                             const gchar *line_term,
                                             gint length);
gboolean    g_io_channel_get_buffered       (GIOChannel *channel);
void        g_io_channel_set_buffered       (GIOChannel *channel,
                                             gboolean buffered);
const gchar* g_io_channel_get_encoding      (GIOChannel *channel);
GIOStatus   g_io_channel_set_encoding       (GIOChannel *channel,
                                             const gchar *encoding,
                                             GError **error);
gboolean    g_io_channel_get_close_on_unref (GIOChannel *channel);
void        g_io_channel_set_close_on_unref (GIOChannel *channel,
                                             gboolean do_close);


GIOError    g_io_channel_read               (GIOChannel *channel,
                                             gchar *buf,
                                             gsize count,
                                             gsize *bytes_read);
enum        GIOError;
GIOError    g_io_channel_write              (GIOChannel *channel,
                                             const gchar *buf,
                                             gsize count,
                                             gsize *bytes_written);
GIOError    g_io_channel_seek               (GIOChannel *channel,
                                             gint64 offset,
                                             GSeekType type);
void        g_io_channel_close              (GIOChannel *channel);

Описание

Тип данных GIOChannel предназначен для обеспечения переносимого метода использования файловых дескрипторов, каналов и сокетов, интегрируя их в main event loop. В настоящий момент доступна полная поддержка на UNIX платформах, поддержка для Windows выполнена только частично.

Для создания новой GIOChannel в UNIX системах используйте g_io_channel_unix_new(). Это работает для простых дескрипторов файла, каналов и сокетов. Альтернативно, канал может быть создан для файла независимым от системы способом используя g_io_channel_new_file().

Как только GIOChannel создана, она может использоваться обычным способом в функциях g_io_channel_read_chars(), g_io_channel_write_chars(), g_io_channel_seek_position() и g_io_channel_shutdown().

Для добавления GIOChannel в основной цикл событий используйте g_io_add_watch() или g_io_add_watch_full(). Так определяется какие события вас интересуют в GIOChannel и обеспечивается функция которая будет вызываться каждый раз когда происходит это событие.

GIOChannel создаётся с начальным количеством ссылок равным 1. Функции g_io_channel_ref() и g_io_channel_unref() могут использоваться для увеличения и уменьшения количества ссылок соответственно. Когда количество ссылок достигло 0, GIOChannel освобождается (хотя она не закрывается автоматически, если не создана с использованием g_io_channel_new_from_file()). Использование g_io_add_watch() или g_io_add_watch_full() увеличивает количество ссылок каналов.

Новые функции g_io_channel_read_chars(), g_io_channel_read_line(), g_io_channel_read_line_string(), g_io_channel_read_to_end(), g_io_channel_write_chars(), g_io_channel_seek_position(), и g_io_channel_flush() не должны использоваться совместно с устаревшими функциями g_io_channel_read(), g_io_channel_write(), и g_io_channel_seek() в одном и том же канале.

Детали

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 предполагает что это дескриптор файла который вы подразумевали.

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

g_io_channel_unix_get_fd ()

gint        g_io_channel_unix_get_fd        (GIOChannel *channel);

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

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

channel : GIOChannel, созданная с помощью g_io_channel_unix_new().
Возвращает : дескриптор файла 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.

fd : дескриптор файла библиотеки C.
Возвращает : новая GIOChannel.

g_io_channel_win32_new_socket ()

GIOChannel* g_io_channel_win32_new_socket   (gint socket);

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

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

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

socket :
Возвращает : новая GIOChannel.

g_io_channel_win32_new_messages ()

GIOChannel* g_io_channel_win32_new_messages (guint hwnd);

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

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

hwnd : обрабатываемое окно.
Возвращает : новая GIOChannel.

g_io_channel_init ()

void        g_io_channel_init               (GIOChannel *channel);

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

channel : 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() (такое выполнение не вызовет никаких проблем, пока не попытается обратиться к уже закрытому каналу).

filename : строка содержащая имя файла.
mode : Один из режимов "r", "w", "a", "r+", "w+", "a+". Тоже самое как в fopen().
error : расположение возвращаемой ошибки типа G_FILE_ERROR.
Возвращает : GIOChannel при успешном выполнении, NULL при неудаче.

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.

channel : GIOChannel
buf : буфер из которого читаются данные
count : размер буфера. Помните что буфер может быть заполнен не полностью если оставшиеся данные не полный символ.
bytes_read : количество читаемых байт. Может быть ноль даже при удаче, если количество < 6 а кодировка каналов не-NULL. Это указывает что следующий символ UTF-8 слишком большой для буфера.
error : расположение возвращаемой ошибки типа GConvertError или GIOChannelError.
Возвращает : состояние операции.

g_io_channel_read_unichar ()

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

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

channel : GIOChannel
thechar : расположение возвращаемого символа
error : расположение возвращаемой ошибки типа GConvertError или GIOChannelError
Возвращает : GIOStatus

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.

channel : GIOChannel
str_return : Читаемая строка из GIOChannel, включая завершающий символ. Эти данные должны освобождаться с помощью g_free() когда больше не нужны. Это nul-terminated строка. Если возвращаемая length равна нулю, то вместо этого она будет NULL.
length : размещение для сохранения длины читаемых данных, или NULL
terminator_pos : размещение для сохранения позиции завершающей строку, или NULL
error : расположение для возвращаемой ошибки типа GConvertError или GIOChannelError
Возвращает : статус операции.

g_io_channel_read_line_string ()

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

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

channel : GIOChannel
buffer : GString в который записывается строка. Если buffer уже содержит данные, они будут перезаписаны.
terminator_pos : расположение для сохранения позиции завершения строки, или NULL
error : расположение для сохранения ошибки типа GConvertError или GIOChannelError
Возвращает : состояние операции.

g_io_channel_read_to_end ()

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

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

channel : GIOChannel
str_return : расположение для хранения указателя на строку содержащую оставшиеся данные в GIOChannel. Эти данные должны освобождаться с помощью g_free() когда больше не нужны. Эти данные завершаются дополнительным символом nul, но могут быть другие nuls в предыдущих данных.
length : расположение для хранения длины данных
error : расположение для возвращаемой ошибки типа GConvertError или GIOChannelError
Возвращает : G_IO_STATUS_NORMAL при успешном выполнении. Эта функция никогда не возвращает G_IO_STATUS_EOF.

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().

channel : GIOChannel
buf : буфер из которого записываются данные
count : размер буфера. Если -1, буфер применяется для nul-terminated строки.
bytes_written : количество записываемых байт. Может быть не нулевым даже если возвращаемое значение не G_IO_STATUS_NORMAL. Если возвращаемое значение G_IO_STATUS_NORMAL и канал заблокирован, значение всегда эквивалентно count если count >= 0.
error : Расположение возвращаемой ошибки типа GConvertError или GIOChannelError
Возвращает : статус операции.

g_io_channel_write_unichar ()

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

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

channel : GIOChannel
thechar : символ
error : расположение возвращаемой ошибки типа GConvertError или GIOChannelError
Возвращает : GIOStatus

g_io_channel_flush ()

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

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

channel : GIOChannel
error : расположение возвращаемой ошибки типа GIOChannelError
Возвращает : статус операции: G_IO_CHANNEL_NORMAL, G_IO_CHANNEL_AGAIN, или G_IO_CHANNEL_ERROR.

g_io_channel_seek_position ()

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

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

channel : GIOChannel
offset : смещение в байтах из позиции определённой с помощью type
type : GSeekType. Тип G_SEEK_CUR допустим только когда допустим вызов g_io_channel_set_encoding(). Смотрите документацию для g_io_channel_set_encoding() для детального изучения.
error : расположение возвращаемой ошибки типа GIOChannelError
Возвращает : статус операции.

enum GSeekType

typedef enum
{
  G_SEEK_CUR,
  G_SEEK_SET,
  G_SEEK_END
} GSeekType;

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

G_SEEK_CUR текущая позиция в файле.
G_SEEK_SET начало файла.
G_SEEK_END конец файла.

g_io_channel_shutdown ()

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

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

channel : GIOChannel
flush : если TRUE, ожидающие обработки данные записываются на диск синхронизируя содержимое памяти и диска
err : расположение для хранения GIOChannelError
Возвращает : статус операции.

enum GIOStatus

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

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

G_IO_STATUS_ERROR произошла ошибка.
G_IO_STATUS_NORMAL удачное завершение операции.
G_IO_STATUS_EOF конец файла.
G_IO_STATUS_AGAIN ресурсы временно недоступны.

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_FBIG файл слишком большой.
G_IO_CHANNEL_ERROR_INVAL недопустимый аргумент.
G_IO_CHANNEL_ERROR_IO ошибка 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 испорченный канал.
G_IO_CHANNEL_ERROR_FAILED какая то другая ошибка.

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.

en : номер ошибки errno, например EINVAL.
Возвращает : GIOChannelError номер ошибки, например G_IO_CHANNEL_ERROR_INVAL.

g_io_channel_ref ()

GIOChannel* g_io_channel_ref                (GIOChannel *channel);

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

channel : GIOChannel.
Возвращает : channel в который был помещён (Начиная с версии 2.6)

g_io_channel_unref ()

void        g_io_channel_unref              (GIOChannel *channel);

Уменьшает количество ссылок 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 создаётся для просматриваемого канала для сокета, помещая сокет в деблокированный режим. Этот побочный эффект реализации неизбежен.

channel : GIOChannel to watch
condition : прсматриваемое условие
Возвращает : новая GSource

g_io_add_watch ()

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

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

channel : GIOChannel.
condition : условие для просмотра.
func : функция вызываемая когда условие удовлетворено.
user_data : пользовательские данные помещаемые в func.
Возвращает : id источника события.

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 в основной цикл события с полученным приоритетом.

channel : GIOChannel.
priority : приоритет GIOChannel источника.
condition : рассматриваемое условие.
func : функция вызываемая при удовлетворении условия.
user_data : пользовательские данные помещаемые в func.
notify : функция вызываемая при удалении источника.
Возвращает : id источника события.

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;

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

G_IO_IN есть данные для чтения.
G_IO_OUT данные могут быть записаны (без блокировки).
G_IO_PRI есть неотложные данные для чтения.
G_IO_ERR ошибочное условие.
G_IO_HUP зависание (соединение прервано, обычно для каналов и сокетов).
G_IO_NVAL неправильный запрос. Дескриптор файла не открыт.

GIOFunc ()

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

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

source : источник события GIOChannel.
condition : условие которое должно удовлетворяться.
data : пользовательские данные устанавливаемые в g_io_add_watch() или g_io_add_watch_full().
Возвращает : функция должна вернуть FALSE если источник события должен быть удалён.

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);

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

channel : GIOChannel
Возвращает : размер буфера.

g_io_channel_set_buffer_size ()

void        g_io_channel_set_buffer_size    (GIOChannel *channel,
                                             gsize size);

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

channel : GIOChannel
size : размер буфера. 0 == подобрать наилучший размер

g_io_channel_get_buffer_condition ()

GIOCondition g_io_channel_get_buffer_condition
                                            (GIOChannel *channel);

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

channel : GIOChannel
Возвращает : GIOCondition

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() для обновления внутренних значений этих флажков.

channel : GIOChannel
Возвращает : флаги которые устанавливаются в канале

g_io_channel_set_flags ()

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

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

channel : GIOChannel.
flags : флаги для установки в канал IO.
error : расположение возвращаемой ошибки типа GIOChannelError.
Возвращает : статус операции.

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_FLAG_APPEND включает режим предварительной перемотки файла в конец (append mode), соответствует O_APPEND (смотрите документацию системного вызова UNIX open()).
G_IO_FLAG_NONBLOCK включает не блокируемый режим, соответствует O_NONBLOCK/O_NDELAY (смотрите документацию системного вызова UNIX open()).
G_IO_FLAG_IS_READABLE указывает что канал читаемый. Этот флаг не может изменяться.
G_IO_FLAG_IS_WRITEABLE указывает что канал записываемый. Этот флаг не может изменяться.
G_IO_FLAG_IS_SEEKABLE указывает что io канал может изменять позицию доступа (seekable), то есть что в нём может использоваться функция g_io_channel_seek_position(). Этот флаг не может изменяться.
G_IO_FLAG_MASK
G_IO_FLAG_GET_MASK
G_IO_FLAG_SET_MASK

g_io_channel_get_line_term ()

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

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

channel : GIOChannel
length : расположение для возвращаемой длины завершающего строку символа
Возвращает : Строка завершения линии. Этим значением владеет GLib и оно не должно освобождаться.

g_io_channel_set_line_term ()

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

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

channel : GIOChannel
line_term : Строка прерывания линии. Используйте NULL для автоматического определения. Автоматическое определение прерывается на "\n", "\r\n", "\r", "\0", и разделителе параграфов Unicode. Автоматическое определение не должно использоваться ни для чего кроме каналов основанных на файлах.
length : Длина прерываемой строки. Если помещено значение -1, строка будет как предполагается nul-terminated. Эта опция позволяет прерывать строки с встроенным nuls.

g_io_channel_get_buffered ()

gboolean    g_io_channel_get_buffered       (GIOChannel *channel);

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

channel : GIOChannel.
Возвращает : TRUE если 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, если это необходимо для поддержки старого кода.

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

channel : GIOChannel
buffered : является ли канал буферизированным или нет

g_io_channel_get_encoding ()

const gchar* g_io_channel_get_encoding      (GIOChannel *channel);

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

channel : GIOChannel
Возвращает : строка содержащая кодировку, строкой владеет GLib и она не должна освобождаться.

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".

channel : GIOChannel
encoding : тип кодировки
error : размещение для хранения ошибки типа GConvertError.
Возвращает : G_IO_STATUS_NORMAL если кодировка была полностью установлена.

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 для всех других каналов.

channel : GIOChannel.
Возвращает : будет ли закрыт канал при удалении последней ссылки на структуру данных GIOChannel.

g_io_channel_set_close_on_unref ()

void        g_io_channel_set_close_on_unref (GIOChannel *channel,
                                             gboolean do_close);

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

channel : GIOChannel
do_close : закрывается ли канал при удалении последней ссылки на структуру данных GIOChannel. Значение по умолчанию TRUE для каналов созданных с помощью g_io_channel_new_file(), а FALSE для всех других каналов.

g_io_channel_read ()

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

Внимание

g_io_channel_read устарела начиная с версии 2.2 и не должна использоваться во вновь создаваемом коде. Используйте g_io_channel_read_chars() вместо неё.

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

channel : GIOChannel.
buf : буфер из которого читаются данные (which should be at least count bytes long).
count : количество байт читаемых из GIOChannel.
bytes_read : возвращает фактическое количество прочтенных байт.
Возвращает : G_IO_ERROR_NONE если операция была успешно выполнена.

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_ERROR_NONE нет ошибки
G_IO_ERROR_AGAIN произошла ошибка EAGAIN
G_IO_ERROR_INVAL произошла ошибка EINVAL
G_IO_ERROR_UNKNOWN произошла другая ошибка

g_io_channel_write ()

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

Внимание

g_io_channel_write устарела начиная с версии 2.2 и не должна использоваться во вновь создаваемом коде. Используйте g_io_channel_write_chars() вместо неё.

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

channel : a GIOChannel.
buf : буфер содержащий данные для записи.
count : количество байт для записи.
bytes_written : количество фактически записанных байт.
Возвращает : G_IO_ERROR_NONE если операция полностью выполнена.

g_io_channel_seek ()

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

Внимание

g_io_channel_seek устарела начиная с версии 2.2 и не должна использоваться во вновь создаваемом коде. Используйте g_io_channel_seek_position() вместо неё.

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

channel : GIOChannel.
offset : смещение в байтах, которое добавляется в позицию определённую type
type : позиция в файе, которая может быть G_SEEK_CUR (текущая позиция), G_SEEK_SET (начало файла), или G_SEEK_END (конец файла).
Возвращает : G_IO_ERROR_NONE если операция выполнена успешно.

g_io_channel_close ()

void        g_io_channel_close              (GIOChannel *channel);

Внимание

g_io_channel_close устарела начиная с версии 2.2 и не должна использоваться во вновь создаваемом коде. Используйте g_io_channel_shutdown() вместо неё.

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

channel : GIOChannel

Смотрите также

gtk_input_add_full(), gtk_input_remove(), gdk_input_add(), gdk_input_add_full(), gdk_input_remove()

Удобные функции для создания GIOChannel и добавления его в основной цикл события.




Спонсоры:
Inferno Solutions
Hosting by Hoster.ru
Хостинг:

Закладки на сайте
Проследить за страницей
Created 1996-2021 by Maxim Chirkov
Добавить, Поддержать, Вебмастеру