mirror of
https://gitlab.gnome.org/GNOME/glib.git
synced 2025-03-14 11:45:11 +01:00
GIOChannel: move docs from tmpl to .c
This commit is contained in:
parent
4353151449
commit
4bdf7d12a8
1
docs/reference/glib/tmpl/.gitignore
vendored
1
docs/reference/glib/tmpl/.gitignore
vendored
@ -9,6 +9,7 @@ ghostutils.sgml
|
||||
gurifuncs.sgml
|
||||
gvarianttype.sgml
|
||||
hash_tables.sgml
|
||||
iochannels.sgml
|
||||
memory_chunks.sgml
|
||||
option.sgml
|
||||
patterns.sgml
|
||||
|
@ -1,666 +0,0 @@
|
||||
<!-- ##### SECTION Title ##### -->
|
||||
IO Channels
|
||||
|
||||
<!-- ##### SECTION Short_Description ##### -->
|
||||
portable support for using files, pipes and sockets
|
||||
|
||||
<!-- ##### SECTION Long_Description ##### -->
|
||||
<para>
|
||||
The #GIOChannel data type aims to provide a portable method for using file
|
||||
descriptors, pipes, and sockets, and integrating them into the
|
||||
<link linkend="glib-The-Main-Event-Loop">main event loop</link>.
|
||||
Currently full support is available on UNIX platforms, support for
|
||||
Windows is only partially complete.
|
||||
</para>
|
||||
<para>
|
||||
To create a new #GIOChannel on UNIX systems use g_io_channel_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 g_io_channel_new_file().
|
||||
</para>
|
||||
<para>
|
||||
Once a #GIOChannel has been created, it can be used in a generic manner
|
||||
with the functions g_io_channel_read_chars(), g_io_channel_write_chars(),
|
||||
g_io_channel_seek_position(), and g_io_channel_shutdown().
|
||||
</para>
|
||||
<para>
|
||||
To add a #GIOChannel to the
|
||||
<link linkend="glib-The-Main-Event-Loop">main event loop</link>
|
||||
use g_io_add_watch() or g_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.
|
||||
</para>
|
||||
<para>
|
||||
#GIOChannel instances are created with an initial reference count of 1.
|
||||
g_io_channel_ref() and g_io_channel_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 g_io_channel_new_from_file().)
|
||||
Using g_io_add_watch() or g_io_add_watch_full() increments a channel's
|
||||
reference count.
|
||||
</para>
|
||||
<para>
|
||||
The new functions 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(),
|
||||
and g_io_channel_flush() should not be mixed with the
|
||||
deprecated functions g_io_channel_read(), g_io_channel_write(),
|
||||
and g_io_channel_seek() on the same channel.
|
||||
</para>
|
||||
|
||||
<!-- ##### SECTION See_Also ##### -->
|
||||
<para>
|
||||
<variablelist>
|
||||
|
||||
<varlistentry>
|
||||
<term>gtk_input_add_full(), gtk_input_remove(), gdk_input_add(),
|
||||
gdk_input_add_full(), gdk_input_remove()</term>
|
||||
<listitem><para>
|
||||
Convenience functions for creating #GIOChannel instances and adding them to the
|
||||
<link linkend="glib-The-Main-Event-Loop">main event loop</link>.
|
||||
</para></listitem>
|
||||
</varlistentry>
|
||||
|
||||
</variablelist>
|
||||
</para>
|
||||
|
||||
<!-- ##### SECTION Stability_Level ##### -->
|
||||
|
||||
|
||||
<!-- ##### STRUCT GIOChannel ##### -->
|
||||
<para>
|
||||
A data structure representing an IO Channel. The fields should be considered
|
||||
private and should only be accessed with the following functions.
|
||||
</para>
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_io_channel_unix_new ##### -->
|
||||
<para>
|
||||
Creates a new #GIOChannel given a file descriptor.
|
||||
On UNIX systems this works for plain files, pipes, and sockets.
|
||||
</para>
|
||||
<para>
|
||||
The returned #GIOChannel has a reference count of 1.
|
||||
</para>
|
||||
<para>
|
||||
The default encoding for #GIOChannel is UTF-8. If your application
|
||||
is reading output from a command using via pipe, you may need to
|
||||
set the encoding to the encoding of the current locale (see
|
||||
g_get_charset()) with the g_io_channel_set_encoding() function.
|
||||
</para>
|
||||
<para>
|
||||
If you want to read raw binary data without interpretation, then
|
||||
call the g_io_channel_set_encoding() function with %NULL for the
|
||||
encoding argument.
|
||||
</para>
|
||||
<para>
|
||||
This function is available in GLib on Windows, too, but you should
|
||||
avoid using it on Windows. The domain of file descriptors and sockets
|
||||
overlap. There is no way for GLib to know which one you mean in case
|
||||
the argument you pass to this function happens to be both a valid file
|
||||
descriptor and socket. If that happens a warning is issued, and GLib
|
||||
assumes that it is the file descriptor you mean.
|
||||
</para>
|
||||
|
||||
@fd: a file descriptor.
|
||||
@Returns: a new #GIOChannel.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_io_channel_unix_get_fd ##### -->
|
||||
<para>
|
||||
Returns the file descriptor of the #GIOChannel.
|
||||
</para>
|
||||
<para>
|
||||
On Windows this function returns the file descriptor or socket of the #GIOChannel.
|
||||
</para>
|
||||
|
||||
@channel: a #GIOChannel, created with g_io_channel_unix_new().
|
||||
@Returns: the file descriptor of the #GIOChannel.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_io_channel_win32_new_fd ##### -->
|
||||
<para>
|
||||
Creates a new #GIOChannel given a file descriptor on Windows.
|
||||
This works for file descriptors from the C runtime.
|
||||
</para>
|
||||
<para>
|
||||
This function works for file descriptors as returned by the open(),
|
||||
creat(), pipe() and fileno() calls in the Microsoft C runtime. In
|
||||
order to meaningfully use this function your code should use the same
|
||||
C runtime as GLib uses, which is msvcrt.dll. Note that in current
|
||||
Microsoft compilers it is near impossible to convince it to build code
|
||||
that would use msvcrt.dll. The last Microsoft compiler version that
|
||||
supported using msvcrt.dll as the C runtime was version 6. The GNU
|
||||
compiler and toolchain for Windows, also known as Mingw, fully
|
||||
supports msvcrt.dll.
|
||||
</para>
|
||||
<para>
|
||||
If you have created a #GIOChannel for a file descriptor and started
|
||||
watching (polling) it, you shouldn't call read() on the file
|
||||
descriptor. This is because adding polling for a file descriptor is
|
||||
implemented in GLib on Windows by starting a thread that sits blocked
|
||||
in a read() from the file descriptor most of the time. All reads from
|
||||
the file descriptor should be done by this internal GLib thread. Your
|
||||
code should call only g_io_channel_read().
|
||||
</para>
|
||||
<para>
|
||||
This function is available only in GLib on Windows.
|
||||
</para>
|
||||
|
||||
@fd: a C library file descriptor.
|
||||
@Returns: a new #GIOChannel.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_io_channel_win32_new_socket ##### -->
|
||||
<para>
|
||||
Creates a new #GIOChannel given a socket on Windows.
|
||||
</para>
|
||||
<para>
|
||||
This function works for sockets created by Winsock.
|
||||
It's available only in GLib on Windows.
|
||||
</para>
|
||||
<para>
|
||||
Polling a #GSource created to watch a channel for a socket
|
||||
puts the socket in non-blocking mode. This is a side-effect
|
||||
of the implementation and unavoidable.
|
||||
</para>
|
||||
|
||||
@socket: a Winsock socket
|
||||
@Returns: a new #GIOChannel
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_io_channel_win32_new_messages ##### -->
|
||||
<para>
|
||||
Creates a new #GIOChannel given a window handle on Windows.
|
||||
</para>
|
||||
<para>
|
||||
This function creates a #GIOChannel that can be used to poll for
|
||||
Windows messages for the window in question.
|
||||
</para>
|
||||
|
||||
@hwnd: a window handle.
|
||||
@Returns: a new #GIOChannel.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_io_channel_init ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@channel:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_io_channel_new_file ##### -->
|
||||
<para>
|
||||
</para>
|
||||
|
||||
@filename:
|
||||
@mode:
|
||||
@error:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_io_channel_read_chars ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@channel:
|
||||
@buf:
|
||||
@count:
|
||||
@bytes_read:
|
||||
@error:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_io_channel_read_unichar ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@channel:
|
||||
@thechar:
|
||||
@error:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_io_channel_read_line ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@channel:
|
||||
@str_return:
|
||||
@length:
|
||||
@terminator_pos:
|
||||
@error:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_io_channel_read_line_string ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@channel:
|
||||
@buffer:
|
||||
@terminator_pos:
|
||||
@error:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_io_channel_read_to_end ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@channel:
|
||||
@str_return:
|
||||
@length:
|
||||
@error:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_io_channel_write_chars ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@channel:
|
||||
@buf:
|
||||
@count:
|
||||
@bytes_written:
|
||||
@error:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_io_channel_write_unichar ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@channel:
|
||||
@thechar:
|
||||
@error:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_io_channel_flush ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@channel:
|
||||
@error:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_io_channel_seek_position ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@channel:
|
||||
@offset:
|
||||
@type:
|
||||
@error:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### ENUM GSeekType ##### -->
|
||||
<para>
|
||||
An enumeration specifying the base position for a g_io_channel_seek_position()
|
||||
operation.
|
||||
</para>
|
||||
|
||||
@G_SEEK_CUR: the current position in the file.
|
||||
@G_SEEK_SET: the start of the file.
|
||||
@G_SEEK_END: the end of the file.
|
||||
|
||||
<!-- ##### FUNCTION g_io_channel_shutdown ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@channel:
|
||||
@flush:
|
||||
@err:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### ENUM GIOStatus ##### -->
|
||||
<para>
|
||||
Stati returned by most of the #GIOFuncs functions.
|
||||
</para>
|
||||
|
||||
@G_IO_STATUS_ERROR: An error occurred.
|
||||
@G_IO_STATUS_NORMAL: Success.
|
||||
@G_IO_STATUS_EOF: End of file.
|
||||
@G_IO_STATUS_AGAIN: Resource temporarily unavailable.
|
||||
|
||||
<!-- ##### ENUM GIOChannelError ##### -->
|
||||
<para>
|
||||
Error codes returned by #GIOChannel operations.
|
||||
</para>
|
||||
|
||||
@G_IO_CHANNEL_ERROR_FBIG: File too large.
|
||||
@G_IO_CHANNEL_ERROR_INVAL: Invalid argument.
|
||||
@G_IO_CHANNEL_ERROR_IO: IO error.
|
||||
@G_IO_CHANNEL_ERROR_ISDIR: File is a directory.
|
||||
@G_IO_CHANNEL_ERROR_NOSPC: No space left on device.
|
||||
@G_IO_CHANNEL_ERROR_NXIO: No such device or address.
|
||||
@G_IO_CHANNEL_ERROR_OVERFLOW: Value too large for defined datatype.
|
||||
@G_IO_CHANNEL_ERROR_PIPE: Broken pipe.
|
||||
@G_IO_CHANNEL_ERROR_FAILED: Some other error.
|
||||
|
||||
<!-- ##### MACRO G_IO_CHANNEL_ERROR ##### -->
|
||||
<para>
|
||||
Error domain for #GIOChannel operations. Errors in this domain will
|
||||
be from the #GIOChannelError enumeration. See #GError for information on
|
||||
error domains.
|
||||
</para>
|
||||
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_io_channel_error_from_errno ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@en:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_io_channel_ref ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@channel:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_io_channel_unref ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@channel:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_io_create_watch ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@channel:
|
||||
@condition:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_io_add_watch ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@channel:
|
||||
@condition:
|
||||
@func:
|
||||
@user_data:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_io_add_watch_full ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@channel:
|
||||
@priority:
|
||||
@condition:
|
||||
@func:
|
||||
@user_data:
|
||||
@notify:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### ENUM GIOCondition ##### -->
|
||||
<para>
|
||||
A bitwise combination representing a condition to watch for on
|
||||
an event source.
|
||||
</para>
|
||||
|
||||
@G_IO_IN: There is data to read.
|
||||
@G_IO_OUT: Data can be written (without blocking).
|
||||
@G_IO_PRI: There is urgent data to read.
|
||||
@G_IO_ERR: Error condition.
|
||||
@G_IO_HUP: Hung up (the connection has been broken, usually for pipes
|
||||
and sockets).
|
||||
@G_IO_NVAL: Invalid request. The file descriptor is not open.
|
||||
|
||||
<!-- ##### USER_FUNCTION GIOFunc ##### -->
|
||||
<para>
|
||||
Specifies the type of function passed to g_io_add_watch() or
|
||||
g_io_add_watch_full(), which is called when the requested
|
||||
condition on a #GIOChannel is satisfied.
|
||||
</para>
|
||||
|
||||
@source: the #GIOChannel event source
|
||||
@condition: the condition which has been satisfied
|
||||
@data: user data set in g_io_add_watch() or g_io_add_watch_full()
|
||||
@Returns: the function should return %FALSE if the event source
|
||||
should be removed
|
||||
|
||||
|
||||
<!-- ##### STRUCT GIOFuncs ##### -->
|
||||
<para>
|
||||
A table of functions used to handle different types of #GIOChannel
|
||||
in a generic way.
|
||||
</para>
|
||||
|
||||
@io_read: reads raw bytes from the channel. This is called from various functions such as g_io_channel_read_chars() to read raw bytes from the channel. Encoding and buffering issues are dealt with at a higher level.
|
||||
@io_write: writes raw bytes to the channel. This is called from various functions such as g_io_channel_write_chars() to write raw bytes to the channel. Encoding and buffering issues are dealt with at a higher level.
|
||||
@io_seek: (optional) seeks the channel. This is called from g_io_channel_seek() on channels that support it.
|
||||
@io_close: closes the channel. This is called from g_io_channel_close() after flushing the buffers.
|
||||
@io_create_watch: creates a watch on the channel. This call corresponds directly to g_io_create_watch().
|
||||
@io_free: called from g_io_channel_unref() when the channel needs to be freed. This function must free the memory associated with the channel, including freeing the #GIOChannel structure itself. The channel buffers have been flushed and possibly @io_close has been called by the time this function is called.
|
||||
@io_set_flags: sets the #GIOFlags on the channel. This is called from g_io_channel_set_flags() with all flags except for %G_IO_FLAG_APPEND and %G_IO_FLAG_NONBLOCK masked out.
|
||||
@io_get_flags: gets the #GIOFlags for the channel. This function need only return the %G_IO_FLAG_APPEND and %G_IO_FLAG_NONBLOCK flags; g_io_channel_get_flags() automatically adds the others as appropriate.
|
||||
|
||||
<!-- ##### FUNCTION g_io_channel_get_buffer_size ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@channel:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_io_channel_set_buffer_size ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@channel:
|
||||
@size:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_io_channel_get_buffer_condition ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@channel:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_io_channel_get_flags ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@channel:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_io_channel_set_flags ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@channel:
|
||||
@flags:
|
||||
@error:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### ENUM GIOFlags ##### -->
|
||||
<para>
|
||||
Specifies properties of a #GIOChannel. Some of the flags can only
|
||||
be read with g_io_channel_get_flags(), but not changed with
|
||||
g_io_channel_set_flags().
|
||||
</para>
|
||||
|
||||
@G_IO_FLAG_APPEND: turns on append mode, corresponds to %O_APPEND
|
||||
(see the documentation of the UNIX open() syscall).
|
||||
@G_IO_FLAG_NONBLOCK: turns on nonblocking mode, corresponds to
|
||||
%O_NONBLOCK/%O_NDELAY (see the documentation of the UNIX open()
|
||||
syscall).
|
||||
@G_IO_FLAG_IS_READABLE: indicates that the io channel is readable.
|
||||
This flag can not be changed.
|
||||
@G_IO_FLAG_IS_WRITEABLE: indicates that the io channel is writable.
|
||||
This flag can not be changed.
|
||||
@G_IO_FLAG_IS_SEEKABLE: indicates that the io channel is seekable,
|
||||
i.e. that g_io_channel_seek_position() can be used on it.
|
||||
This flag can not be changed.
|
||||
@G_IO_FLAG_MASK: the mask that specifies all the valid flags.
|
||||
@G_IO_FLAG_GET_MASK: the mask of the flags that are returned from g_io_channel_get_flags().
|
||||
@G_IO_FLAG_SET_MASK: the mask of the flags that the user can modify with g_io_channel_set_flags().
|
||||
|
||||
<!-- ##### FUNCTION g_io_channel_get_line_term ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@channel:
|
||||
@length:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_io_channel_set_line_term ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@channel:
|
||||
@line_term:
|
||||
@length:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_io_channel_get_buffered ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@channel:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_io_channel_set_buffered ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@channel:
|
||||
@buffered:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_io_channel_get_encoding ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@channel:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_io_channel_set_encoding ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@channel:
|
||||
@encoding:
|
||||
@error:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_io_channel_get_close_on_unref ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@channel:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_io_channel_set_close_on_unref ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@channel:
|
||||
@do_close:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_io_channel_read ##### -->
|
||||
<para>
|
||||
</para>
|
||||
|
||||
@channel:
|
||||
@buf:
|
||||
@count:
|
||||
@bytes_read:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### ENUM GIOError ##### -->
|
||||
<para>
|
||||
#GIOError is only used by the deprecated functions g_io_channel_read(),
|
||||
g_io_channel_write(), and g_io_channel_seek().
|
||||
</para>
|
||||
|
||||
@G_IO_ERROR_NONE: no error
|
||||
@G_IO_ERROR_AGAIN: an EAGAIN error occurred
|
||||
@G_IO_ERROR_INVAL: an EINVAL error occurred
|
||||
@G_IO_ERROR_UNKNOWN: another error occurred
|
||||
|
||||
<!-- ##### FUNCTION g_io_channel_write ##### -->
|
||||
<para>
|
||||
</para>
|
||||
|
||||
@channel:
|
||||
@buf:
|
||||
@count:
|
||||
@bytes_written:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_io_channel_seek ##### -->
|
||||
<para>
|
||||
</para>
|
||||
|
||||
@channel:
|
||||
@offset:
|
||||
@type.
|
||||
@type:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_io_channel_close ##### -->
|
||||
<para>
|
||||
</para>
|
||||
|
||||
@channel:
|
||||
|
||||
|
@ -50,6 +50,122 @@
|
||||
|
||||
#include "galias.h"
|
||||
|
||||
/**
|
||||
* SECTION: iochannels
|
||||
* @title: IO Channels
|
||||
* @short_description: portable support for using files, pipes and
|
||||
* sockets
|
||||
* @see_also: <para> <variablelist> <varlistentry>
|
||||
* <term>gtk_input_add_full(), gtk_input_remove(),
|
||||
* gdk_input_add(), gdk_input_add_full(),
|
||||
* gdk_input_remove()</term> <listitem><para> Convenience
|
||||
* functions for creating #GIOChannel instances and adding
|
||||
* them to the <link linkend="glib-The-Main-Event-Loop">main
|
||||
* event loop</link>. </para></listitem> </varlistentry>
|
||||
* </variablelist> </para>
|
||||
*
|
||||
* The #GIOChannel data type aims to provide a portable method for
|
||||
* using file descriptors, pipes, and sockets, and integrating them
|
||||
* into the <link linkend="glib-The-Main-Event-Loop">main event
|
||||
* loop</link>. Currently full support is available on UNIX platforms,
|
||||
* support for Windows is only partially complete.
|
||||
*
|
||||
* To create a new #GIOChannel on UNIX systems use
|
||||
* g_io_channel_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 g_io_channel_new_file().
|
||||
*
|
||||
* Once a #GIOChannel has been created, it can be used in a generic
|
||||
* manner with the functions g_io_channel_read_chars(),
|
||||
* g_io_channel_write_chars(), g_io_channel_seek_position(), and
|
||||
* g_io_channel_shutdown().
|
||||
*
|
||||
* To add a #GIOChannel to the <link
|
||||
* linkend="glib-The-Main-Event-Loop">main event loop</link> use
|
||||
* g_io_add_watch() or g_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. g_io_channel_ref() and g_io_channel_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
|
||||
* g_io_channel_new_from_file().) Using g_io_add_watch() or
|
||||
* g_io_add_watch_full() increments a channel's reference count.
|
||||
*
|
||||
* The new functions 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(), and g_io_channel_flush() should not be
|
||||
* mixed with the deprecated functions g_io_channel_read(),
|
||||
* g_io_channel_write(), and g_io_channel_seek() on the same channel.
|
||||
**/
|
||||
|
||||
/**
|
||||
* GIOChannel:
|
||||
*
|
||||
* A data structure representing an IO Channel. The fields should be
|
||||
* considered private and should only be accessed with the following
|
||||
* functions.
|
||||
**/
|
||||
|
||||
/**
|
||||
* GIOFuncs:
|
||||
* @io_read: reads raw bytes from the channel. This is called from
|
||||
* various functions such as g_io_channel_read_chars() to
|
||||
* read raw bytes from the channel. Encoding and buffering
|
||||
* issues are dealt with at a higher level.
|
||||
* @io_write: writes raw bytes to the channel. This is called from
|
||||
* various functions such as g_io_channel_write_chars() to
|
||||
* write raw bytes to the channel. Encoding and buffering
|
||||
* issues are dealt with at a higher level.
|
||||
* @io_seek: (optional) seeks the channel. This is called from
|
||||
* g_io_channel_seek() on channels that support it.
|
||||
* @io_close: closes the channel. This is called from
|
||||
* g_io_channel_close() after flushing the buffers.
|
||||
* @io_create_watch: creates a watch on the channel. This call
|
||||
* corresponds directly to g_io_create_watch().
|
||||
* @io_free: called from g_io_channel_unref() when the channel needs to
|
||||
* be freed. This function must free the memory associated
|
||||
* with the channel, including freeing the #GIOChannel
|
||||
* structure itself. The channel buffers have been flushed
|
||||
* and possibly @io_close has been called by the time this
|
||||
* function is called.
|
||||
* @io_set_flags: sets the #GIOFlags on the channel. This is called
|
||||
* from g_io_channel_set_flags() with all flags except
|
||||
* for %G_IO_FLAG_APPEND and %G_IO_FLAG_NONBLOCK masked
|
||||
* out.
|
||||
* @io_get_flags: gets the #GIOFlags for the channel. This function
|
||||
* need only return the %G_IO_FLAG_APPEND and
|
||||
* %G_IO_FLAG_NONBLOCK flags; g_io_channel_get_flags()
|
||||
* automatically adds the others as appropriate.
|
||||
*
|
||||
* A table of functions used to handle different types of #GIOChannel
|
||||
* in a generic way.
|
||||
**/
|
||||
|
||||
/**
|
||||
* GIOStatus:
|
||||
* @G_IO_STATUS_ERROR: An error occurred.
|
||||
* @G_IO_STATUS_NORMAL: Success.
|
||||
* @G_IO_STATUS_EOF: End of file.
|
||||
* @G_IO_STATUS_AGAIN: Resource temporarily unavailable.
|
||||
*
|
||||
* Stati returned by most of the #GIOFuncs functions.
|
||||
**/
|
||||
|
||||
/**
|
||||
* GIOError:
|
||||
* @G_IO_ERROR_NONE: no error
|
||||
* @G_IO_ERROR_AGAIN: an EAGAIN error occurred
|
||||
* @G_IO_ERROR_INVAL: an EINVAL error occurred
|
||||
* @G_IO_ERROR_UNKNOWN: another error occurred
|
||||
*
|
||||
* #GIOError is only used by the deprecated functions
|
||||
* g_io_channel_read(), g_io_channel_write(), and g_io_channel_seek().
|
||||
**/
|
||||
|
||||
#define G_IO_NICE_BUF_SIZE 1024
|
||||
|
||||
/* This needs to be as wide as the largest character in any possible encoding */
|
||||
@ -571,6 +687,31 @@ g_io_add_watch_full (GIOChannel *channel,
|
||||
*
|
||||
* Returns: the event source id
|
||||
*/
|
||||
/**
|
||||
* GIOFunc:
|
||||
* @source: the #GIOChannel event source
|
||||
* @condition: the condition which has been satisfied
|
||||
* @data: user data set in g_io_add_watch() or g_io_add_watch_full()
|
||||
* @Returns: the function should return %FALSE if the event source
|
||||
* should be removed
|
||||
*
|
||||
* Specifies the type of function passed to g_io_add_watch() or
|
||||
* g_io_add_watch_full(), which is called when the requested condition
|
||||
* on a #GIOChannel is satisfied.
|
||||
**/
|
||||
/**
|
||||
* GIOCondition:
|
||||
* @G_IO_IN: There is data to read.
|
||||
* @G_IO_OUT: Data can be written (without blocking).
|
||||
* @G_IO_PRI: There is urgent data to read.
|
||||
* @G_IO_ERR: Error condition.
|
||||
* @G_IO_HUP: Hung up (the connection has been broken, usually for
|
||||
* pipes and sockets).
|
||||
* @G_IO_NVAL: Invalid request. The file descriptor is not open.
|
||||
*
|
||||
* A bitwise combination representing a condition to watch for on an
|
||||
* event source.
|
||||
**/
|
||||
guint
|
||||
g_io_add_watch (GIOChannel *channel,
|
||||
GIOCondition condition,
|
||||
@ -803,6 +944,31 @@ g_io_channel_get_line_term (GIOChannel *channel,
|
||||
*
|
||||
* Return value: the status of the operation.
|
||||
**/
|
||||
/**
|
||||
* GIOFlags:
|
||||
* @G_IO_FLAG_APPEND: turns on append mode, corresponds to %O_APPEND
|
||||
* (see the documentation of the UNIX open()
|
||||
* syscall).
|
||||
* @G_IO_FLAG_NONBLOCK: turns on nonblocking mode, corresponds to
|
||||
* %O_NONBLOCK/%O_NDELAY (see the documentation of
|
||||
* the UNIX open() syscall).
|
||||
* @G_IO_FLAG_IS_READABLE: indicates that the io channel is readable.
|
||||
* This flag can not be changed.
|
||||
* @G_IO_FLAG_IS_WRITEABLE: indicates that the io channel is writable.
|
||||
* This flag can not be changed.
|
||||
* @G_IO_FLAG_IS_SEEKABLE: indicates that the io channel is seekable,
|
||||
* i.e. that g_io_channel_seek_position() can
|
||||
* be used on it. This flag can not be changed.
|
||||
* @G_IO_FLAG_MASK: the mask that specifies all the valid flags.
|
||||
* @G_IO_FLAG_GET_MASK: the mask of the flags that are returned from
|
||||
* g_io_channel_get_flags().
|
||||
* @G_IO_FLAG_SET_MASK: the mask of the flags that the user can modify
|
||||
* with g_io_channel_set_flags().
|
||||
*
|
||||
* Specifies properties of a #GIOChannel. Some of the flags can only be
|
||||
* read with g_io_channel_get_flags(), but not changed with
|
||||
* g_io_channel_set_flags().
|
||||
**/
|
||||
GIOStatus
|
||||
g_io_channel_set_flags (GIOChannel *channel,
|
||||
GIOFlags flags,
|
||||
@ -908,6 +1074,15 @@ g_io_channel_get_close_on_unref (GIOChannel *channel)
|
||||
*
|
||||
* Return value: the status of the operation.
|
||||
**/
|
||||
/**
|
||||
* GSeekType:
|
||||
* @G_SEEK_CUR: the current position in the file.
|
||||
* @G_SEEK_SET: the start of the file.
|
||||
* @G_SEEK_END: the end of the file.
|
||||
*
|
||||
* An enumeration specifying the base position for a
|
||||
* g_io_channel_seek_position() operation.
|
||||
**/
|
||||
GIOStatus
|
||||
g_io_channel_seek_position (GIOChannel *channel,
|
||||
gint64 offset,
|
||||
@ -2379,6 +2554,27 @@ g_io_channel_write_unichar (GIOChannel *channel,
|
||||
*
|
||||
* Return value: the quark used as %G_IO_CHANNEL_ERROR
|
||||
**/
|
||||
/**
|
||||
* G_IO_CHANNEL_ERROR:
|
||||
*
|
||||
* Error domain for #GIOChannel operations. Errors in this domain will
|
||||
* be from the #GIOChannelError enumeration. See #GError for
|
||||
* information on error domains.
|
||||
**/
|
||||
/**
|
||||
* GIOChannelError:
|
||||
* @G_IO_CHANNEL_ERROR_FBIG: File too large.
|
||||
* @G_IO_CHANNEL_ERROR_INVAL: Invalid argument.
|
||||
* @G_IO_CHANNEL_ERROR_IO: IO error.
|
||||
* @G_IO_CHANNEL_ERROR_ISDIR: File is a directory.
|
||||
* @G_IO_CHANNEL_ERROR_NOSPC: No space left on device.
|
||||
* @G_IO_CHANNEL_ERROR_NXIO: No such device or address.
|
||||
* @G_IO_CHANNEL_ERROR_OVERFLOW: Value too large for defined datatype.
|
||||
* @G_IO_CHANNEL_ERROR_PIPE: Broken pipe.
|
||||
* @G_IO_CHANNEL_ERROR_FAILED: Some other error.
|
||||
*
|
||||
* Error codes returned by #GIOChannel operations.
|
||||
**/
|
||||
GQuark
|
||||
g_io_channel_error_quark (void)
|
||||
{
|
||||
|
@ -569,6 +569,32 @@ g_io_channel_new_file (const gchar *filename,
|
||||
return channel;
|
||||
}
|
||||
|
||||
/**
|
||||
* g_io_channel_unix_new:
|
||||
* @fd: a file descriptor.
|
||||
* @Returns: a new #GIOChannel.
|
||||
*
|
||||
* Creates a new #GIOChannel given a file descriptor. On UNIX systems
|
||||
* this works for plain files, pipes, and sockets.
|
||||
*
|
||||
* The returned #GIOChannel has a reference count of 1.
|
||||
*
|
||||
* The default encoding for #GIOChannel is UTF-8. If your application
|
||||
* is reading output from a command using via pipe, you may need to set
|
||||
* the encoding to the encoding of the current locale (see
|
||||
* g_get_charset()) with the g_io_channel_set_encoding() function.
|
||||
*
|
||||
* If you want to read raw binary data without interpretation, then
|
||||
* call the g_io_channel_set_encoding() function with %NULL for the
|
||||
* encoding argument.
|
||||
*
|
||||
* This function is available in GLib on Windows, too, but you should
|
||||
* avoid using it on Windows. The domain of file descriptors and
|
||||
* sockets overlap. There is no way for GLib to know which one you mean
|
||||
* in case the argument you pass to this function happens to be both a
|
||||
* valid file descriptor and socket. If that happens a warning is
|
||||
* issued, and GLib assumes that it is the file descriptor you mean.
|
||||
**/
|
||||
GIOChannel *
|
||||
g_io_channel_unix_new (gint fd)
|
||||
{
|
||||
@ -598,6 +624,16 @@ g_io_channel_unix_new (gint fd)
|
||||
return channel;
|
||||
}
|
||||
|
||||
/**
|
||||
* g_io_channel_unix_get_fd:
|
||||
* @channel: a #GIOChannel, created with g_io_channel_unix_new().
|
||||
* @Returns: the file descriptor of the #GIOChannel.
|
||||
*
|
||||
* Returns the file descriptor of the #GIOChannel.
|
||||
*
|
||||
* On Windows this function returns the file descriptor or socket of
|
||||
* the #GIOChannel.
|
||||
**/
|
||||
gint
|
||||
g_io_channel_unix_get_fd (GIOChannel *channel)
|
||||
{
|
||||
|
@ -1973,6 +1973,16 @@ static GIOFuncs win32_channel_sock_funcs = {
|
||||
g_io_win32_sock_get_flags,
|
||||
};
|
||||
|
||||
/**
|
||||
* g_io_channel_win32_new_messages:
|
||||
* @hwnd: a window handle.
|
||||
* @Returns: a new #GIOChannel.
|
||||
*
|
||||
* Creates a new #GIOChannel given a window handle on Windows.
|
||||
*
|
||||
* This function creates a #GIOChannel that can be used to poll for
|
||||
* Windows messages for the window in question.
|
||||
**/
|
||||
GIOChannel *
|
||||
#if GLIB_SIZEOF_VOID_P == 8
|
||||
g_io_channel_win32_new_messages (gsize hwnd)
|
||||
@ -2036,6 +2046,34 @@ g_io_channel_win32_new_fd_internal (gint fd,
|
||||
return channel;
|
||||
}
|
||||
|
||||
/**
|
||||
* g_io_channel_win32_new_fd:
|
||||
* @fd: a C library file descriptor.
|
||||
* @Returns: a new #GIOChannel.
|
||||
*
|
||||
* Creates a new #GIOChannel given a file descriptor on Windows. This
|
||||
* works for file descriptors from the C runtime.
|
||||
*
|
||||
* This function works for file descriptors as returned by the open(),
|
||||
* creat(), pipe() and fileno() calls in the Microsoft C runtime. In
|
||||
* order to meaningfully use this function your code should use the
|
||||
* same C runtime as GLib uses, which is msvcrt.dll. Note that in
|
||||
* current Microsoft compilers it is near impossible to convince it to
|
||||
* build code that would use msvcrt.dll. The last Microsoft compiler
|
||||
* version that supported using msvcrt.dll as the C runtime was version
|
||||
* 6. The GNU compiler and toolchain for Windows, also known as Mingw,
|
||||
* fully supports msvcrt.dll.
|
||||
*
|
||||
* If you have created a #GIOChannel for a file descriptor and started
|
||||
* watching (polling) it, you shouldn't call read() on the file
|
||||
* descriptor. This is because adding polling for a file descriptor is
|
||||
* implemented in GLib on Windows by starting a thread that sits
|
||||
* blocked in a read() from the file descriptor most of the time. All
|
||||
* reads from the file descriptor should be done by this internal GLib
|
||||
* thread. Your code should call only g_io_channel_read().
|
||||
*
|
||||
* This function is available only in GLib on Windows.
|
||||
**/
|
||||
GIOChannel *
|
||||
g_io_channel_win32_new_fd (gint fd)
|
||||
{
|
||||
@ -2058,6 +2096,20 @@ g_io_channel_win32_get_fd (GIOChannel *channel)
|
||||
return win32_channel->fd;
|
||||
}
|
||||
|
||||
/**
|
||||
* g_io_channel_win32_new_socket:
|
||||
* @socket: a Winsock socket
|
||||
* @Returns: a new #GIOChannel
|
||||
*
|
||||
* Creates a new #GIOChannel given a socket on Windows.
|
||||
*
|
||||
* This function works for sockets created by Winsock. It's available
|
||||
* only in GLib on Windows.
|
||||
*
|
||||
* Polling a #GSource created to watch a channel for a socket puts the
|
||||
* socket in non-blocking mode. This is a side-effect of the
|
||||
* implementation and unavoidable.
|
||||
**/
|
||||
GIOChannel *
|
||||
g_io_channel_win32_new_socket (int socket)
|
||||
{
|
||||
|
Loading…
x
Reference in New Issue
Block a user