Branch data Line data Source code
1 : : /* GIO - GLib Input, Output and Streaming Library
2 : : *
3 : : * Copyright (C) 2009 Red Hat, Inc.
4 : : *
5 : : * SPDX-License-Identifier: LGPL-2.1-or-later
6 : : *
7 : : * This library is free software; you can redistribute it and/or
8 : : * modify it under the terms of the GNU Lesser General Public
9 : : * License as published by the Free Software Foundation; either
10 : : * version 2.1 of the License, or (at your option) any later version.
11 : : *
12 : : * This library is distributed in the hope that it will be useful,
13 : : * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 : : * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 : : * Lesser General Public License for more details.
16 : : *
17 : : * You should have received a copy of the GNU Lesser General
18 : : * Public License along with this library; if not, see <http://www.gnu.org/licenses/>.
19 : : *
20 : : * Author: Alexander Larsson <alexl@redhat.com>
21 : : */
22 : :
23 : : #include "config.h"
24 : : #include "gconverter.h"
25 : : #include "glibintl.h"
26 : : #include "gmemoryinputstream.h"
27 : : #include "gmemoryoutputstream.h"
28 : : #include "gconverteroutputstream.h"
29 : :
30 : :
31 : : /**
32 : : * GConverter:
33 : : *
34 : : * `GConverter` is an interface for streaming conversions.
35 : : *
36 : : * `GConverter` is implemented by objects that convert
37 : : * binary data in various ways. The conversion can be
38 : : * stateful and may fail at any place.
39 : : *
40 : : * Some example conversions are: character set conversion,
41 : : * compression, decompression and regular expression
42 : : * replace.
43 : : *
44 : : * Since: 2.24
45 : : */
46 : :
47 : :
48 : : typedef GConverterIface GConverterInterface;
49 : 180966 : G_DEFINE_INTERFACE (GConverter, g_converter, G_TYPE_OBJECT)
50 : :
51 : : static void
52 : 9 : g_converter_default_init (GConverterInterface *iface)
53 : : {
54 : 9 : }
55 : :
56 : : /**
57 : : * g_converter_convert:
58 : : * @converter: a #GConverter.
59 : : * @inbuf: (array length=inbuf_size) (element-type guint8): the buffer
60 : : * containing the data to convert.
61 : : * @inbuf_size: the number of bytes in @inbuf
62 : : * @outbuf: (element-type guint8) (array length=outbuf_size) (not nullable): a
63 : : * buffer to write converted data in.
64 : : * @outbuf_size: the number of bytes in @outbuf, must be at least one
65 : : * @flags: a #GConverterFlags controlling the conversion details
66 : : * @bytes_read: (out) (not nullable): will be set to the number of bytes read
67 : : * from @inbuf on success
68 : : * @bytes_written: (out) (not nullable): will be set to the number of bytes
69 : : * written to @outbuf on success
70 : : * @error: location to store the error occurring, or %NULL to ignore
71 : : *
72 : : * This is the main operation used when converting data. It is to be called
73 : : * multiple times in a loop, and each time it will do some work, i.e.
74 : : * producing some output (in @outbuf) or consuming some input (from @inbuf) or
75 : : * both. If its not possible to do any work an error is returned.
76 : : *
77 : : * Note that a single call may not consume all input (or any input at all).
78 : : * Also a call may produce output even if given no input, due to state stored
79 : : * in the converter producing output.
80 : : *
81 : : * If any data was either produced or consumed, and then an error happens, then
82 : : * only the successful conversion is reported and the error is returned on the
83 : : * next call.
84 : : *
85 : : * A full conversion loop involves calling this method repeatedly, each time
86 : : * giving it new input and space output space. When there is no more input
87 : : * data after the data in @inbuf, the flag %G_CONVERTER_INPUT_AT_END must be set.
88 : : * The loop will be (unless some error happens) returning %G_CONVERTER_CONVERTED
89 : : * each time until all data is consumed and all output is produced, then
90 : : * %G_CONVERTER_FINISHED is returned instead. Note, that %G_CONVERTER_FINISHED
91 : : * may be returned even if %G_CONVERTER_INPUT_AT_END is not set, for instance
92 : : * in a decompression converter where the end of data is detectable from the
93 : : * data (and there might even be other data after the end of the compressed data).
94 : : *
95 : : * When some data has successfully been converted @bytes_read and is set to
96 : : * the number of bytes read from @inbuf, and @bytes_written is set to indicate
97 : : * how many bytes was written to @outbuf. If there are more data to output
98 : : * or consume (i.e. unless the %G_CONVERTER_INPUT_AT_END is specified) then
99 : : * %G_CONVERTER_CONVERTED is returned, and if no more data is to be output
100 : : * then %G_CONVERTER_FINISHED is returned.
101 : : *
102 : : * On error %G_CONVERTER_ERROR is returned and @error is set accordingly.
103 : : * Some errors need special handling:
104 : : *
105 : : * %G_IO_ERROR_NO_SPACE is returned if there is not enough space
106 : : * to write the resulting converted data, the application should
107 : : * call the function again with a larger @outbuf to continue.
108 : : *
109 : : * %G_IO_ERROR_PARTIAL_INPUT is returned if there is not enough
110 : : * input to fully determine what the conversion should produce,
111 : : * and the %G_CONVERTER_INPUT_AT_END flag is not set. This happens for
112 : : * example with an incomplete multibyte sequence when converting text,
113 : : * or when a regexp matches up to the end of the input (and may match
114 : : * further input). It may also happen when @inbuf_size is zero and
115 : : * there is no more data to produce.
116 : : *
117 : : * When this happens the application should read more input and then
118 : : * call the function again. If further input shows that there is no
119 : : * more data call the function again with the same data but with
120 : : * the %G_CONVERTER_INPUT_AT_END flag set. This may cause the conversion
121 : : * to finish as e.g. in the regexp match case (or, to fail again with
122 : : * %G_IO_ERROR_PARTIAL_INPUT in e.g. a charset conversion where the
123 : : * input is actually partial).
124 : : *
125 : : * After g_converter_convert() has returned %G_CONVERTER_FINISHED the
126 : : * converter object is in an invalid state where its not allowed
127 : : * to call g_converter_convert() anymore. At this time you can only
128 : : * free the object or call g_converter_reset() to reset it to the
129 : : * initial state.
130 : : *
131 : : * If the flag %G_CONVERTER_FLUSH is set then conversion is modified
132 : : * to try to write out all internal state to the output. The application
133 : : * has to call the function multiple times with the flag set, and when
134 : : * the available input has been consumed and all internal state has
135 : : * been produced then %G_CONVERTER_FLUSHED (or %G_CONVERTER_FINISHED if
136 : : * really at the end) is returned instead of %G_CONVERTER_CONVERTED.
137 : : * This is somewhat similar to what happens at the end of the input stream,
138 : : * but done in the middle of the data.
139 : : *
140 : : * This has different meanings for different conversions. For instance
141 : : * in a compression converter it would mean that we flush all the
142 : : * compression state into output such that if you uncompress the
143 : : * compressed data you get back all the input data. Doing this may
144 : : * make the final file larger due to padding though. Another example
145 : : * is a regexp conversion, where if you at the end of the flushed data
146 : : * have a match, but there is also a potential longer match. In the
147 : : * non-flushed case we would ask for more input, but when flushing we
148 : : * treat this as the end of input and do the match.
149 : : *
150 : : * Flushing is not always possible (like if a charset converter flushes
151 : : * at a partial multibyte sequence). Converters are supposed to try
152 : : * to produce as much output as possible and then return an error
153 : : * (typically %G_IO_ERROR_PARTIAL_INPUT).
154 : : *
155 : : * Returns: a #GConverterResult, %G_CONVERTER_ERROR on error.
156 : : *
157 : : * Since: 2.24
158 : : **/
159 : : GConverterResult
160 : 90421 : g_converter_convert (GConverter *converter,
161 : : const void *inbuf,
162 : : gsize inbuf_size,
163 : : void *outbuf,
164 : : gsize outbuf_size,
165 : : GConverterFlags flags,
166 : : gsize *bytes_read,
167 : : gsize *bytes_written,
168 : : GError **error)
169 : : {
170 : : GConverterIface *iface;
171 : :
172 : 90421 : g_return_val_if_fail (G_IS_CONVERTER (converter), G_CONVERTER_ERROR);
173 : 90421 : g_return_val_if_fail (inbuf != NULL || inbuf_size == 0, G_CONVERTER_ERROR);
174 : 90421 : g_return_val_if_fail (outbuf != NULL, G_CONVERTER_ERROR);
175 : 90421 : g_return_val_if_fail (outbuf_size > 0, G_CONVERTER_ERROR);
176 : 90421 : g_return_val_if_fail (bytes_read != NULL, G_CONVERTER_ERROR);
177 : 90421 : g_return_val_if_fail (bytes_written != NULL, G_CONVERTER_ERROR);
178 : 90421 : g_return_val_if_fail (error == NULL || *error == NULL, G_CONVERTER_ERROR);
179 : :
180 : 90421 : *bytes_read = 0;
181 : 90421 : *bytes_written = 0;
182 : :
183 : 90421 : iface = G_CONVERTER_GET_IFACE (converter);
184 : :
185 : 90421 : return (* iface->convert) (converter,
186 : : inbuf, inbuf_size,
187 : : outbuf, outbuf_size,
188 : : flags,
189 : : bytes_read, bytes_written, error);
190 : : }
191 : :
192 : : /**
193 : : * g_converter_reset:
194 : : * @converter: a #GConverter.
195 : : *
196 : : * Resets all internal state in the converter, making it behave
197 : : * as if it was just created. If the converter has any internal
198 : : * state that would produce output then that output is lost.
199 : : *
200 : : * Since: 2.24
201 : : **/
202 : : void
203 : 23 : g_converter_reset (GConverter *converter)
204 : : {
205 : : GConverterIface *iface;
206 : :
207 : 23 : g_return_if_fail (G_IS_CONVERTER (converter));
208 : :
209 : 23 : iface = G_CONVERTER_GET_IFACE (converter);
210 : :
211 : 23 : (* iface->reset) (converter);
212 : : }
213 : :
214 : : /**
215 : : * g_converter_convert_bytes:
216 : : * @converter: the `GConverter` to use
217 : : * @bytes: the data to convert
218 : : * @error: location to store the error occurring
219 : : *
220 : : * Applies @converter to the data in @bytes.
221 : : *
222 : : * Returns: (transfer full): A newly-allocated
223 : : * `GBytes` with the converted data, or `NULL` if an error
224 : : * occurred
225 : : *
226 : : * Since: 2.82
227 : : */
228 : : GBytes *
229 : 4 : g_converter_convert_bytes (GConverter *converter,
230 : : GBytes *bytes,
231 : : GError **error)
232 : : {
233 : : GInputStream *input;
234 : : GOutputStream *output;
235 : : GOutputStream *conv;
236 : : GOutputStreamSpliceFlags flags;
237 : 4 : GBytes *result = NULL;
238 : :
239 : 4 : g_converter_reset (converter);
240 : :
241 : 4 : input = g_memory_input_stream_new_from_bytes (bytes);
242 : 4 : output = g_memory_output_stream_new_resizable ();
243 : 4 : conv = g_converter_output_stream_new (output, converter);
244 : :
245 : 4 : flags = G_OUTPUT_STREAM_SPLICE_CLOSE_SOURCE | G_OUTPUT_STREAM_SPLICE_CLOSE_TARGET;
246 : :
247 : 4 : if (g_output_stream_splice (conv, input, flags, NULL, error) != -1)
248 : : {
249 : 2 : result = g_memory_output_stream_steal_as_bytes (G_MEMORY_OUTPUT_STREAM (output));
250 : : }
251 : :
252 : 4 : g_object_unref (conv);
253 : 4 : g_object_unref (output);
254 : 4 : g_object_unref (input);
255 : :
256 : 4 : return result;
257 : : }
|
