source: appstream-generator/build/girepo/gio/ConverterIF.d @ 4841

Last change on this file since 4841 was 4841, checked in by Juanma, 2 years ago

Initial release

File size: 7.0 KB
Line 
1/*
2 * Licensed under the GNU Lesser General Public License Version 3
3 *
4 * This library is free software: you can redistribute it and/or modify
5 * it under the terms of the GNU Lesser General Public License as published by
6 * the Free Software Foundation, either version 3 of the license, or
7 * (at your option) any later version.
8 *
9 * This software is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
12 * GNU Lesser General Public License for more details.
13 *
14 * You should have received a copy of the GNU Lesser General Public License
15 * along with this library.  If not, see <http://www.gnu.org/licenses/>.
16 */
17
18// generated automatically - do not change
19
20
21module gio.ConverterIF;
22
23private import gi.gio;
24public  import gi.giotypes;
25private import glib.ErrorG;
26private import glib.GException;
27
28
29/**
30 * #GConverter is implemented by objects that convert
31 * binary data in various ways. The conversion can be
32 * stateful and may fail at any place.
33 *
34 * Some example conversions are: character set conversion,
35 * compression, decompression and regular expression
36 * replace.
37 *
38 * Since: 2.24
39 */
40public interface ConverterIF{
41        /** Get the main Gtk struct */
42        public GConverter* getConverterStruct();
43
44        /** the main Gtk struct as a void* */
45        protected void* getStruct();
46
47
48        /**
49         * This is the main operation used when converting data. It is to be called
50         * multiple times in a loop, and each time it will do some work, i.e.
51         * producing some output (in @outbuf) or consuming some input (from @inbuf) or
52         * both. If its not possible to do any work an error is returned.
53         *
54         * Note that a single call may not consume all input (or any input at all).
55         * Also a call may produce output even if given no input, due to state stored
56         * in the converter producing output.
57         *
58         * If any data was either produced or consumed, and then an error happens, then
59         * only the successful conversion is reported and the error is returned on the
60         * next call.
61         *
62         * A full conversion loop involves calling this method repeatedly, each time
63         * giving it new input and space output space. When there is no more input
64         * data after the data in @inbuf, the flag %G_CONVERTER_INPUT_AT_END must be set.
65         * The loop will be (unless some error happens) returning %G_CONVERTER_CONVERTED
66         * each time until all data is consumed and all output is produced, then
67         * %G_CONVERTER_FINISHED is returned instead. Note, that %G_CONVERTER_FINISHED
68         * may be returned even if %G_CONVERTER_INPUT_AT_END is not set, for instance
69         * in a decompression converter where the end of data is detectable from the
70         * data (and there might even be other data after the end of the compressed data).
71         *
72         * When some data has successfully been converted @bytes_read and is set to
73         * the number of bytes read from @inbuf, and @bytes_written is set to indicate
74         * how many bytes was written to @outbuf. If there are more data to output
75         * or consume (i.e. unless the %G_CONVERTER_INPUT_AT_END is specified) then
76         * %G_CONVERTER_CONVERTED is returned, and if no more data is to be output
77         * then %G_CONVERTER_FINISHED is returned.
78         *
79         * On error %G_CONVERTER_ERROR is returned and @error is set accordingly.
80         * Some errors need special handling:
81         *
82         * %G_IO_ERROR_NO_SPACE is returned if there is not enough space
83         * to write the resulting converted data, the application should
84         * call the function again with a larger @outbuf to continue.
85         *
86         * %G_IO_ERROR_PARTIAL_INPUT is returned if there is not enough
87         * input to fully determine what the conversion should produce,
88         * and the %G_CONVERTER_INPUT_AT_END flag is not set. This happens for
89         * example with an incomplete multibyte sequence when converting text,
90         * or when a regexp matches up to the end of the input (and may match
91         * further input). It may also happen when @inbuf_size is zero and
92         * there is no more data to produce.
93         *
94         * When this happens the application should read more input and then
95         * call the function again. If further input shows that there is no
96         * more data call the function again with the same data but with
97         * the %G_CONVERTER_INPUT_AT_END flag set. This may cause the conversion
98         * to finish as e.g. in the regexp match case (or, to fail again with
99         * %G_IO_ERROR_PARTIAL_INPUT in e.g. a charset conversion where the
100         * input is actually partial).
101         *
102         * After g_converter_convert() has returned %G_CONVERTER_FINISHED the
103         * converter object is in an invalid state where its not allowed
104         * to call g_converter_convert() anymore. At this time you can only
105         * free the object or call g_converter_reset() to reset it to the
106         * initial state.
107         *
108         * If the flag %G_CONVERTER_FLUSH is set then conversion is modified
109         * to try to write out all internal state to the output. The application
110         * has to call the function multiple times with the flag set, and when
111         * the available input has been consumed and all internal state has
112         * been produced then %G_CONVERTER_FLUSHED (or %G_CONVERTER_FINISHED if
113         * really at the end) is returned instead of %G_CONVERTER_CONVERTED.
114         * This is somewhat similar to what happens at the end of the input stream,
115         * but done in the middle of the data.
116         *
117         * This has different meanings for different conversions. For instance
118         * in a compression converter it would mean that we flush all the
119         * compression state into output such that if you uncompress the
120         * compressed data you get back all the input data. Doing this may
121         * make the final file larger due to padding though. Another example
122         * is a regexp conversion, where if you at the end of the flushed data
123         * have a match, but there is also a potential longer match. In the
124         * non-flushed case we would ask for more input, but when flushing we
125         * treat this as the end of input and do the match.
126         *
127         * Flushing is not always possible (like if a charset converter flushes
128         * at a partial multibyte sequence). Converters are supposed to try
129         * to produce as much output as possible and then return an error
130         * (typically %G_IO_ERROR_PARTIAL_INPUT).
131         *
132         * Params:
133         *     inbuf = the buffer
134         *         containing the data to convert.
135         *     inbufSize = the number of bytes in @inbuf
136         *     outbuf = a buffer to write converted data in.
137         *     outbufSize = the number of bytes in @outbuf, must be at least one
138         *     flags = a #GConverterFlags controlling the conversion details
139         *     bytesRead = will be set to the number of bytes read from @inbuf on success
140         *     bytesWritten = will be set to the number of bytes written to @outbuf on success
141         *
142         * Returns: a #GConverterResult, %G_CONVERTER_ERROR on error.
143         *
144         * Since: 2.24
145         *
146         * Throws: GException on failure.
147         */
148        public GConverterResult convert(ubyte[] inbuf, void* outbuf, size_t outbufSize, GConverterFlags flags, out size_t bytesRead, out size_t bytesWritten);
149
150        /**
151         * Resets all internal state in the converter, making it behave
152         * as if it was just created. If the converter has any internal
153         * state that would produce output then that output is lost.
154         *
155         * Since: 2.24
156         */
157        public void reset();
158}
Note: See TracBrowser for help on using the repository browser.