1 /*
2  * This file is part of gtkD.
3  *
4  * gtkD is free software; you can redistribute it and/or modify
5  * it under the terms of the GNU Lesser General Public License
6  * as published by the Free Software Foundation; either version 3
7  * of the License, or (at your option) any later version, with
8  * some exceptions, please read the COPYING file.
9  *
10  * gtkD 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
13  * GNU Lesser General Public License for more details.
14  *
15  * You should have received a copy of the GNU Lesser General Public License
16  * along with gtkD; if not, write to the Free Software
17  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110, USA
18  */
19 
20 // generated automatically - do not change
21 // find conversion definition on APILookup.txt
22 // implement new conversion functionalities on the wrap.utils pakage
23 
24 
25 module gio.ConverterT;
26 
27 public  import glib.ErrorG;
28 public  import glib.GException;
29 public  import gtkc.gio;
30 public  import gtkc.giotypes;
31 
32 
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 public template ConverterT(TStruct)
45 {
46 	/** Get the main Gtk struct */
47 	public GConverter* getConverterStruct()
48 	{
49 		return cast(GConverter*)getStruct();
50 	}
51 
52 	/**
53 	 */
54 
55 	/**
56 	 * This is the main operation used when converting data. It is to be called
57 	 * multiple times in a loop, and each time it will do some work, i.e.
58 	 * producing some output (in @outbuf) or consuming some input (from @inbuf) or
59 	 * both. If its not possible to do any work an error is returned.
60 	 *
61 	 * Note that a single call may not consume all input (or any input at all).
62 	 * Also a call may produce output even if given no input, due to state stored
63 	 * in the converter producing output.
64 	 *
65 	 * If any data was either produced or consumed, and then an error happens, then
66 	 * only the successful conversion is reported and the error is returned on the
67 	 * next call.
68 	 *
69 	 * A full conversion loop involves calling this method repeatedly, each time
70 	 * giving it new input and space output space. When there is no more input
71 	 * data after the data in @inbuf, the flag %G_CONVERTER_INPUT_AT_END must be set.
72 	 * The loop will be (unless some error happens) returning %G_CONVERTER_CONVERTED
73 	 * each time until all data is consumed and all output is produced, then
74 	 * %G_CONVERTER_FINISHED is returned instead. Note, that %G_CONVERTER_FINISHED
75 	 * may be returned even if %G_CONVERTER_INPUT_AT_END is not set, for instance
76 	 * in a decompression converter where the end of data is detectable from the
77 	 * data (and there might even be other data after the end of the compressed data).
78 	 *
79 	 * When some data has successfully been converted @bytes_read and is set to
80 	 * the number of bytes read from @inbuf, and @bytes_written is set to indicate
81 	 * how many bytes was written to @outbuf. If there are more data to output
82 	 * or consume (i.e. unless the %G_CONVERTER_INPUT_AT_END is specified) then
83 	 * %G_CONVERTER_CONVERTED is returned, and if no more data is to be output
84 	 * then %G_CONVERTER_FINISHED is returned.
85 	 *
86 	 * On error %G_CONVERTER_ERROR is returned and @error is set accordingly.
87 	 * Some errors need special handling:
88 	 *
89 	 * %G_IO_ERROR_NO_SPACE is returned if there is not enough space
90 	 * to write the resulting converted data, the application should
91 	 * call the function again with a larger @outbuf to continue.
92 	 *
93 	 * %G_IO_ERROR_PARTIAL_INPUT is returned if there is not enough
94 	 * input to fully determine what the conversion should produce,
95 	 * and the %G_CONVERTER_INPUT_AT_END flag is not set. This happens for
96 	 * example with an incomplete multibyte sequence when converting text,
97 	 * or when a regexp matches up to the end of the input (and may match
98 	 * further input). It may also happen when @inbuf_size is zero and
99 	 * there is no more data to produce.
100 	 *
101 	 * When this happens the application should read more input and then
102 	 * call the function again. If further input shows that there is no
103 	 * more data call the function again with the same data but with
104 	 * the %G_CONVERTER_INPUT_AT_END flag set. This may cause the conversion
105 	 * to finish as e.g. in the regexp match case (or, to fail again with
106 	 * %G_IO_ERROR_PARTIAL_INPUT in e.g. a charset conversion where the
107 	 * input is actually partial).
108 	 *
109 	 * After g_converter_convert() has returned %G_CONVERTER_FINISHED the
110 	 * converter object is in an invalid state where its not allowed
111 	 * to call g_converter_convert() anymore. At this time you can only
112 	 * free the object or call g_converter_reset() to reset it to the
113 	 * initial state.
114 	 *
115 	 * If the flag %G_CONVERTER_FLUSH is set then conversion is modified
116 	 * to try to write out all internal state to the output. The application
117 	 * has to call the function multiple times with the flag set, and when
118 	 * the available input has been consumed and all internal state has
119 	 * been produced then %G_CONVERTER_FLUSHED (or %G_CONVERTER_FINISHED if
120 	 * really at the end) is returned instead of %G_CONVERTER_CONVERTED.
121 	 * This is somewhat similar to what happens at the end of the input stream,
122 	 * but done in the middle of the data.
123 	 *
124 	 * This has different meanings for different conversions. For instance
125 	 * in a compression converter it would mean that we flush all the
126 	 * compression state into output such that if you uncompress the
127 	 * compressed data you get back all the input data. Doing this may
128 	 * make the final file larger due to padding though. Another example
129 	 * is a regexp conversion, where if you at the end of the flushed data
130 	 * have a match, but there is also a potential longer match. In the
131 	 * non-flushed case we would ask for more input, but when flushing we
132 	 * treat this as the end of input and do the match.
133 	 *
134 	 * Flushing is not always possible (like if a charset converter flushes
135 	 * at a partial multibyte sequence). Converters are supposed to try
136 	 * to produce as much output as possible and then return an error
137 	 * (typically %G_IO_ERROR_PARTIAL_INPUT).
138 	 *
139 	 * Params:
140 	 *     inbuf = the buffer
141 	 *         containing the data to convert.
142 	 *     inbufSize = the number of bytes in @inbuf
143 	 *     outbuf = a buffer to write converted data in.
144 	 *     outbufSize = the number of bytes in @outbuf, must be at least one
145 	 *     flags = a #GConverterFlags controlling the conversion details
146 	 *     bytesRead = will be set to the number of bytes read from @inbuf on success
147 	 *     bytesWritten = will be set to the number of bytes written to @outbuf on success
148 	 *
149 	 * Return: a #GConverterResult, %G_CONVERTER_ERROR on error.
150 	 *
151 	 * Since: 2.24
152 	 *
153 	 * Throws: GException on failure.
154 	 */
155 	public GConverterResult convert(ubyte[] inbuf, void* outbuf, size_t outbufSize, GConverterFlags flags, out size_t bytesRead, out size_t bytesWritten)
156 	{
157 		GError* err = null;
158 		
159 		auto p = g_converter_convert(getConverterStruct(), inbuf.ptr, cast(size_t)inbuf.length, outbuf, outbufSize, flags, &bytesRead, &bytesWritten, &err);
160 		
161 		if (err !is null)
162 		{
163 			throw new GException( new ErrorG(err) );
164 		}
165 		
166 		return p;
167 	}
168 
169 	/**
170 	 * Resets all internal state in the converter, making it behave
171 	 * as if it was just created. If the converter has any internal
172 	 * state that would produce output then that output is lost.
173 	 *
174 	 * Since: 2.24
175 	 */
176 	public void reset()
177 	{
178 		g_converter_reset(getConverterStruct());
179 	}
180 }