Para crear un GIOChannel, primero se debe crear el descriptor de fichero de UNIX™ por los métodos convencionales (open, socket, etc.) y luego utilizar g_io_channel_unix_new o bien g_io_channel_new_file para acceder a ficheros directamente.

Esta función devuelve el canal creado a partir del descriptor. Dicho parámetro se puede recuperar después utilizando la función g_io_channel_unix_get_fd.

Devuelve un nuevo canal para acceder al archivo nombre_fichero. El modo tiene la misma forma que el parámetro modo de la función de C estándar fopen. Esto es:

El parámetro error debe apuntar a una estructura tipo GError previamente creada y es aquí donde se informa de cualquier problema al abrir el fichero. En este último caso la función retorna NULL.

Una vez obtenido el GIOChannel, en general, todas las llamadas a funciones para realizar alguna operación sobre el canal (lectura, escritura, etc.) tomarán como primer parámetro al propio canal y como último un puntero, error, a una estructura GError, donde se informará de cualquier inconveniente ocurrido al intentar la operación. Además, la mayoría de las funciones retornan un código del tipo GIOStatus que puede tomar los siguientes valores:

En caso de que el código de retorno sea G_IO_STATUS_ERROR, en la estructura GError se almacena otro código, indicando con mayor detalle la naturaleza del problema. Este nuevo código es de tipo GIOChannelError y puede tomar los siguientes valores:

Los primeros valores tienen su correspondencia directa con los valores de la variable errno estándar de C. El último se reserva para otra clase de errores no identificados.

Los canales tienen un tiempo de vida controlado por conteo de referencias. Inicialmente, los canales se crean con una cuenta de 1 y, cuando la misma cae a 0, se destruyen. Para obtener una referencia se utiliza la función g_io_channel_ref y para liberar una referencia g_io_channel_unref. Cabe aclarar que, aunque el objeto GIOChannel se destruya, no necesariamente se cierra el canal. En concreto, si el objeto fue creado a partir de un descriptor de UNIX™, el programador es responsable de cerrarlo (a menos que se utilice la función g_io_channel_set_close_on_unref).

Las funciones mencionadas tienen la siguiente forma:

Para cerrar de un canal se utiliza g_io_channel_shutdown:

Aquí, el parámetro descarga controla si se escriben los datos que pueda haber en el buffer interno del canal antes de cerrarlo (para forzar una descarga en cualquier momento se puede utilizar g_io_channel_flush).

GLib™ provee una serie de funciones para acceder a un canal abierto de diversas maneras: por caracteres individuales, por bloques de cantidad de bytes fijos y por líneas.

Si el tipo de canal lo permite, la función g_io_channel_seek_position sirve para establecer la siguiente posición donde se leerá o escribirá. Normalmente sólo los ficheros permiten posicionamiento aleatorio.

La semántica de posición (que es un número con signo) queda determinada por el tipo_posicion, que puede tomar los siguientes valores:

Para efectuar lecturas en un canal se utilizan algunas de las siguientes funciones:

Lee una cantidad máxima (tamaño_buffer) de bytes del canal como caracteres y los almacena en buffer. Éste debe estar previamente reservado (p.e. con g_malloc). bytes_leidos contiene la cantidad de bytes efectivamente leídos (puede ser menor que la solicitada).

Es importante notar que si el canal está configurado para trabajar con caracteres Unicode™, un carácter puede ocupar más de un byte y, si el buffer no es lo suficientemente grande, puede que no sea posible almacenar ningún carácter. En estas condiciones bytes_leidos es cero, pero no hay indicación de error.

Lee una línea completa del canal y almacena el puntero a la misma en puntero_cadena>. Una vez finalizada la operación con la línea, es responsabilidad del programador liberar la memoria con g_free. En bytes_leidos se devuelve la cantidad total de bytes leídos (incluyendo caracteres de fin de línea) y en terminador, sólo la cantidad perteneciente a la línea en sí. Tanto bytes_leidos como terminador pueden ser nulos si la información no es de interés.

Similar a g_io_channel_read_line, sólo que, para devolver el resultado, utiliza una estructura GString. terminador puede ser nulo.

Lee todos los bytes disponibles en el canal hasta encontrar el fin de fichero. En puntero_cadena se devuelve un puntero al espacio de memoria asignado a tal fin que luego debe ser liberado con g_free.

Para la escritura se utiliza la contraparte de g_io_channel_read_chars:

Como su propio nombre indica, esta función escribe en el canal cantidad_bytes del buffer. Puede que no lleguen a escribirse todos los bytes que se solicitaron, por lo que la función devuelve la cantidad de bytes efectivamente escritos. Si cantidad_bytes es -1 se considera al buffer como terminado en nulo.

Se aplican las mismas restricciones en cuanto a codificación del canal que para g_io_channel_read_chars.

Uno de los aspectos más interesantes de los GIOChannels es que es posible integrarlos fácilmente al bucle de eventos y así, por ejemplo, hacer que la aplicación reaccione ante la llegada de datos.

Los posibles tipos de eventos que puede generar un canal están dados por el tipo GIOCondition que toma los siguientes valores:

La forma básica de integrar un objeto generador de eventos al bucle es obtener una estructura GSource. En el caso de los canales, la función para ello es g_io_create_watch:

Esta función devuelve un GSource que luego se registra en algún bucle de eventos con g_source_attach. Sin embargo, por conveniencia, GLib™ provee un par adicional de funciones para integrar directamente un canal al bucle principal: g_io_watch y f_io_add_watch_full.

Esta función, que devuelve el identificador de evento, registra el canal para que sea controlado según las condiciones especificadas. En caso de que se cumpla alguna de las condiciones, se llama a la función con los datos_usuario adicionales.

La función especificada en el registro debe tener la siguiente forma:

La condición que la función recibe es aquella que causó el evento en primer lugar. datos_usario es lo que se especificó en el momento del registro.

La otra función, g_io_add_watch_full permite además especificar la prioridad del canal y una función de notificación cuando el canal se desconecta del bucle de eventos.