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