1 /* GIO - GLib Input, Output and Streaming Library
3 * Copyright (C) 2009 Red Hat, Inc.
5 * This library is free software; you can redistribute it and/or
6 * modify it under the terms of the GNU Lesser General Public
7 * License as published by the Free Software Foundation; either
8 * version 2 of the License, or (at your option) any later version.
10 * This library is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 * Lesser General Public License for more details.
15 * You should have received a copy of the GNU Lesser General
16 * Public License along with this library; if not, write to the
17 * Free Software Foundation, Inc., 59 Temple Place, Suite 330,
18 * Boston, MA 02111-1307, USA.
20 * Author: Alexander Larsson <alexl@redhat.com>
24 #include "gconverter.h"
31 * @short_description: Data conversion interface
33 * @see_also: #GInputStream, #GOutputStream
35 * #GConverter is implemented by objects that convert
36 * binary data in various ways. The conversion can be
37 * stateful and may fail at any place.
39 * Some example conversions are: character set conversion,
40 * compression, decompression and regular expression
46 static void g_converter_base_init (gpointer g_class);
49 g_converter_get_type (void)
51 static volatile gsize g_define_type_id__volatile = 0;
53 if (g_once_init_enter (&g_define_type_id__volatile))
55 const GTypeInfo converter_info =
57 sizeof (GConverterIface), /* class_size */
58 g_converter_base_init, /* base_init */
59 NULL, /* base_finalize */
61 NULL, /* class_finalize */
62 NULL, /* class_data */
67 GType g_define_type_id =
68 g_type_register_static (G_TYPE_INTERFACE, I_("GConverter"),
71 g_type_interface_add_prerequisite (g_define_type_id, G_TYPE_OBJECT);
73 g_once_init_leave (&g_define_type_id__volatile, g_define_type_id);
76 return g_define_type_id__volatile;
80 g_converter_base_init (gpointer g_class)
85 * g_converter_convert:
86 * @converter: a #GConverter.
87 * @inbuf: the buffer containing the data to convert.
88 * @inbuf_size: the number of bytes in @inbuf
89 * @outbuf: a buffer to write converted data in.
90 * @outbuf_size: the number of bytes in @outbuf, must be at least one
91 * @flags: a #GConvertFlags controlling the conversion details
92 * @bytes_read: will be set to the number of bytes read from @inbuf on success
93 * @bytes_written: will be set to the number of bytes written to @outbuf on success
94 * @error: location to store the error occuring, or %NULL to ignore
96 * This is the main operation used when converting data. It is to be called
97 * multiple times in a loop, and each time it will do some work, i.e.
98 * producing some output (in @outbuf) or consuming some input (from @inbuf) or
99 * both. If its not possible to do any work an error is returned.
101 * Note that a single call may not consume all input (or any input at all).
102 * Also a call may produce output even if given no input, due to state stored
103 * in the converter producing output.
105 * If any data was either produced or consumed, and then an error happens, then
106 * only the successful conversion is reported and the error is returned on the
109 * A full conversion loop involves calling this method repeatedly, each time
110 * giving it new input and space output space. When there is no more input
111 * data after the data in @inbuf, the flag %G_CONVERTER_INPUT_AT_END must be set.
112 * The loop will be (unless some error happens) returning %G_CONVERTER_CONVERTED
113 * each time until all data is consumed and all output is produced, then
114 * %G_CONVERTER_FINISHED is returned instead. Note, that %G_CONVERTER_FINISHED
115 * may be returned even if %G_CONVERTER_INPUT_AT_END is not set, for instance
116 * in a decompression converter where the end of data is detectable from the
117 * data (and there might even be other data after the end of the compressed data).
119 * When some data has successfully been converted @bytes_read and is set to
120 * the number of bytes read from @inbuf, and @bytes_written is set to indicate
121 * how many bytes was written to @outbuf. If there are more data to output
122 * or consume (i.e. unless the G_CONVERTER_INPUT_AT_END is specified) then
123 * G_CONVERTER_CONVERTED is returned, and if no more data is to be output
124 * then G_CONVERTER_FINISHED is returned.
126 * On error %G_CONVERTER_ERROR is returned and @error is set accordingly.
127 * Some errors need special handling:
129 * %G_IO_ERROR_NO_SPACE is returned if there is not enough space
130 * to write the resulting converted data, the application should
131 * call the function again with a larger @outbuf to continue.
133 * %G_IO_ERROR_PARTIAL_INPUT is returned if there is not enough
134 * input to fully determine what the conversion should produce,
135 * and the %G_CONVERTER_INPUT_AT_END flag is not set. This happens for
136 * example with an incomplete multibyte sequence when converting text,
137 * or when a regexp matches up to the end of the input (and may match
138 * further input). It may also happen when @inbuf_size is zero and
139 * there is no more data to produce.
141 * When this happens the application should read more input and then
142 * call the function again. If further input shows that there is no
143 * more data call the function again with the same data but with
144 * the %G_CONVERTER_INPUT_AT_END flag set. This may cause the conversion
145 * to finish as e.g. in the regexp match case (or, to fail again with
146 * %G_IO_ERROR_PARTIAL_INPUT in e.g. a charset conversion where the
147 * input is actually partial).
149 * After g_converter_convert() has returned %G_CONVERTER_FINISHED the
150 * converter object is in an invalid state where its not allowed
151 * to call g_converter_convert() anymore. At this time you can only
152 * free the object or call g_converter_reset() to reset it to the
155 * If the flag %G_CONVERTER_FLUSH is set then conversion is modified
156 * to try to write out all internal state to the output. The application
157 * has to call the function multiple times with the flag set, and when
158 * the availible input has been consumed and all internal state has
159 * been produced then %G_CONVERTER_FLUSHED (or %G_CONVERTER_FINISHED if
160 * really at the end) is returned instead of %G_CONVERTER_CONVERTED.
161 * This is somewhat similar to what happens at the end of the input stream,
162 * but done in the middle of the data.
164 * This has different meanings for different conversions. For instance
165 * in a compression converter it would mean that we flush all the
166 * compression state into output such that if you uncompress the
167 * compressed data you get back all the input data. Doing this may
168 * make the final file larger due to padding though. Another example
169 * is a regexp conversion, where if you at the end of the flushed data
170 * have a match, but there is also a potential longer match. In the
171 * non-flushed case we would ask for more input, but when flushing we
172 * treat this as the end of input and do the match.
174 * Flushing is not always possible (like if a charset converter flushes
175 * at a partial multibyte sequence). Converters are supposed to try
176 * to produce as much output as possible and then return an error
177 * (typically %G_IO_ERROR_PARTIAL_INPUT).
179 * Returns: a #GConverterResult, %G_CONVERTER_ERROR on error.
184 g_converter_convert (GConverter *converter,
189 GConverterFlags flags,
191 gsize *bytes_written,
194 GConverterIface *iface;
196 g_return_val_if_fail (G_IS_CONVERTER (converter), G_CONVERTER_ERROR);
197 g_return_val_if_fail (outbuf_size > 0, G_CONVERTER_ERROR);
202 iface = G_CONVERTER_GET_IFACE (converter);
204 return (* iface->convert) (converter,
208 bytes_read, bytes_written, error);
213 * @converter: a #GConverter.
215 * Resets all internal state in the converter, making it behave
216 * as if it was just created. If the converter has any internal
217 * state that would produce output then that output is lost.
222 g_converter_reset (GConverter *converter)
224 GConverterIface *iface;
226 g_return_if_fail (G_IS_CONVERTER (converter));
228 iface = G_CONVERTER_GET_IFACE (converter);
230 (* iface->reset) (converter);
233 #define __G_CONVERTER_C__
234 #include "gioaliasdef.c"