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 }