gio/gconverter.c

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