1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162

// Take a look at the license at the top of the repository in the LICENSE file.

use std::{mem, ptr};

use glib::{prelude::*, translate::*};

use crate::{Converter, ConverterFlags, ConverterResult};

mod sealed {
    pub trait Sealed {}
    impl<T: super::IsA<super::Converter>> Sealed for T {}
}

pub trait ConverterExtManual: sealed::Sealed + IsA<Converter> + 'static {
    /// This is the main operation used when converting data. It is to be called
    /// multiple times in a loop, and each time it will do some work, i.e.
    /// producing some output (in `outbuf`) or consuming some input (from `inbuf`) or
    /// both. If its not possible to do any work an error is returned.
    ///
    /// Note that a single call may not consume all input (or any input at all).
    /// Also a call may produce output even if given no input, due to state stored
    /// in the converter producing output.
    ///
    /// If any data was either produced or consumed, and then an error happens, then
    /// only the successful conversion is reported and the error is returned on the
    /// next call.
    ///
    /// A full conversion loop involves calling this method repeatedly, each time
    /// giving it new input and space output space. When there is no more input
    /// data after the data in `inbuf`, the flag [`ConverterFlags::INPUT_AT_END`][crate::ConverterFlags::INPUT_AT_END] must be set.
    /// The loop will be (unless some error happens) returning [`ConverterResult::Converted`][crate::ConverterResult::Converted]
    /// each time until all data is consumed and all output is produced, then
    /// [`ConverterResult::Finished`][crate::ConverterResult::Finished] is returned instead. Note, that [`ConverterResult::Finished`][crate::ConverterResult::Finished]
    /// may be returned even if [`ConverterFlags::INPUT_AT_END`][crate::ConverterFlags::INPUT_AT_END] is not set, for instance
    /// in a decompression converter where the end of data is detectable from the
    /// data (and there might even be other data after the end of the compressed data).
    ///
    /// When some data has successfully been converted `bytes_read` and is set to
    /// the number of bytes read from `inbuf`, and `bytes_written` is set to indicate
    /// how many bytes was written to `outbuf`. If there are more data to output
    /// or consume (i.e. unless the [`ConverterFlags::INPUT_AT_END`][crate::ConverterFlags::INPUT_AT_END] is specified) then
    /// [`ConverterResult::Converted`][crate::ConverterResult::Converted] is returned, and if no more data is to be output
    /// then [`ConverterResult::Finished`][crate::ConverterResult::Finished] is returned.
    ///
    /// On error [`ConverterResult::Error`][crate::ConverterResult::Error] is returned and `error` is set accordingly.
    /// Some errors need special handling:
    ///
    /// [`IOErrorEnum::NoSpace`][crate::IOErrorEnum::NoSpace] is returned if there is not enough space
    /// to write the resulting converted data, the application should
    /// call the function again with a larger `outbuf` to continue.
    ///
    /// [`IOErrorEnum::PartialInput`][crate::IOErrorEnum::PartialInput] is returned if there is not enough
    /// input to fully determine what the conversion should produce,
    /// and the [`ConverterFlags::INPUT_AT_END`][crate::ConverterFlags::INPUT_AT_END] flag is not set. This happens for
    /// example with an incomplete multibyte sequence when converting text,
    /// or when a regexp matches up to the end of the input (and may match
    /// further input). It may also happen when `inbuf_size` is zero and
    /// there is no more data to produce.
    ///
    /// When this happens the application should read more input and then
    /// call the function again. If further input shows that there is no
    /// more data call the function again with the same data but with
    /// the [`ConverterFlags::INPUT_AT_END`][crate::ConverterFlags::INPUT_AT_END] flag set. This may cause the conversion
    /// to finish as e.g. in the regexp match case (or, to fail again with
    /// [`IOErrorEnum::PartialInput`][crate::IOErrorEnum::PartialInput] in e.g. a charset conversion where the
    /// input is actually partial).
    ///
    /// After [`ConverterExtManual::convert()`][crate::prelude::ConverterExtManual::convert()] has returned [`ConverterResult::Finished`][crate::ConverterResult::Finished] the
    /// converter object is in an invalid state where its not allowed
    /// to call [`ConverterExtManual::convert()`][crate::prelude::ConverterExtManual::convert()] anymore. At this time you can only
    /// free the object or call [`ConverterExt::reset()`][crate::prelude::ConverterExt::reset()] to reset it to the
    /// initial state.
    ///
    /// If the flag [`ConverterFlags::FLUSH`][crate::ConverterFlags::FLUSH] is set then conversion is modified
    /// to try to write out all internal state to the output. The application
    /// has to call the function multiple times with the flag set, and when
    /// the available input has been consumed and all internal state has
    /// been produced then [`ConverterResult::Flushed`][crate::ConverterResult::Flushed] (or [`ConverterResult::Finished`][crate::ConverterResult::Finished] if
    /// really at the end) is returned instead of [`ConverterResult::Converted`][crate::ConverterResult::Converted].
    /// This is somewhat similar to what happens at the end of the input stream,
    /// but done in the middle of the data.
    ///
    /// This has different meanings for different conversions. For instance
    /// in a compression converter it would mean that we flush all the
    /// compression state into output such that if you uncompress the
    /// compressed data you get back all the input data. Doing this may
    /// make the final file larger due to padding though. Another example
    /// is a regexp conversion, where if you at the end of the flushed data
    /// have a match, but there is also a potential longer match. In the
    /// non-flushed case we would ask for more input, but when flushing we
    /// treat this as the end of input and do the match.
    ///
    /// Flushing is not always possible (like if a charset converter flushes
    /// at a partial multibyte sequence). Converters are supposed to try
    /// to produce as much output as possible and then return an error
    /// (typically [`IOErrorEnum::PartialInput`][crate::IOErrorEnum::PartialInput]).
    /// ## `inbuf`
    /// the buffer
    ///  containing the data to convert.
    /// ## `outbuf`
    /// a
    ///  buffer to write converted data in.
    /// ## `flags`
    /// a [`ConverterFlags`][crate::ConverterFlags] controlling the conversion details
    ///
    /// # Returns
    ///
    /// a [`ConverterResult`][crate::ConverterResult], [`ConverterResult::Error`][crate::ConverterResult::Error] on error.
    ///
    /// ## `bytes_read`
    /// will be set to the number of bytes read
    ///  from `inbuf` on success
    ///
    /// ## `bytes_written`
    /// will be set to the number of bytes
    ///  written to `outbuf` on success
    #[doc(alias = "g_converter_convert")]
    fn convert<IN: AsRef<[u8]>, OUT: AsMut<[u8]>>(
        &self,
        inbuf: IN,
        outbuf: OUT,
        flags: ConverterFlags,
    ) -> Result<(ConverterResult, usize, usize), glib::Error> {
        let inbuf: Box<IN> = Box::new(inbuf);
        let (inbuf_size, inbuf) = {
            let slice = (*inbuf).as_ref();
            (slice.len(), slice.as_ptr())
        };
        let mut outbuf: Box<OUT> = Box::new(outbuf);
        let (outbuf_size, outbuf) = {
            let slice = (*outbuf).as_mut();
            (slice.len(), slice.as_mut_ptr())
        };
        unsafe {
            let mut bytes_read = mem::MaybeUninit::uninit();
            let mut bytes_written = mem::MaybeUninit::uninit();
            let mut error = ptr::null_mut();
            let ret = ffi::g_converter_convert(
                self.as_ref().to_glib_none().0,
                mut_override(inbuf),
                inbuf_size,
                outbuf,
                outbuf_size,
                flags.into_glib(),
                bytes_read.as_mut_ptr(),
                bytes_written.as_mut_ptr(),
                &mut error,
            );
            if error.is_null() {
                Ok((
                    from_glib(ret),
                    bytes_read.assume_init(),
                    bytes_written.assume_init(),
                ))
            } else {
                Err(from_glib_full(error))
            }
        }
    }
}

impl<O: IsA<Converter>> ConverterExtManual for O {}