1dcf6aac19f974570ef62366b6441212471ceb97
[platform/upstream/glib.git] / gio / gconverter.c
1 /* GIO - GLib Input, Output and Streaming Library
2  *
3  * Copyright (C) 2009 Red Hat, Inc.
4  *
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.
9  *
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.
14  *
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.
19  *
20  * Author: Alexander Larsson <alexl@redhat.com>
21  */
22
23 #include "config.h"
24 #include "gconverter.h"
25 #include "glibintl.h"
26
27
28 /**
29  * SECTION:gconverter
30  * @short_description: Data conversion interface
31  * @include: gio/gio.h
32  * @see_also: #GInputStream, #GOutputStream
33  *
34  * #GConverter is implemented by objects that convert
35  * binary data in various ways. The conversion can be
36  * stateful and may fail at any place.
37  *
38  * Some example conversions are: character set conversion,
39  * compression, decompression and regular expression
40  * replace.
41  *
42  * Since: 2.24
43  **/
44
45
46 typedef GConverterIface GConverterInterface;
47 G_DEFINE_INTERFACE (GConverter, g_converter, G_TYPE_OBJECT)
48
49 static void
50 g_converter_default_init (GConverterInterface *iface)
51 {
52 }
53
54 /**
55  * g_converter_convert:
56  * @converter: a #GConverter.
57  * @inbuf: (array length=inbuf_size) (element-type guint8): the buffer
58  *         containing the data to convert.
59  * @inbuf_size: the number of bytes in @inbuf
60  * @outbuf: a buffer to write converted data in.
61  * @outbuf_size: the number of bytes in @outbuf, must be at least one
62  * @flags: a #GConvertFlags controlling the conversion details
63  * @bytes_read: (out): will be set to the number of bytes read from @inbuf on success
64  * @bytes_written: (out): will be set to the number of bytes written to @outbuf on success
65  * @error: location to store the error occuring, or %NULL to ignore
66  *
67  * This is the main operation used when converting data. It is to be called
68  * multiple times in a loop, and each time it will do some work, i.e.
69  * producing some output (in @outbuf) or consuming some input (from @inbuf) or
70  * both. If its not possible to do any work an error is returned.
71  *
72  * Note that a single call may not consume all input (or any input at all).
73  * Also a call may produce output even if given no input, due to state stored
74  * in the converter producing output.
75  *
76  * If any data was either produced or consumed, and then an error happens, then
77  * only the successful conversion is reported and the error is returned on the
78  * next call.
79  *
80  * A full conversion loop involves calling this method repeatedly, each time
81  * giving it new input and space output space. When there is no more input
82  * data after the data in @inbuf, the flag %G_CONVERTER_INPUT_AT_END must be set.
83  * The loop will be (unless some error happens) returning %G_CONVERTER_CONVERTED
84  * each time until all data is consumed and all output is produced, then
85  * %G_CONVERTER_FINISHED is returned instead. Note, that %G_CONVERTER_FINISHED
86  * may be returned even if %G_CONVERTER_INPUT_AT_END is not set, for instance
87  * in a decompression converter where the end of data is detectable from the
88  * data (and there might even be other data after the end of the compressed data).
89  *
90  * When some data has successfully been converted @bytes_read and is set to
91  * the number of bytes read from @inbuf, and @bytes_written is set to indicate
92  * how many bytes was written to @outbuf. If there are more data to output
93  * or consume (i.e. unless the G_CONVERTER_INPUT_AT_END is specified) then
94  * G_CONVERTER_CONVERTED is returned, and if no more data is to be output
95  * then G_CONVERTER_FINISHED is returned.
96  *
97  * On error %G_CONVERTER_ERROR is returned and @error is set accordingly.
98  * Some errors need special handling:
99  *
100  * %G_IO_ERROR_NO_SPACE is returned if there is not enough space
101  * to write the resulting converted data, the application should
102  * call the function again with a larger @outbuf to continue.
103  *
104  * %G_IO_ERROR_PARTIAL_INPUT is returned if there is not enough
105  * input to fully determine what the conversion should produce,
106  * and the %G_CONVERTER_INPUT_AT_END flag is not set. This happens for
107  * example with an incomplete multibyte sequence when converting text,
108  * or when a regexp matches up to the end of the input (and may match
109  * further input). It may also happen when @inbuf_size is zero and
110  * there is no more data to produce.
111  *
112  * When this happens the application should read more input and then
113  * call the function again. If further input shows that there is no
114  * more data call the function again with the same data but with
115  * the %G_CONVERTER_INPUT_AT_END flag set. This may cause the conversion
116  * to finish as e.g. in the regexp match case (or, to fail again with
117  * %G_IO_ERROR_PARTIAL_INPUT in e.g. a charset conversion where the
118  * input is actually partial).
119  *
120  * After g_converter_convert() has returned %G_CONVERTER_FINISHED the
121  * converter object is in an invalid state where its not allowed
122  * to call g_converter_convert() anymore. At this time you can only
123  * free the object or call g_converter_reset() to reset it to the
124  * initial state.
125  *
126  * If the flag %G_CONVERTER_FLUSH is set then conversion is modified
127  * to try to write out all internal state to the output. The application
128  * has to call the function multiple times with the flag set, and when
129  * the availible input has been consumed and all internal state has
130  * been produced then %G_CONVERTER_FLUSHED (or %G_CONVERTER_FINISHED if
131  * really at the end) is returned instead of %G_CONVERTER_CONVERTED.
132  * This is somewhat similar to what happens at the end of the input stream,
133  * but done in the middle of the data.
134  *
135  * This has different meanings for different conversions. For instance
136  * in a compression converter it would mean that we flush all the
137  * compression state into output such that if you uncompress the
138  * compressed data you get back all the input data. Doing this may
139  * make the final file larger due to padding though. Another example
140  * is a regexp conversion, where if you at the end of the flushed data
141  * have a match, but there is also a potential longer match. In the
142  * non-flushed case we would ask for more input, but when flushing we
143  * treat this as the end of input and do the match.
144  *
145  * Flushing is not always possible (like if a charset converter flushes
146  * at a partial multibyte sequence). Converters are supposed to try
147  * to produce as much output as possible and then return an error
148  * (typically %G_IO_ERROR_PARTIAL_INPUT).
149  *
150  * Returns: a #GConverterResult, %G_CONVERTER_ERROR on error.
151  *
152  * Since: 2.24
153  **/
154 GConverterResult
155 g_converter_convert (GConverter *converter,
156                      const void *inbuf,
157                      gsize       inbuf_size,
158                      void       *outbuf,
159                      gsize       outbuf_size,
160                      GConverterFlags flags,
161                      gsize      *bytes_read,
162                      gsize      *bytes_written,
163                      GError    **error)
164 {
165   GConverterIface *iface;
166
167   g_return_val_if_fail (G_IS_CONVERTER (converter), G_CONVERTER_ERROR);
168   g_return_val_if_fail (outbuf_size > 0, G_CONVERTER_ERROR);
169
170   *bytes_read = 0;
171   *bytes_written = 0;
172
173   iface = G_CONVERTER_GET_IFACE (converter);
174
175   return (* iface->convert) (converter,
176                              inbuf, inbuf_size,
177                              outbuf, outbuf_size,
178                              flags,
179                              bytes_read, bytes_written, error);
180 }
181
182 /**
183  * g_converter_reset:
184  * @converter: a #GConverter.
185  *
186  * Resets all internal state in the converter, making it behave
187  * as if it was just created. If the converter has any internal
188  * state that would produce output then that output is lost.
189  *
190  * Since: 2.24
191  **/
192 void
193 g_converter_reset (GConverter *converter)
194 {
195   GConverterIface *iface;
196
197   g_return_if_fail (G_IS_CONVERTER (converter));
198
199   iface = G_CONVERTER_GET_IFACE (converter);
200
201   (* iface->reset) (converter);
202 }