| <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> |
| <html> |
| <head> |
| <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> |
| <title>GConverter</title> |
| <meta name="generator" content="DocBook XSL Stylesheets V1.75.2"> |
| <link rel="home" href="index.html" title="GIO Reference Manual"> |
| <link rel="up" href="conversion.html" title="Data conversion"> |
| <link rel="prev" href="conversion.html" title="Data conversion"> |
| <link rel="next" href="GCharsetConverter.html" title="GCharsetConverter"> |
| <meta name="generator" content="GTK-Doc V1.14 (XML mode)"> |
| <link rel="stylesheet" href="style.css" type="text/css"> |
| </head> |
| <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> |
| <table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2"> |
| <tr valign="middle"> |
| <td><a accesskey="p" href="conversion.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td> |
| <td><a accesskey="u" href="conversion.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td> |
| <td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td> |
| <th width="100%" align="center">GIO Reference Manual</th> |
| <td><a accesskey="n" href="GCharsetConverter.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td> |
| </tr> |
| <tr><td colspan="5" class="shortcuts"> |
| <a href="#GConverter.synopsis" class="shortcut">Top</a> |
| | |
| <a href="#GConverter.description" class="shortcut">Description</a> |
| | |
| <a href="#GConverter.object-hierarchy" class="shortcut">Object Hierarchy</a> |
| | |
| <a href="#GConverter.prerequisites" class="shortcut">Prerequisites</a> |
| | |
| <a href="#GConverter.implementations" class="shortcut">Known Implementations</a> |
| </td></tr> |
| </table> |
| <div class="refentry" title="GConverter"> |
| <a name="GConverter"></a><div class="titlepage"></div> |
| <div class="refnamediv"><table width="100%"><tr> |
| <td valign="top"> |
| <h2><span class="refentrytitle"><a name="GConverter.top_of_page"></a>GConverter</span></h2> |
| <p>GConverter — Data conversion interface</p> |
| </td> |
| <td valign="top" align="right"></td> |
| </tr></table></div> |
| <div class="refsynopsisdiv" title="Synopsis"> |
| <a name="GConverter.synopsis"></a><h2>Synopsis</h2> |
| <pre class="synopsis"> |
| #include <gio/gio.h> |
| |
| <a class="link" href="GConverter.html#GConverter-struct" title="GConverter">GConverter</a>; |
| <a class="link" href="GConverter.html#GConverterIface" title="GConverterIface">GConverterIface</a>; |
| enum <a class="link" href="GConverter.html#GConverterResult" title="enum GConverterResult">GConverterResult</a>; |
| <a class="link" href="GConverter.html#GConverterResult" title="enum GConverterResult"><span class="returnvalue">GConverterResult</span></a> <a class="link" href="GConverter.html#g-converter-convert" title="g_converter_convert ()">g_converter_convert</a> (<em class="parameter"><code><a class="link" href="GConverter.html" title="GConverter"><span class="type">GConverter</span></a> *converter</code></em>, |
| <em class="parameter"><code>const <span class="type">void</span> *inbuf</code></em>, |
| <em class="parameter"><code><a href="/usr/share/gtk-doc/html/glib/glib-Basic-Types.html#gsize"><span class="type">gsize</span></a> inbuf_size</code></em>, |
| <em class="parameter"><code><span class="type">void</span> *outbuf</code></em>, |
| <em class="parameter"><code><a href="/usr/share/gtk-doc/html/glib/glib-Basic-Types.html#gsize"><span class="type">gsize</span></a> outbuf_size</code></em>, |
| <em class="parameter"><code><span class="type">GConverterFlags</span> flags</code></em>, |
| <em class="parameter"><code><a href="/usr/share/gtk-doc/html/glib/glib-Basic-Types.html#gsize"><span class="type">gsize</span></a> *bytes_read</code></em>, |
| <em class="parameter"><code><a href="/usr/share/gtk-doc/html/glib/glib-Basic-Types.html#gsize"><span class="type">gsize</span></a> *bytes_written</code></em>, |
| <em class="parameter"><code><a href="/usr/share/gtk-doc/html/glib/glib-Error-Reporting.html#GError"><span class="type">GError</span></a> **error</code></em>); |
| <span class="returnvalue">void</span> <a class="link" href="GConverter.html#g-converter-reset" title="g_converter_reset ()">g_converter_reset</a> (<em class="parameter"><code><a class="link" href="GConverter.html" title="GConverter"><span class="type">GConverter</span></a> *converter</code></em>); |
| </pre> |
| </div> |
| <div class="refsect1" title="Object Hierarchy"> |
| <a name="GConverter.object-hierarchy"></a><h2>Object Hierarchy</h2> |
| <pre class="synopsis"> |
| GInterface |
| +----GConverter |
| </pre> |
| </div> |
| <div class="refsect1" title="Prerequisites"> |
| <a name="GConverter.prerequisites"></a><h2>Prerequisites</h2> |
| <p> |
| GConverter requires |
| <a href="/usr/share/gtk-doc/html/gobject/gobject-The-Base-Object-Type.html#GObject">GObject</a>.</p> |
| </div> |
| <div class="refsect1" title="Known Implementations"> |
| <a name="GConverter.implementations"></a><h2>Known Implementations</h2> |
| <p> |
| GConverter is implemented by |
| <a class="link" href="GCharsetConverter.html" title="GCharsetConverter">GCharsetConverter</a>, <a class="link" href="GZlibCompressor.html" title="GZlibCompressor">GZlibCompressor</a> and <a class="link" href="GZlibDecompressor.html" title="GZlibDecompressor">GZlibDecompressor</a>.</p> |
| </div> |
| <div class="refsect1" title="Description"> |
| <a name="GConverter.description"></a><h2>Description</h2> |
| <p> |
| <a class="link" href="GConverter.html" title="GConverter"><span class="type">GConverter</span></a> is implemented by objects that convert |
| binary data in various ways. The conversion can be |
| stateful and may fail at any place. |
| </p> |
| <p> |
| Some example conversions are: character set conversion, |
| compression, decompression and regular expression |
| replace. |
| </p> |
| </div> |
| <div class="refsect1" title="Details"> |
| <a name="GConverter.details"></a><h2>Details</h2> |
| <div class="refsect2" title="GConverter"> |
| <a name="GConverter-struct"></a><h3>GConverter</h3> |
| <pre class="programlisting">typedef struct _GConverter GConverter;</pre> |
| <p> |
| Seek object for streaming operations. |
| </p> |
| <p class="since">Since 2.24</p> |
| </div> |
| <hr> |
| <div class="refsect2" title="GConverterIface"> |
| <a name="GConverterIface"></a><h3>GConverterIface</h3> |
| <pre class="programlisting">typedef struct { |
| GTypeInterface g_iface; |
| |
| /* Virtual Table */ |
| |
| GConverterResult (* convert) (GConverter *converter, |
| const void *inbuf, |
| gsize inbuf_size, |
| void *outbuf, |
| gsize outbuf_size, |
| GConverterFlags flags, |
| gsize *bytes_read, |
| gsize *bytes_written, |
| GError **error); |
| void (* reset) (GConverter *converter); |
| } GConverterIface; |
| </pre> |
| <p> |
| Provides an interface for converting data from one type |
| to another type. The conversion can be stateful |
| and may fail at any place. |
| </p> |
| <div class="variablelist"><table border="0"> |
| <col align="left" valign="top"> |
| <tbody> |
| <tr> |
| <td><p><span class="term"><a href="/usr/share/gtk-doc/html/gobject/gobject-Type-Information.html#GTypeInterface"><span class="type">GTypeInterface</span></a> <em class="structfield"><code><a name="GConverterIface.g-iface"></a>g_iface</code></em>;</span></p></td> |
| <td>The parent interface. |
| </td> |
| </tr> |
| <tr> |
| <td><p><span class="term"><em class="structfield"><code><a name="GConverterIface.convert"></a>convert</code></em> ()</span></p></td> |
| <td>Converts data. |
| </td> |
| </tr> |
| <tr> |
| <td><p><span class="term"><em class="structfield"><code><a name="GConverterIface.reset"></a>reset</code></em> ()</span></p></td> |
| <td>Reverts the internal state of the converter to its initial state. |
| </td> |
| </tr> |
| </tbody> |
| </table></div> |
| <p class="since">Since 2.24</p> |
| </div> |
| <hr> |
| <div class="refsect2" title="enum GConverterResult"> |
| <a name="GConverterResult"></a><h3>enum GConverterResult</h3> |
| <pre class="programlisting">typedef enum { |
| G_CONVERTER_ERROR = 0, /*< nick=error >*/ |
| G_CONVERTER_CONVERTED = 1, /*< nick=converted >*/ |
| G_CONVERTER_FINISHED = 2, /*< nick=finished >*/ |
| G_CONVERTER_FLUSHED = 3 /*< nick=flushed >*/ |
| } GConverterResult; |
| </pre> |
| <p> |
| Results returned from <a class="link" href="GConverter.html#g-converter-convert" title="g_converter_convert ()"><code class="function">g_converter_convert()</code></a>. |
| </p> |
| <div class="variablelist"><table border="0"> |
| <col align="left" valign="top"> |
| <tbody> |
| <tr> |
| <td><p><a name="G-CONVERTER-ERROR:CAPS"></a><span class="term"><code class="literal">G_CONVERTER_ERROR</code></span></p></td> |
| <td>There was an error during conversion. |
| </td> |
| </tr> |
| <tr> |
| <td><p><a name="G-CONVERTER-CONVERTED:CAPS"></a><span class="term"><code class="literal">G_CONVERTER_CONVERTED</code></span></p></td> |
| <td>Some data was consumed or produced |
| </td> |
| </tr> |
| <tr> |
| <td><p><a name="G-CONVERTER-FINISHED:CAPS"></a><span class="term"><code class="literal">G_CONVERTER_FINISHED</code></span></p></td> |
| <td>The conversion is finished |
| </td> |
| </tr> |
| <tr> |
| <td><p><a name="G-CONVERTER-FLUSHED:CAPS"></a><span class="term"><code class="literal">G_CONVERTER_FLUSHED</code></span></p></td> |
| <td>Flushing is finished |
| </td> |
| </tr> |
| </tbody> |
| </table></div> |
| <p class="since">Since 2.24</p> |
| </div> |
| <hr> |
| <div class="refsect2" title="g_converter_convert ()"> |
| <a name="g-converter-convert"></a><h3>g_converter_convert ()</h3> |
| <pre class="programlisting"><a class="link" href="GConverter.html#GConverterResult" title="enum GConverterResult"><span class="returnvalue">GConverterResult</span></a> g_converter_convert (<em class="parameter"><code><a class="link" href="GConverter.html" title="GConverter"><span class="type">GConverter</span></a> *converter</code></em>, |
| <em class="parameter"><code>const <span class="type">void</span> *inbuf</code></em>, |
| <em class="parameter"><code><a href="/usr/share/gtk-doc/html/glib/glib-Basic-Types.html#gsize"><span class="type">gsize</span></a> inbuf_size</code></em>, |
| <em class="parameter"><code><span class="type">void</span> *outbuf</code></em>, |
| <em class="parameter"><code><a href="/usr/share/gtk-doc/html/glib/glib-Basic-Types.html#gsize"><span class="type">gsize</span></a> outbuf_size</code></em>, |
| <em class="parameter"><code><span class="type">GConverterFlags</span> flags</code></em>, |
| <em class="parameter"><code><a href="/usr/share/gtk-doc/html/glib/glib-Basic-Types.html#gsize"><span class="type">gsize</span></a> *bytes_read</code></em>, |
| <em class="parameter"><code><a href="/usr/share/gtk-doc/html/glib/glib-Basic-Types.html#gsize"><span class="type">gsize</span></a> *bytes_written</code></em>, |
| <em class="parameter"><code><a href="/usr/share/gtk-doc/html/glib/glib-Error-Reporting.html#GError"><span class="type">GError</span></a> **error</code></em>);</pre> |
| <p> |
| This is the main operation used when converting data. It is to be called |
| multiple times in a loop, and each time it will do some work, i.e. |
| producing some output (in <em class="parameter"><code>outbuf</code></em>) or consuming some input (from <em class="parameter"><code>inbuf</code></em>) or |
| both. If its not possible to do any work an error is returned. |
| </p> |
| <p> |
| Note that a single call may not consume all input (or any input at all). |
| Also a call may produce output even if given no input, due to state stored |
| in the converter producing output. |
| </p> |
| <p> |
| If any data was either produced or consumed, and then an error happens, then |
| only the successful conversion is reported and the error is returned on the |
| next call. |
| </p> |
| <p> |
| A full conversion loop involves calling this method repeatedly, each time |
| giving it new input and space output space. When there is no more input |
| data after the data in <em class="parameter"><code>inbuf</code></em>, the flag <code class="literal">G_CONVERTER_INPUT_AT_END</code> must be set. |
| The loop will be (unless some error happens) returning <a class="link" href="GConverter.html#G-CONVERTER-CONVERTED:CAPS"><code class="literal">G_CONVERTER_CONVERTED</code></a> |
| each time until all data is consumed and all output is produced, then |
| <a class="link" href="GConverter.html#G-CONVERTER-FINISHED:CAPS"><code class="literal">G_CONVERTER_FINISHED</code></a> is returned instead. Note, that <a class="link" href="GConverter.html#G-CONVERTER-FINISHED:CAPS"><code class="literal">G_CONVERTER_FINISHED</code></a> |
| may be returned even if <code class="literal">G_CONVERTER_INPUT_AT_END</code> is not set, for instance |
| in a decompression converter where the end of data is detectable from the |
| data (and there might even be other data after the end of the compressed data). |
| </p> |
| <p> |
| When some data has successfully been converted <em class="parameter"><code>bytes_read</code></em> and is set to |
| the number of bytes read from <em class="parameter"><code>inbuf</code></em>, and <em class="parameter"><code>bytes_written</code></em> is set to indicate |
| how many bytes was written to <em class="parameter"><code>outbuf</code></em>. If there are more data to output |
| or consume (i.e. unless the G_CONVERTER_INPUT_AT_END is specified) then |
| G_CONVERTER_CONVERTED is returned, and if no more data is to be output |
| then G_CONVERTER_FINISHED is returned. |
| </p> |
| <p> |
| On error <a class="link" href="GConverter.html#G-CONVERTER-ERROR:CAPS"><code class="literal">G_CONVERTER_ERROR</code></a> is returned and <em class="parameter"><code>error</code></em> is set accordingly. |
| Some errors need special handling: |
| </p> |
| <p> |
| <a class="link" href="gio-GIOError.html#G-IO-ERROR-NO-SPACE:CAPS"><code class="literal">G_IO_ERROR_NO_SPACE</code></a> is returned if there is not enough space |
| to write the resulting converted data, the application should |
| call the function again with a larger <em class="parameter"><code>outbuf</code></em> to continue. |
| </p> |
| <p> |
| <a class="link" href="gio-GIOError.html#G-IO-ERROR-PARTIAL-INPUT:CAPS"><code class="literal">G_IO_ERROR_PARTIAL_INPUT</code></a> is returned if there is not enough |
| input to fully determine what the conversion should produce, |
| and the <code class="literal">G_CONVERTER_INPUT_AT_END</code> flag is not set. This happens for |
| example with an incomplete multibyte sequence when converting text, |
| or when a regexp matches up to the end of the input (and may match |
| further input). It may also happen when <em class="parameter"><code>inbuf_size</code></em> is zero and |
| there is no more data to produce. |
| </p> |
| <p> |
| When this happens the application should read more input and then |
| call the function again. If further input shows that there is no |
| more data call the function again with the same data but with |
| the <code class="literal">G_CONVERTER_INPUT_AT_END</code> flag set. This may cause the conversion |
| to finish as e.g. in the regexp match case (or, to fail again with |
| <a class="link" href="gio-GIOError.html#G-IO-ERROR-PARTIAL-INPUT:CAPS"><code class="literal">G_IO_ERROR_PARTIAL_INPUT</code></a> in e.g. a charset conversion where the |
| input is actually partial). |
| </p> |
| <p> |
| After <a class="link" href="GConverter.html#g-converter-convert" title="g_converter_convert ()"><code class="function">g_converter_convert()</code></a> has returned <a class="link" href="GConverter.html#G-CONVERTER-FINISHED:CAPS"><code class="literal">G_CONVERTER_FINISHED</code></a> the |
| converter object is in an invalid state where its not allowed |
| to call <a class="link" href="GConverter.html#g-converter-convert" title="g_converter_convert ()"><code class="function">g_converter_convert()</code></a> anymore. At this time you can only |
| free the object or call <a class="link" href="GConverter.html#g-converter-reset" title="g_converter_reset ()"><code class="function">g_converter_reset()</code></a> to reset it to the |
| initial state. |
| </p> |
| <p> |
| If the flag <code class="literal">G_CONVERTER_FLUSH</code> is set then conversion is modified |
| to try to write out all internal state to the output. The application |
| has to call the function multiple times with the flag set, and when |
| the availible input has been consumed and all internal state has |
| been produced then <a class="link" href="GConverter.html#G-CONVERTER-FLUSHED:CAPS"><code class="literal">G_CONVERTER_FLUSHED</code></a> (or <a class="link" href="GConverter.html#G-CONVERTER-FINISHED:CAPS"><code class="literal">G_CONVERTER_FINISHED</code></a> if |
| really at the end) is returned instead of <a class="link" href="GConverter.html#G-CONVERTER-CONVERTED:CAPS"><code class="literal">G_CONVERTER_CONVERTED</code></a>. |
| This is somewhat similar to what happens at the end of the input stream, |
| but done in the middle of the data. |
| </p> |
| <p> |
| This has different meanings for different conversions. For instance |
| in a compression converter it would mean that we flush all the |
| compression state into output such that if you uncompress the |
| compressed data you get back all the input data. Doing this may |
| make the final file larger due to padding though. Another example |
| is a regexp conversion, where if you at the end of the flushed data |
| have a match, but there is also a potential longer match. In the |
| non-flushed case we would ask for more input, but when flushing we |
| treat this as the end of input and do the match. |
| </p> |
| <p> |
| Flushing is not always possible (like if a charset converter flushes |
| at a partial multibyte sequence). Converters are supposed to try |
| to produce as much output as possible and then return an error |
| (typically <a class="link" href="gio-GIOError.html#G-IO-ERROR-PARTIAL-INPUT:CAPS"><code class="literal">G_IO_ERROR_PARTIAL_INPUT</code></a>). |
| </p> |
| <div class="variablelist"><table border="0"> |
| <col align="left" valign="top"> |
| <tbody> |
| <tr> |
| <td><p><span class="term"><em class="parameter"><code>converter</code></em> :</span></p></td> |
| <td>a <a class="link" href="GConverter.html" title="GConverter"><span class="type">GConverter</span></a>. |
| </td> |
| </tr> |
| <tr> |
| <td><p><span class="term"><em class="parameter"><code>inbuf</code></em> :</span></p></td> |
| <td>the buffer containing the data to convert. |
| </td> |
| </tr> |
| <tr> |
| <td><p><span class="term"><em class="parameter"><code>inbuf_size</code></em> :</span></p></td> |
| <td>the number of bytes in <em class="parameter"><code>inbuf</code></em> |
| </td> |
| </tr> |
| <tr> |
| <td><p><span class="term"><em class="parameter"><code>outbuf</code></em> :</span></p></td> |
| <td>a buffer to write converted data in. |
| </td> |
| </tr> |
| <tr> |
| <td><p><span class="term"><em class="parameter"><code>outbuf_size</code></em> :</span></p></td> |
| <td>the number of bytes in <em class="parameter"><code>outbuf</code></em>, must be at least one |
| </td> |
| </tr> |
| <tr> |
| <td><p><span class="term"><em class="parameter"><code>flags</code></em> :</span></p></td> |
| <td>a <span class="type">GConvertFlags</span> controlling the conversion details |
| </td> |
| </tr> |
| <tr> |
| <td><p><span class="term"><em class="parameter"><code>bytes_read</code></em> :</span></p></td> |
| <td>will be set to the number of bytes read from <em class="parameter"><code>inbuf</code></em> on success |
| </td> |
| </tr> |
| <tr> |
| <td><p><span class="term"><em class="parameter"><code>bytes_written</code></em> :</span></p></td> |
| <td>will be set to the number of bytes written to <em class="parameter"><code>outbuf</code></em> on success |
| </td> |
| </tr> |
| <tr> |
| <td><p><span class="term"><em class="parameter"><code>error</code></em> :</span></p></td> |
| <td>location to store the error occuring, or <a href="/usr/share/gtk-doc/html/glib/glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> to ignore |
| </td> |
| </tr> |
| <tr> |
| <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td> |
| <td> a <a class="link" href="GConverter.html#GConverterResult" title="enum GConverterResult"><span class="type">GConverterResult</span></a>, <a class="link" href="GConverter.html#G-CONVERTER-ERROR:CAPS"><code class="literal">G_CONVERTER_ERROR</code></a> on error. |
| |
| </td> |
| </tr> |
| </tbody> |
| </table></div> |
| <p class="since">Since 2.24</p> |
| </div> |
| <hr> |
| <div class="refsect2" title="g_converter_reset ()"> |
| <a name="g-converter-reset"></a><h3>g_converter_reset ()</h3> |
| <pre class="programlisting"><span class="returnvalue">void</span> g_converter_reset (<em class="parameter"><code><a class="link" href="GConverter.html" title="GConverter"><span class="type">GConverter</span></a> *converter</code></em>);</pre> |
| <p> |
| Resets all internal state in the converter, making it behave |
| as if it was just created. If the converter has any internal |
| state that would produce output then that output is lost. |
| </p> |
| <div class="variablelist"><table border="0"> |
| <col align="left" valign="top"> |
| <tbody><tr> |
| <td><p><span class="term"><em class="parameter"><code>converter</code></em> :</span></p></td> |
| <td>a <a class="link" href="GConverter.html" title="GConverter"><span class="type">GConverter</span></a>. |
| </td> |
| </tr></tbody> |
| </table></div> |
| <p class="since">Since 2.24</p> |
| </div> |
| </div> |
| <div class="refsect1" title="See Also"> |
| <a name="GConverter.see-also"></a><h2>See Also</h2> |
| <a class="link" href="GInputStream.html" title="GInputStream"><span class="type">GInputStream</span></a>, <a class="link" href="GOutputStream.html" title="GOutputStream"><span class="type">GOutputStream</span></a> |
| </div> |
| </div> |
| <div class="footer"> |
| <hr> |
| Generated by GTK-Doc V1.14</div> |
| </body> |
| </html> |
