The `GIOChannel` data type aims to provide a portable method for using file descriptors, pipes, and sockets, and integrating them into
the main event loop (see [struct@GLib.
MainContext]). Currently, full support is available on UNIX platforms; support for Windows is only partially complete.
To create a new `GIOChannel` on UNIX systems use [ctor@GLib.IOChannel.unix_new]. This works for plain file descriptors, pipes and
sockets. Alternatively, a channel can be created for a file in a system independent manner using [ctor@GLib.IOChannel.new_file].
Once a `GIOChannel` has been created, it can be used in a generic manner with the functions [method@GLib.IOChannel.read_chars], [
method@GLib.IOChannel.write_chars], [method@GLib.IOChannel.seek_position], and [method@GLib.IOChannel.shutdown].
To add a `GIOChannel` to the main event loop, use [func@GLib.io_add_watch] or [func@GLib.io_add_watch_full]. Here you specify which
events you are interested in on the `GIOChannel`, and provide a function to be called whenever these events occur.
`GIOChannel` instances are created with an initial reference count of 1. [method@GLib.IOChannel.ref] and [method@GLib.IOChannel.unref]
can be used to increment or decrement the reference count respectively. When the reference count falls to 0, the `GIOChannel` is freed. (
Though it isn’t closed automatically, unless it was created using [ctor@GLib.IOChannel.new_file].) Using [func@GLib.io_add_watch] or [
func@GLib.io_add_watch_full] increments a channel’s reference count.
The new functions [method@GLib.IOChannel.read_chars], [method@GLib.IOChannel.read_line], [method@GLib.IOChannel.read_line_string], [
method@GLib.IOChannel.read_to_end], [method@GLib.IOChannel.write_chars], [method@GLib.IOChannel.seek_position], and [
method@GLib.IOChannel.flush] should not be mixed with the deprecated functions [method@GLib.IOChannel.read], [method@GLib.IOChannel.write]
, and [method@GLib.IOChannel.seek] on the same channel.
Example: Watch a file with IOChannel:
public static int main (string[] args) {
MainLoop loop = new MainLoop (null, false);
IOChannel channel = null;
try {
channel = new IOChannel.file ("my-io-channel-test-file.txt", "r");
} catch (FileError e) {
print ("FileError: %s\n", e.message);
return 0;
}
uint stat = channel.add_watch (IOCondition.IN, (source, condition) => {
size_t terminator_pos = -1;
string str_return = null;
size_t length = -1;
if (condition == IOCondition.HUP) {
print ("The connection has been broken.\n");
return false;
}
try {
IOStatus status = channel.read_line (out str_return, out length, out terminator_pos);
if (status == IOStatus.EOF) {
// Quit the program:
loop.quit ();
return false;
}
print ("watch: %s", str_return);
return true;
} catch (IOChannelError e) {
print ("IOChannelError: %s\n", e.message);
return false;
} catch (ConvertError e) {
print ("ConvertError: %s\n", e.message);
return false;
}
});
if(stat == 0) {
print ("Cannot add watch on IOChannel.\n");
return 0;
}
loop.run ();
return 0;
}
valac --pkg glib-2.0 GLib.IOChannel.vala
- public uint add_watch (IOCondition condition, IOFunc func)
Adds the IOChannel into the default main
loop context with the default priority.
- public uint add_watch_full (int priority, IOCondition condition, owned IOFunc func)
Adds the IOChannel into the default main
loop context with the given priority.
- public IOSource create_watch (IOCondition condition)
- public IOStatus flush () throws IOChannelError
Flushes the write buffer for the GIOChannel.
- public IOCondition get_buffer_condition ()
This function returns a
IOCondition depending on whether there is data to be read/space to write data in the internal buffers in the
IOChannel.
- public size_t get_buffer_size ()
Gets the buffer size.
- public bool get_buffered ()
Returns whether this is buffered.
- public bool get_close_on_unref ()
Returns whether the file/socket/whatever associated with
this will be closed when this receives its final unref and is
destroyed.
- public unowned string get_encoding ()
Gets the encoding for the input/output of the channel.
- public IOFlags get_flags ()
Gets the current flags for a IOChannel,
including read-only flags such as g_io_flag_is_readable.
- public unowned string get_line_term (out int length)
This returns the string that IOChannel uses
to determine where in the file a line break occurs.
- public void init ()
Initializes a IOChannel struct.
- public IOStatus read_chars (char[] buf, out size_t bytes_read) throws ConvertError, IOChannelError
Replacement for g_io_channel_read
with the new API.
- public IOStatus read_line (out string str_return, out size_t length, out size_t terminator_pos) throws ConvertError, IOChannelError
Reads a line, including the terminating character(s), from a
IOChannel into a newly-allocated string.
- public IOStatus read_line_string (StringBuilder buffer, out size_t terminator_pos) throws ConvertError, IOChannelError
Reads a line from a IOChannel, using a
StringBuilder as a buffer.
- public IOStatus read_to_end (out string str_return, out size_t length) throws ConvertError, IOChannelError
Reads all the remaining data from the file.
- public IOStatus read_unichar (out unichar thechar) throws ConvertError, IOChannelError
Reads a Unicode character from this.
- public IOStatus seek_position (int64 offset, SeekType type) throws IOChannelError
Replacement for g_io_channel_seek
with the new API.
- public void set_buffer_size (size_t size)
Sets the buffer size.
- public void set_buffered (bool buffered)
The buffering state can only be set if the channel's encoding is
null.
- public void set_close_on_unref (bool do_close)
Whether to close the channel on the final unref of the
IOChannel data structure.
- public IOStatus set_encoding (string? encoding) throws IOChannelError
Sets the encoding for the input/output of the channel.
- public IOStatus set_flags (IOFlags flags) throws IOChannelError
Sets the (writeable) flags in this
to (flags
& g_io_flag_set_mask).
- public void set_line_term (string line_term, int length)
This sets the string that IOChannel uses to
determine where in the file a line break occurs.
- public IOStatus shutdown (bool flush) throws IOChannelError
Close an IO channel.
- public int unix_get_fd ()
Returns the file descriptor of the IOChannel
.
- public int win32_get_fd ()
- public void win32_make_pollfd (IOCondition condition, ref PollFD fd)
- public void win32_set_debug (bool flag)
- public IOStatus write_chars (char[] buf, out size_t bytes_written) throws ConvertError, IOChannelError
Replacement for g_io_channel_write
with the new API.
- public IOStatus write_unichar (unichar thechar) throws ConvertError, IOChannelError
Writes a Unicode character to this.