LCOV - code coverage report
Current view: top level - gio - gconverter.c (source / functions) Coverage Total Hit
Test: unnamed Lines: 100.0 % 32 32
Test Date: 2024-11-26 05:23:01 Functions: 100.0 % 5 5
Branches: - 0 0

             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                 :             : }
        

Generated by: LCOV version 2.0-1