iochannels.sgml

GLib是GTK+和GNOME工程的基础底层核心程序库

<entry>user data set in <link linkend="g-io-add-watch">g_io_add_watch</link>() or <link linkend="g-io-add-watch-full">g_io_add_watch_full</link>().
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>the function should return <literal>FALSE</literal> if the event source should be
removed.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="GIOFuncs">struct GIOFuncs</title>
<programlisting>struct GIOFuncs
{
  GIOStatus (*io_read)           (GIOChannel   *channel, 
			          gchar        *buf, 
				  gsize         count,
				  gsize        *bytes_read,
				  GError      **err);
  GIOStatus (*io_write)          (GIOChannel   *channel, 
				  const gchar  *buf, 
				  gsize         count,
				  gsize        *bytes_written,
				  GError      **err);
  GIOStatus (*io_seek)           (GIOChannel   *channel, 
				  gint64        offset, 
				  GSeekType     type,
				  GError      **err);
  GIOStatus  (*io_close)         (GIOChannel   *channel,
				  GError      **err);
  GSource*   (*io_create_watch)  (GIOChannel   *channel,
				  GIOCondition  condition);
  void       (*io_free)          (GIOChannel   *channel);
  GIOStatus  (*io_set_flags)     (GIOChannel   *channel,
                                  GIOFlags      flags,
				  GError      **err);
  GIOFlags   (*io_get_flags)     (GIOChannel   *channel);
};
</programlisting>
<para>
A table of functions used to handle different types of <link linkend="GIOChannel">GIOChannel</link> in a
generic way.
</para></refsect2>
<refsect2>
<title><anchor id="g-io-channel-get-buffer-size">g_io_channel_get_buffer_size ()</title>
<programlisting><link linkend="gsize">gsize</link>       g_io_channel_get_buffer_size    (<link linkend="GIOChannel">GIOChannel</link> *channel);</programlisting>
<para>
Gets the buffer size.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>channel</parameter>&nbsp;:</entry>
<entry> a <link linkend="GIOChannel">GIOChannel</link>
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> the size of the buffer.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-io-channel-set-buffer-size">g_io_channel_set_buffer_size ()</title>
<programlisting>void        g_io_channel_set_buffer_size    (<link linkend="GIOChannel">GIOChannel</link> *channel,
                                             <link linkend="gsize">gsize</link> size);</programlisting>
<para>
Sets the buffer size.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>channel</parameter>&nbsp;:</entry>
<entry> a <link linkend="GIOChannel">GIOChannel</link>
</entry></row>
<row><entry align="right"><parameter>size</parameter>&nbsp;:</entry>
<entry> the size of the buffer. 0 == pick a good size
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-io-channel-get-buffer-condition">g_io_channel_get_buffer_condition ()</title>
<programlisting><link linkend="GIOCondition">GIOCondition</link> g_io_channel_get_buffer_condition
                                            (<link linkend="GIOChannel">GIOChannel</link> *channel);</programlisting>
<para>
This function returns a <link linkend="GIOCondition">GIOCondition</link> depending on whether there
is data to be read/space to write data in the
internal buffers in the <link linkend="GIOChannel">GIOChannel</link>. Only the flags <literal>G_IO_IN</literal> and
<literal>G_IO_OUT</literal> may be set.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>channel</parameter>&nbsp;:</entry>
<entry> A <link linkend="GIOChannel">GIOChannel</link>
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> A <link linkend="GIOCondition">GIOCondition</link>
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-io-channel-get-flags">g_io_channel_get_flags ()</title>
<programlisting><link linkend="GIOFlags">GIOFlags</link>    g_io_channel_get_flags          (<link linkend="GIOChannel">GIOChannel</link> *channel);</programlisting>
<para>
Gets the current flags for a <link linkend="GIOChannel">GIOChannel</link>, including read-only
flags such as <literal>G_IO_FLAG_IS_READABLE</literal>.
</para>
<para>
The values of the flags <literal>G_IO_FLAG_IS_READABLE</literal> and <literal>G_IO_FLAG_IS_WRITEABLE</literal>
are cached for internal use by the channel when it is created.
If they should change at some later point (e.g. partial shutdown
of a socket with the UNIX <function><link linkend="shutdown">shutdown</link>()</function> function), the user
should immediately call <link linkend="g-io-channel-get-flags">g_io_channel_get_flags</link>() to update
the internal values of these flags.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>channel</parameter>&nbsp;:</entry>
<entry> a <link linkend="GIOChannel">GIOChannel</link>
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> the flags which are set on the channel
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-io-channel-set-flags">g_io_channel_set_flags ()</title>
<programlisting><link linkend="GIOStatus">GIOStatus</link>   g_io_channel_set_flags          (<link linkend="GIOChannel">GIOChannel</link> *channel,
                                             <link linkend="GIOFlags">GIOFlags</link> flags,
                                             <link linkend="GError">GError</link> **error);</programlisting>
<para>
Sets the (writeable) flags in <parameter>channel</parameter> to (<parameter>flags</parameter> & <literal>G_IO_CHANNEL_SET_MASK</literal>).</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>channel</parameter>&nbsp;:</entry>
<entry> a <link linkend="GIOChannel">GIOChannel</link>.
</entry></row>
<row><entry align="right"><parameter>flags</parameter>&nbsp;:</entry>
<entry> the flags to set on the IO channel.
</entry></row>
<row><entry align="right"><parameter>error</parameter>&nbsp;:</entry>
<entry> A location to return an error of type <link linkend="GIOChannelError">GIOChannelError</link>.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> the status of the operation. 
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="GIOFlags">enum GIOFlags</title>
<programlisting>typedef enum
{
  G_IO_FLAG_APPEND = 1 &lt;&lt; 0,
  G_IO_FLAG_NONBLOCK = 1 &lt;&lt; 1,
  G_IO_FLAG_IS_READABLE = 1 &lt;&lt; 2,	/* Read only flag */
  G_IO_FLAG_IS_WRITEABLE = 1 &lt;&lt; 3,	/* Read only flag */
  G_IO_FLAG_IS_SEEKABLE = 1 &lt;&lt; 4,	/* Read only flag */
  G_IO_FLAG_MASK = (1 &lt;&lt; 5) - 1,
  G_IO_FLAG_GET_MASK = G_IO_FLAG_MASK,
  G_IO_FLAG_SET_MASK = G_IO_FLAG_APPEND | G_IO_FLAG_NONBLOCK
} GIOFlags;
</programlisting>
<para>
Specifies properties of a <link linkend="GIOChannel">GIOChannel</link>. Some of the flags can only
be read with <link linkend="g-io-channel-get-flags">g_io_channel_get_flags</link>(), but not changed with
<link linkend="g-io-channel-set-flags">g_io_channel_set_flags</link>(). 
</para><informaltable pgwide="1" frame="none" role="enum">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row>
<entry><literal>G_IO_FLAG_APPEND</literal></entry>
<entry>turns on append mode, corresponds to <literal>O_APPEND</literal> (see the 
   documentation of the UNIX <function><link linkend="open">open</link>()</function> syscall).
</entry>
</row>
<row>
<entry><literal>G_IO_FLAG_NONBLOCK</literal></entry>
<entry>turns on nonblocking mode, corresponds to 
   <literal>O_NONBLOCK</literal>/<literal>O_NDELAY</literal> (see the documentation of the UNIX 
   <function><link linkend="open">open</link>()</function> syscall).
</entry>
</row>
<row>
<entry><literal>G_IO_FLAG_IS_READABLE</literal></entry>
<entry>indicates that the io channel is readable. This flag 
   can not be changed.
</entry>
</row>
<row>
<entry><literal>G_IO_FLAG_IS_WRITEABLE</literal></entry>
<entry>indicates that the io channel is writable. This flag 
   can not be changed.
</entry>
</row>
<row>
<entry><literal>G_IO_FLAG_IS_SEEKABLE</literal></entry>
<entry>indicates that the io channel is seekable, i.e. that 
   <link linkend="g-io-channel-seek-position">g_io_channel_seek_position</link>() can be used on it. This flag can not be changed.
</entry>
</row>
<row>
<entry><literal>G_IO_FLAG_MASK</literal></entry>
<entry>
</entry>
</row>
<row>
<entry><literal>G_IO_FLAG_GET_MASK</literal></entry>
<entry>
</entry>
</row>
<row>
<entry><literal>G_IO_FLAG_SET_MASK</literal></entry>
<entry>

</entry>
</row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-io-channel-get-line-term">g_io_channel_get_line_term ()</title>
<programlisting>G_CONST_RETURN <link linkend="gchar">gchar</link>* g_io_channel_get_line_term
                                            (<link linkend="GIOChannel">GIOChannel</link> *channel,
                                             <link linkend="gint">gint</link> *length);</programlisting>
<para>
This returns the string that <link linkend="GIOChannel">GIOChannel</link> uses to determine
where in the file a line break occurs. A value of <literal>NULL</literal>
indicates auto detection.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>channel</parameter>&nbsp;:</entry>
<entry> a <link linkend="GIOChannel">GIOChannel</link>
</entry></row>
<row><entry align="right"><parameter>length</parameter>&nbsp;:</entry>
<entry> a location to return the length of the line terminator
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> The line termination string. This value
  is owned by GLib and must not be freed.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-io-channel-set-line-term">g_io_channel_set_line_term ()</title>
<programlisting>void        g_io_channel_set_line_term      (<link linkend="GIOChannel">GIOChannel</link> *channel,
                                             const <link linkend="gchar">gchar</link> *line_term,
                                             <link linkend="gint"