From 7cd44603720710b41c703e571eb31cc3a36b468f Mon Sep 17 00:00:00 2001 From: Tor Lillqvist Date: Mon, 20 Feb 2006 10:56:13 +0000 Subject: [PATCH] Document some Windows-specific issues. 2006-02-14 Tor Lillqvist * glib/tmpl/iochannels.sgml: Document some Windows-specific issues. * glib/glib-sections.txt: Move three Windows-specific functions that now are documented from being Private to the correct section. --- docs/reference/ChangeLog | 7 +++ docs/reference/glib/glib-sections.txt | 6 +-- docs/reference/glib/tmpl/iochannels.sgml | 82 +++++++++++++++++++++++++++++++- 3 files changed, 91 insertions(+), 4 deletions(-) diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog index c2e9ac5..c81f452 100644 --- a/docs/reference/ChangeLog +++ b/docs/reference/ChangeLog @@ -1,3 +1,10 @@ +2006-02-14 Tor Lillqvist + + * glib/tmpl/iochannels.sgml: Document some Windows-specific issues. + + * glib/glib-sections.txt: Move three Windows-specific functions + that now are documented from being Private to the correct section. + 2006-02-10 Matthias Clasen * === Released 2.9.6 === diff --git a/docs/reference/glib/glib-sections.txt b/docs/reference/glib/glib-sections.txt index 09efd20..ed5bb20 100644 --- a/docs/reference/glib/glib-sections.txt +++ b/docs/reference/glib/glib-sections.txt @@ -695,6 +695,9 @@ GIOChannel g_io_channel_unix_new g_io_channel_unix_get_fd +g_io_channel_win32_new_fd +g_io_channel_win32_new_socket +g_io_channel_win32_new_messages g_io_channel_init @@ -750,9 +753,6 @@ g_io_channel_get_close_on_unref g_io_channel_set_close_on_unref -g_io_channel_win32_new_fd -g_io_channel_win32_new_messages -g_io_channel_win32_new_socket g_io_channel_win32_poll g_io_channel_win32_make_pollfd g_io_channel_win32_get_fd diff --git a/docs/reference/glib/tmpl/iochannels.sgml b/docs/reference/glib/tmpl/iochannels.sgml index f1344da..4f54c52 100644 --- a/docs/reference/glib/tmpl/iochannels.sgml +++ b/docs/reference/glib/tmpl/iochannels.sgml @@ -93,14 +93,89 @@ 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. + + +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. + + +@fd: 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. + + -Returns the file descriptor of the UNIX #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(). @@ -323,6 +398,11 @@ when there's data available for reading. g_io_add_watch() is a simpler interface to this same functionality, for the case where you want to add the source to the default main loop at the default priority. + +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. + @channel: a #GIOChannel to watch @condition: conditions to watch for -- 2.7.4