gio/

converter.rs

// 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::{ffi, Converter, ConverterFlags, ConverterResult};

pub trait ConverterExtManual: 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 g_converter_convert() has returned [`ConverterResult::Finished`][crate::ConverterResult::Finished] the
    /// converter object is in an invalid state where its not allowed
    /// to call g_converter_convert() anymore. At this time you can only
    /// free the object or call g_converter_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 #GConverterFlags controlling the conversion details
    ///
    /// # Returns
    ///
    /// a #GConverterResult, [`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 {}