gio/auto/

input_stream.rs

// This file was generated by gir (https://github.com/gtk-rs/gir)
// from gir-files (https://github.com/gtk-rs/gir-files)
// DO NOT EDIT

use crate::{ffi, AsyncResult, Cancellable};
use glib::{prelude::*, translate::*};
use std::{boxed::Box as Box_, pin::Pin};

glib::wrapper! {
    /// `GInputStream` is a base class for implementing streaming input.
    ///
    /// It has functions to read from a stream ([`InputStreamExtManual::read()`][crate::prelude::InputStreamExtManual::read()]),
    /// to close a stream ([`InputStreamExt::close()`][crate::prelude::InputStreamExt::close()]) and to skip some content
    /// ([`InputStreamExt::skip()`][crate::prelude::InputStreamExt::skip()]).
    ///
    /// To copy the content of an input stream to an output stream without
    /// manually handling the reads and writes, use [`OutputStreamExt::splice()`][crate::prelude::OutputStreamExt::splice()].
    ///
    /// See the documentation for [`IOStream`][crate::IOStream] for details of thread safety
    /// of streaming APIs.
    ///
    /// All of these functions have async variants too.
    ///
    /// This is an Abstract Base Class, you cannot instantiate it.
    ///
    /// # Implements
    ///
    /// [`InputStreamExt`][trait@crate::prelude::InputStreamExt], [`trait@glib::ObjectExt`], [`InputStreamExtManual`][trait@crate::prelude::InputStreamExtManual]
    #[doc(alias = "GInputStream")]
    pub struct InputStream(Object<ffi::GInputStream, ffi::GInputStreamClass>);

    match fn {
        type_ => || ffi::g_input_stream_get_type(),
    }
}

impl InputStream {
    pub const NONE: Option<&'static InputStream> = None;
}

/// Trait containing all [`struct@InputStream`] methods.
///
/// # Implementors
///
/// [`FileInputStream`][struct@crate::FileInputStream], [`FilterInputStream`][struct@crate::FilterInputStream], [`InputStream`][struct@crate::InputStream], [`MemoryInputStream`][struct@crate::MemoryInputStream], [`PollableInputStream`][struct@crate::PollableInputStream], [`UnixInputStream`][struct@crate::UnixInputStream]
pub trait InputStreamExt: IsA<InputStream> + 'static {
    /// Clears the pending flag on @self.
    #[doc(alias = "g_input_stream_clear_pending")]
    fn clear_pending(&self) {
        unsafe {
            ffi::g_input_stream_clear_pending(self.as_ref().to_glib_none().0);
        }
    }

    /// Closes the stream, releasing resources related to it.
    ///
    /// Once the stream is closed, all other operations will return [`IOErrorEnum::Closed`][crate::IOErrorEnum::Closed].
    /// Closing a stream multiple times will not return an error.
    ///
    /// Streams will be automatically closed when the last reference
    /// is dropped, but you might want to call this function to make sure
    /// resources are released as early as possible.
    ///
    /// Some streams might keep the backing store of the stream (e.g. a file descriptor)
    /// open after the stream is closed. See the documentation for the individual
    /// stream for details.
    ///
    /// On failure the first error that happened will be reported, but the close
    /// operation will finish as much as possible. A stream that failed to
    /// close will still return [`IOErrorEnum::Closed`][crate::IOErrorEnum::Closed] for all operations. Still, it
    /// is important to check and report the error to the user.
    ///
    /// If @cancellable is not [`None`], then the operation can be cancelled by
    /// triggering the cancellable object from another thread. If the operation
    /// was cancelled, the error [`IOErrorEnum::Cancelled`][crate::IOErrorEnum::Cancelled] will be returned.
    /// Cancelling a close will still leave the stream closed, but some streams
    /// can use a faster close that doesn't block to e.g. check errors.
    /// ## `cancellable`
    /// optional #GCancellable object, [`None`] to ignore.
    ///
    /// # Returns
    ///
    /// [`true`] on success, [`false`] on failure
    #[doc(alias = "g_input_stream_close")]
    fn close(&self, cancellable: Option<&impl IsA<Cancellable>>) -> Result<(), glib::Error> {
        unsafe {
            let mut error = std::ptr::null_mut();
            let is_ok = ffi::g_input_stream_close(
                self.as_ref().to_glib_none().0,
                cancellable.map(|p| p.as_ref()).to_glib_none().0,
                &mut error,
            );
            debug_assert_eq!(is_ok == glib::ffi::GFALSE, !error.is_null());
            if error.is_null() {
                Ok(())
            } else {
                Err(from_glib_full(error))
            }
        }
    }

    /// Requests an asynchronous closes of the stream, releasing resources related to it.
    /// When the operation is finished @callback will be called.
    /// You can then call g_input_stream_close_finish() to get the result of the
    /// operation.
    ///
    /// For behaviour details see g_input_stream_close().
    ///
    /// The asynchronous methods have a default fallback that uses threads to implement
    /// asynchronicity, so they are optional for inheriting classes. However, if you
    /// override one you must override all.
    /// ## `io_priority`
    /// the [I/O priority](iface.AsyncResult.html#io-priority) of the request
    /// ## `cancellable`
    /// optional cancellable object
    /// ## `callback`
    /// a #GAsyncReadyCallback
    ///   to call when the request is satisfied
    #[doc(alias = "g_input_stream_close_async")]
    fn close_async<P: FnOnce(Result<(), glib::Error>) + 'static>(
        &self,
        io_priority: glib::Priority,
        cancellable: Option<&impl IsA<Cancellable>>,
        callback: P,
    ) {
        let main_context = glib::MainContext::ref_thread_default();
        let is_main_context_owner = main_context.is_owner();
        let has_acquired_main_context = (!is_main_context_owner)
            .then(|| main_context.acquire().ok())
            .flatten();
        assert!(
            is_main_context_owner || has_acquired_main_context.is_some(),
            "Async operations only allowed if the thread is owning the MainContext"
        );

        let user_data: Box_<glib::thread_guard::ThreadGuard<P>> =
            Box_::new(glib::thread_guard::ThreadGuard::new(callback));
        unsafe extern "C" fn close_async_trampoline<
            P: FnOnce(Result<(), glib::Error>) + 'static,
        >(
            _source_object: *mut glib::gobject_ffi::GObject,
            res: *mut crate::ffi::GAsyncResult,
            user_data: glib::ffi::gpointer,
        ) {
            let mut error = std::ptr::null_mut();
            let _ = ffi::g_input_stream_close_finish(_source_object as *mut _, res, &mut error);
            let result = if error.is_null() {
                Ok(())
            } else {
                Err(from_glib_full(error))
            };
            let callback: Box_<glib::thread_guard::ThreadGuard<P>> =
                Box_::from_raw(user_data as *mut _);
            let callback: P = callback.into_inner();
            callback(result);
        }
        let callback = close_async_trampoline::<P>;
        unsafe {
            ffi::g_input_stream_close_async(
                self.as_ref().to_glib_none().0,
                io_priority.into_glib(),
                cancellable.map(|p| p.as_ref()).to_glib_none().0,
                Some(callback),
                Box_::into_raw(user_data) as *mut _,
            );
        }
    }

    fn close_future(
        &self,
        io_priority: glib::Priority,
    ) -> Pin<Box_<dyn std::future::Future<Output = Result<(), glib::Error>> + 'static>> {
        Box_::pin(crate::GioFuture::new(
            self,
            move |obj, cancellable, send| {
                obj.close_async(io_priority, Some(cancellable), move |res| {
                    send.resolve(res);
                });
            },
        ))
    }

    /// Checks if an input stream has pending actions.
    ///
    /// # Returns
    ///
    /// [`true`] if @self has pending actions.
    #[doc(alias = "g_input_stream_has_pending")]
    fn has_pending(&self) -> bool {
        unsafe {
            from_glib(ffi::g_input_stream_has_pending(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Checks if an input stream is closed.
    ///
    /// # Returns
    ///
    /// [`true`] if the stream is closed.
    #[doc(alias = "g_input_stream_is_closed")]
    fn is_closed(&self) -> bool {
        unsafe {
            from_glib(ffi::g_input_stream_is_closed(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Like g_input_stream_read(), this tries to read @count bytes from
    /// the stream in a blocking fashion. However, rather than reading into
    /// a user-supplied buffer, this will create a new #GBytes containing
    /// the data that was read. This may be easier to use from language
    /// bindings.
    ///
    /// If count is zero, returns a zero-length #GBytes and does nothing. A
    /// value of @count larger than `G_MAXSSIZE` will cause a
    /// [`IOErrorEnum::InvalidArgument`][crate::IOErrorEnum::InvalidArgument] error.
    ///
    /// On success, a new #GBytes is returned. It is not an error if the
    /// size of this object is not the same as the requested size, as it
    /// can happen e.g. near the end of a file. A zero-length #GBytes is
    /// returned on end of file (or if @count is zero), but never
    /// otherwise.
    ///
    /// If @cancellable is not [`None`], then the operation can be cancelled by
    /// triggering the cancellable object from another thread. If the operation
    /// was cancelled, the error [`IOErrorEnum::Cancelled`][crate::IOErrorEnum::Cancelled] will be returned. If an
    /// operation was partially finished when the operation was cancelled the
    /// partial result will be returned, without an error.
    ///
    /// On error [`None`] is returned and @error is set accordingly.
    /// ## `count`
    /// maximum number of bytes that will be read from the stream. Common
    /// values include 4096 and 8192.
    /// ## `cancellable`
    /// optional #GCancellable object, [`None`] to ignore.
    ///
    /// # Returns
    ///
    /// a new #GBytes, or [`None`] on error
    #[doc(alias = "g_input_stream_read_bytes")]
    fn read_bytes(
        &self,
        count: usize,
        cancellable: Option<&impl IsA<Cancellable>>,
    ) -> Result<glib::Bytes, glib::Error> {
        unsafe {
            let mut error = std::ptr::null_mut();
            let ret = ffi::g_input_stream_read_bytes(
                self.as_ref().to_glib_none().0,
                count,
                cancellable.map(|p| p.as_ref()).to_glib_none().0,
                &mut error,
            );
            if error.is_null() {
                Ok(from_glib_full(ret))
            } else {
                Err(from_glib_full(error))
            }
        }
    }

    /// Request an asynchronous read of @count bytes from the stream into a
    /// new #GBytes. When the operation is finished @callback will be
    /// called. You can then call g_input_stream_read_bytes_finish() to get the
    /// result of the operation.
    ///
    /// During an async request no other sync and async calls are allowed
    /// on @self, and will result in [`IOErrorEnum::Pending`][crate::IOErrorEnum::Pending] errors.
    ///
    /// A value of @count larger than `G_MAXSSIZE` will cause a
    /// [`IOErrorEnum::InvalidArgument`][crate::IOErrorEnum::InvalidArgument] error.
    ///
    /// On success, the new #GBytes will be passed to the callback. It is
    /// not an error if this is smaller than the requested size, as it can
    /// happen e.g. near the end of a file, but generally we try to read as
    /// many bytes as requested. Zero is returned on end of file (or if
    /// @count is zero), but never otherwise.
    ///
    /// Any outstanding I/O request with higher priority (lower numerical
    /// value) will be executed before an outstanding request with lower
    /// priority. Default priority is `G_PRIORITY_DEFAULT`.
    /// ## `count`
    /// the number of bytes that will be read from the stream
    /// ## `io_priority`
    /// the [I/O priority](iface.AsyncResult.html#io-priority) of the request
    /// ## `cancellable`
    /// optional #GCancellable object, [`None`] to ignore.
    /// ## `callback`
    /// a #GAsyncReadyCallback
    ///   to call when the request is satisfied
    #[doc(alias = "g_input_stream_read_bytes_async")]
    fn read_bytes_async<P: FnOnce(Result<glib::Bytes, glib::Error>) + 'static>(
        &self,
        count: usize,
        io_priority: glib::Priority,
        cancellable: Option<&impl IsA<Cancellable>>,
        callback: P,
    ) {
        let main_context = glib::MainContext::ref_thread_default();
        let is_main_context_owner = main_context.is_owner();
        let has_acquired_main_context = (!is_main_context_owner)
            .then(|| main_context.acquire().ok())
            .flatten();
        assert!(
            is_main_context_owner || has_acquired_main_context.is_some(),
            "Async operations only allowed if the thread is owning the MainContext"
        );

        let user_data: Box_<glib::thread_guard::ThreadGuard<P>> =
            Box_::new(glib::thread_guard::ThreadGuard::new(callback));
        unsafe extern "C" fn read_bytes_async_trampoline<
            P: FnOnce(Result<glib::Bytes, glib::Error>) + 'static,
        >(
            _source_object: *mut glib::gobject_ffi::GObject,
            res: *mut crate::ffi::GAsyncResult,
            user_data: glib::ffi::gpointer,
        ) {
            let mut error = std::ptr::null_mut();
            let ret =
                ffi::g_input_stream_read_bytes_finish(_source_object as *mut _, res, &mut error);
            let result = if error.is_null() {
                Ok(from_glib_full(ret))
            } else {
                Err(from_glib_full(error))
            };
            let callback: Box_<glib::thread_guard::ThreadGuard<P>> =
                Box_::from_raw(user_data as *mut _);
            let callback: P = callback.into_inner();
            callback(result);
        }
        let callback = read_bytes_async_trampoline::<P>;
        unsafe {
            ffi::g_input_stream_read_bytes_async(
                self.as_ref().to_glib_none().0,
                count,
                io_priority.into_glib(),
                cancellable.map(|p| p.as_ref()).to_glib_none().0,
                Some(callback),
                Box_::into_raw(user_data) as *mut _,
            );
        }
    }

    fn read_bytes_future(
        &self,
        count: usize,
        io_priority: glib::Priority,
    ) -> Pin<Box_<dyn std::future::Future<Output = Result<glib::Bytes, glib::Error>> + 'static>>
    {
        Box_::pin(crate::GioFuture::new(
            self,
            move |obj, cancellable, send| {
                obj.read_bytes_async(count, io_priority, Some(cancellable), move |res| {
                    send.resolve(res);
                });
            },
        ))
    }

    /// Sets @self to have actions pending. If the pending flag is
    /// already set or @self is closed, it will return [`false`] and set
    /// @error.
    ///
    /// # Returns
    ///
    /// [`true`] if pending was previously unset and is now set.
    #[doc(alias = "g_input_stream_set_pending")]
    fn set_pending(&self) -> Result<(), glib::Error> {
        unsafe {
            let mut error = std::ptr::null_mut();
            let is_ok = ffi::g_input_stream_set_pending(self.as_ref().to_glib_none().0, &mut error);
            debug_assert_eq!(is_ok == glib::ffi::GFALSE, !error.is_null());
            if error.is_null() {
                Ok(())
            } else {
                Err(from_glib_full(error))
            }
        }
    }

    /// Tries to skip @count bytes from the stream. Will block during the operation.
    ///
    /// This is identical to g_input_stream_read(), from a behaviour standpoint,
    /// but the bytes that are skipped are not returned to the user. Some
    /// streams have an implementation that is more efficient than reading the data.
    ///
    /// This function is optional for inherited classes, as the default implementation
    /// emulates it using read.
    ///
    /// If @cancellable is not [`None`], then the operation can be cancelled by
    /// triggering the cancellable object from another thread. If the operation
    /// was cancelled, the error [`IOErrorEnum::Cancelled`][crate::IOErrorEnum::Cancelled] will be returned. If an
    /// operation was partially finished when the operation was cancelled the
    /// partial result will be returned, without an error.
    /// ## `count`
    /// the number of bytes that will be skipped from the stream
    /// ## `cancellable`
    /// optional #GCancellable object, [`None`] to ignore.
    ///
    /// # Returns
    ///
    /// Number of bytes skipped, or -1 on error
    #[doc(alias = "g_input_stream_skip")]
    fn skip(
        &self,
        count: usize,
        cancellable: Option<&impl IsA<Cancellable>>,
    ) -> Result<isize, glib::Error> {
        unsafe {
            let mut error = std::ptr::null_mut();
            let ret = ffi::g_input_stream_skip(
                self.as_ref().to_glib_none().0,
                count,
                cancellable.map(|p| p.as_ref()).to_glib_none().0,
                &mut error,
            );
            if error.is_null() {
                Ok(ret)
            } else {
                Err(from_glib_full(error))
            }
        }
    }

    /// Request an asynchronous skip of @count bytes from the stream.
    /// When the operation is finished @callback will be called.
    /// You can then call g_input_stream_skip_finish() to get the result
    /// of the operation.
    ///
    /// During an async request no other sync and async calls are allowed,
    /// and will result in [`IOErrorEnum::Pending`][crate::IOErrorEnum::Pending] errors.
    ///
    /// A value of @count larger than `G_MAXSSIZE` will cause a [`IOErrorEnum::InvalidArgument`][crate::IOErrorEnum::InvalidArgument] error.
    ///
    /// On success, the number of bytes skipped will be passed to the callback.
    /// It is not an error if this is not the same as the requested size, as it
    /// can happen e.g. near the end of a file, but generally we try to skip
    /// as many bytes as requested. Zero is returned on end of file
    /// (or if @count is zero), but never otherwise.
    ///
    /// Any outstanding i/o request with higher priority (lower numerical value)
    /// will be executed before an outstanding request with lower priority.
    /// Default priority is `G_PRIORITY_DEFAULT`.
    ///
    /// The asynchronous methods have a default fallback that uses threads to
    /// implement asynchronicity, so they are optional for inheriting classes.
    /// However, if you override one, you must override all.
    /// ## `count`
    /// the number of bytes that will be skipped from the stream
    /// ## `io_priority`
    /// the [I/O priority](iface.AsyncResult.html#io-priority) of the request
    /// ## `cancellable`
    /// optional #GCancellable object, [`None`] to ignore.
    /// ## `callback`
    /// a #GAsyncReadyCallback
    ///   to call when the request is satisfied
    #[doc(alias = "g_input_stream_skip_async")]
    fn skip_async<P: FnOnce(Result<isize, glib::Error>) + 'static>(
        &self,
        count: usize,
        io_priority: glib::Priority,
        cancellable: Option<&impl IsA<Cancellable>>,
        callback: P,
    ) {
        let main_context = glib::MainContext::ref_thread_default();
        let is_main_context_owner = main_context.is_owner();
        let has_acquired_main_context = (!is_main_context_owner)
            .then(|| main_context.acquire().ok())
            .flatten();
        assert!(
            is_main_context_owner || has_acquired_main_context.is_some(),
            "Async operations only allowed if the thread is owning the MainContext"
        );

        let user_data: Box_<glib::thread_guard::ThreadGuard<P>> =
            Box_::new(glib::thread_guard::ThreadGuard::new(callback));
        unsafe extern "C" fn skip_async_trampoline<
            P: FnOnce(Result<isize, glib::Error>) + 'static,
        >(
            _source_object: *mut glib::gobject_ffi::GObject,
            res: *mut crate::ffi::GAsyncResult,
            user_data: glib::ffi::gpointer,
        ) {
            let mut error = std::ptr::null_mut();
            let ret = ffi::g_input_stream_skip_finish(_source_object as *mut _, res, &mut error);
            let result = if error.is_null() {
                Ok(ret)
            } else {
                Err(from_glib_full(error))
            };
            let callback: Box_<glib::thread_guard::ThreadGuard<P>> =
                Box_::from_raw(user_data as *mut _);
            let callback: P = callback.into_inner();
            callback(result);
        }
        let callback = skip_async_trampoline::<P>;
        unsafe {
            ffi::g_input_stream_skip_async(
                self.as_ref().to_glib_none().0,
                count,
                io_priority.into_glib(),
                cancellable.map(|p| p.as_ref()).to_glib_none().0,
                Some(callback),
                Box_::into_raw(user_data) as *mut _,
            );
        }
    }

    fn skip_future(
        &self,
        count: usize,
        io_priority: glib::Priority,
    ) -> Pin<Box_<dyn std::future::Future<Output = Result<isize, glib::Error>> + 'static>> {
        Box_::pin(crate::GioFuture::new(
            self,
            move |obj, cancellable, send| {
                obj.skip_async(count, io_priority, Some(cancellable), move |res| {
                    send.resolve(res);
                });
            },
        ))
    }
}

impl<O: IsA<InputStream>> InputStreamExt for O {}