luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2025-05-20 12:32:10 +02:00
Code Issues Packages Projects Releases Wiki Activity

Document some Windows-specific issues.

Browse Source 
2006-02-14  Tor Lillqvist  <tml@novell.com>

	* 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.
This commit is contained in:
Tor Lillqvist 2006-02-20 10:56:13 +00:00 committed by Tor Lillqvist
parent 26ab00418e
commit 7cd4460372
3 changed files with 91 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
docs/reference/ChangeLog
View File

@ -1,3 +1,10 @@
2006-02-14 Tor Lillqvist <tml@novell.com>
* 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 <mclasen@redhat.com>
* === Released 2.9.6 ===

6
docs/reference/glib/glib-sections.txt
View File

@ -695,6 +695,9 @@ GIOChannel
<SUBSECTION>
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
<SUBSECTION>
g_io_channel_init
@ -750,9 +753,6 @@ g_io_channel_get_close_on_unref
g_io_channel_set_close_on_unref
<SUBSECTION Private>
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

82
docs/reference/glib/tmpl/iochannels.sgml
View File

@ -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.
</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_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>
@fd: 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_unix_get_fd ##### -->
<para>
Returns the file descriptor of the UNIX #GIOChannel.
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().
@ -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.
</para>
<para>
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.
</para>
@channel: a #GIOChannel to watch
@condition: conditions to watch for