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 #include "gioalias.h"
  28
  29 /**
  30  * SECTION:gconverter
  31  * @short_description: Data conversion interface
  32  * @include: gio/gio.h
  33  * @see_also: #GInputStream, #GOutputStream
  34  *
  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.
  38  *
  39  * Some example conversions are: character set conversion,
  40  * compression, decompression and regular expression
  41  * replace.
  42  *
  43  * Since: 2.24
  44  **/
  45
  46 static void g_converter_base_init (gpointer g_class);
  47
  48 GType
  49 g_converter_get_type (void)
  50 {
  51   static volatile gsize g_define_type_id__volatile = 0;
  52
  53   if (g_once_init_enter (&g_define_type_id__volatile))
  54     {
  55       const GTypeInfo converter_info =
  56       {
  57         sizeof (GConverterIface), /* class_size */
  58         g_converter_base_init,   /* base_init */
  59         NULL,           /* base_finalize */
  60         NULL,
  61         NULL,           /* class_finalize */
  62         NULL,           /* class_data */
  63         0,
  64         0,              /* n_preallocs */
  65         NULL
  66       };
  67       GType g_define_type_id =
  68         g_type_register_static (G_TYPE_INTERFACE, I_("GConverter"),
  69                                 &converter_info, 0);
  70
  71       g_type_interface_add_prerequisite (g_define_type_id, G_TYPE_OBJECT);
  72
  73       g_once_init_leave (&g_define_type_id__volatile, g_define_type_id);
  74     }
  75
  76   return g_define_type_id__volatile;
  77 }
  78
  79 static void
  80 g_converter_base_init (gpointer g_class)
  81 {
  82 }
  83
  84 /**
  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
  95  *
  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.
 100  *
 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.
 104  *
 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
 107  * next call.
 108  *
 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).
 118  *
 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.
 125  *
 126  * On error %G_CONVERTER_ERROR is returned and @error is set accordingly.
 127  * Some errors need special handling:
 128  *
 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.
 132  *
 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.
 140  *
 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).
 148  *
 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
 153  * initial state.
 154  *
 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.
 163  *
 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.
 173  *
 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).
 178  *
 179  * Returns: a #GConverterResult, %G_CONVERTER_ERROR on error.
 180  *
 181  * Since: 2.24
 182  **/
 183 GConverterResult
 184 g_converter_convert (GConverter *converter,
 185                      const void *inbuf,
 186                      gsize       inbuf_size,
 187                      void       *outbuf,
 188                      gsize       outbuf_size,
 189                      GConverterFlags flags,
 190                      gsize      *bytes_read,
 191                      gsize      *bytes_written,
 192                      GError    **error)
 193 {
 194   GConverterIface *iface;
 195
 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);
 198
 199   *bytes_read = 0;
 200   *bytes_written = 0;
 201
 202   iface = G_CONVERTER_GET_IFACE (converter);
 203
 204   return (* iface->convert) (converter,
 205                              inbuf, inbuf_size,
 206                              outbuf, outbuf_size,
 207                              flags,
 208                              bytes_read, bytes_written, error);
 209 }
 210
 211 /**
 212  * g_converter_reset:
 213  * @converter: a #GConverter.
 214  *
 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.
 218  *
 219  * Since: 2.24
 220  **/
 221 void
 222 g_converter_reset (GConverter *converter)
 223 {
 224   GConverterIface *iface;
 225
 226   g_return_if_fail (G_IS_CONVERTER (converter));
 227
 228   iface = G_CONVERTER_GET_IFACE (converter);
 229
 230   (* iface->reset) (converter);
 231 }
 232
 233 #define __G_CONVERTER_C__
 234 #include "gioaliasdef.c"