From 4bdf7d12a8ef7e027dced8d0da46986c2009180e Mon Sep 17 00:00:00 2001 From: Ryan Lortie Date: Sun, 31 Jan 2010 00:39:40 -0500 Subject: [PATCH] GIOChannel: move docs from tmpl to .c --- docs/reference/glib/tmpl/.gitignore | 1 + docs/reference/glib/tmpl/iochannels.sgml | 666 ----------------------- glib/giochannel.c | 196 +++++++ glib/giounix.c | 36 ++ glib/giowin32.c | 52 ++ 5 files changed, 285 insertions(+), 666 deletions(-) delete mode 100644 docs/reference/glib/tmpl/iochannels.sgml diff --git a/docs/reference/glib/tmpl/.gitignore b/docs/reference/glib/tmpl/.gitignore index b942d63fe..104579761 100644 --- a/docs/reference/glib/tmpl/.gitignore +++ b/docs/reference/glib/tmpl/.gitignore @@ -9,6 +9,7 @@ ghostutils.sgml gurifuncs.sgml gvarianttype.sgml hash_tables.sgml +iochannels.sgml memory_chunks.sgml option.sgml patterns.sgml diff --git a/docs/reference/glib/tmpl/iochannels.sgml b/docs/reference/glib/tmpl/iochannels.sgml deleted file mode 100644 index 96a01f32f..000000000 --- a/docs/reference/glib/tmpl/iochannels.sgml +++ /dev/null @@ -1,666 +0,0 @@ - -IO Channels - - -portable support for using files, pipes and sockets - - - -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. -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 -main event loop -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. - - - - - - - -gtk_input_add_full(), gtk_input_remove(), gdk_input_add(), -gdk_input_add_full(), gdk_input_remove() - -Convenience functions for creating #GIOChannel instances and adding them to the -main event loop. - - - - - - - - - - - -A data structure representing an IO Channel. The fields should be considered -private and should only be accessed with the following functions. - - - - - -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. - - -@fd: a file descriptor. -@Returns: a new #GIOChannel. - - - - -Returns the file descriptor of the #GIOChannel. - - -On Windows this function returns the file descriptor or socket of the #GIOChannel. - - -@channel: a #GIOChannel, created with g_io_channel_unix_new(). -@Returns: the file descriptor of the #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. - - -@fd: a C library file descriptor. -@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. - - -@socket: a Winsock socket -@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. - - -@hwnd: a window handle. -@Returns: a new #GIOChannel. - - - - - - - -@channel: - - - - - - -@filename: -@mode: -@error: -@Returns: - - - - - - - -@channel: -@buf: -@count: -@bytes_read: -@error: -@Returns: - - - - - - - -@channel: -@thechar: -@error: -@Returns: - - - - - - - -@channel: -@str_return: -@length: -@terminator_pos: -@error: -@Returns: - - - - - - - -@channel: -@buffer: -@terminator_pos: -@error: -@Returns: - - - - - - - -@channel: -@str_return: -@length: -@error: -@Returns: - - - - - - - -@channel: -@buf: -@count: -@bytes_written: -@error: -@Returns: - - - - - - - -@channel: -@thechar: -@error: -@Returns: - - - - - - - -@channel: -@error: -@Returns: - - - - - - - -@channel: -@offset: -@type: -@error: -@Returns: - - - - -An enumeration specifying the base position for a g_io_channel_seek_position() -operation. - - -@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. - - - - - - -@channel: -@flush: -@err: -@Returns: - - - - -Stati returned by most of the #GIOFuncs functions. - - -@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. - - - -Error codes returned by #GIOChannel operations. - - -@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 domain for #GIOChannel operations. Errors in this domain will -be from the #GIOChannelError enumeration. See #GError for information on -error domains. - - - - - - - - - -@en: -@Returns: - - - - - - - -@channel: -@Returns: - - - - - - - -@channel: - - - - - - - -@channel: -@condition: -@Returns: - - - - - - - -@channel: -@condition: -@func: -@user_data: -@Returns: - - - - - - - -@channel: -@priority: -@condition: -@func: -@user_data: -@notify: -@Returns: - - - - -A bitwise combination representing a condition to watch for on -an event source. - - -@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. - - - -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. - - -@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 - - - - -A table of functions used to handle different types of #GIOChannel -in a generic way. - - -@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. - - - - - - -@channel: -@Returns: - - - - - - - -@channel: -@size: - - - - - - - -@channel: -@Returns: - - - - - - - -@channel: -@Returns: - - - - - - - -@channel: -@flags: -@error: -@Returns: - - - - -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(). - - -@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(). - - - - - - -@channel: -@length: -@Returns: - - - - - - - -@channel: -@line_term: -@length: - - - - - - - -@channel: -@Returns: - - - - - - - -@channel: -@buffered: - - - - - - - -@channel: -@Returns: - - - - - - - -@channel: -@encoding: -@error: -@Returns: - - - - - - - -@channel: -@Returns: - - - - - - - -@channel: -@do_close: - - - - - - -@channel: -@buf: -@count: -@bytes_read: -@Returns: - - - - -#GIOError is only used by the deprecated functions g_io_channel_read(), -g_io_channel_write(), and g_io_channel_seek(). - - -@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 - - - - - -@channel: -@buf: -@count: -@bytes_written: -@Returns: - - - - - - -@channel: -@offset: -@type. -@type: -@Returns: - - - - - - -@channel: - - diff --git a/glib/giochannel.c b/glib/giochannel.c index 537fdb654..358bac6e7 100644 --- a/glib/giochannel.c +++ b/glib/giochannel.c @@ -50,6 +50,122 @@ #include "galias.h" +/** + * SECTION: iochannels + * @title: IO Channels + * @short_description: portable support for using files, pipes and + * sockets + * @see_also: + * gtk_input_add_full(), gtk_input_remove(), + * gdk_input_add(), gdk_input_add_full(), + * gdk_input_remove() Convenience + * functions for creating #GIOChannel instances and adding + * them to the main + * event loop. + * + * + * 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. 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 main event loop 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) { diff --git a/glib/giounix.c b/glib/giounix.c index eaff939ae..0e89d5c15 100644 --- a/glib/giounix.c +++ b/glib/giounix.c @@ -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) { diff --git a/glib/giowin32.c b/glib/giowin32.c index d661865d3..07c9c5f8d 100644 --- a/glib/giowin32.c +++ b/glib/giowin32.c @@ -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) {