gio/auto/

subprocess_launcher.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, Subprocess, SubprocessFlags};
use glib::translate::*;
#[cfg(unix)]
#[cfg_attr(docsrs, doc(cfg(unix)))]
use std::boxed::Box as Box_;

glib::wrapper! {
    /// This class contains a set of options for launching child processes,
    /// such as where its standard input and output will be directed, the
    /// argument list, the environment, and more.
    ///
    /// While the [`Subprocess`][crate::Subprocess] class has high level functions covering
    /// popular cases, use of this class allows access to more advanced
    /// options.  It can also be used to launch multiple subprocesses with
    /// a similar configuration.
    ///
    /// ## Properties
    ///
    ///
    /// #### `flags`
    ///  [`SubprocessFlags`][crate::SubprocessFlags] for launched processes.
    ///
    /// Writeable | Construct Only
    ///
    /// # Implements
    ///
    /// [`trait@glib::ObjectExt`]
    #[doc(alias = "GSubprocessLauncher")]
    pub struct SubprocessLauncher(Object<ffi::GSubprocessLauncher>);

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

impl SubprocessLauncher {
    /// Creates a new #GSubprocessLauncher.
    ///
    /// The launcher is created with the default options.  A copy of the
    /// environment of the calling process is made at the time of this call
    /// and will be used as the environment that the process is launched in.
    /// ## `flags`
    /// #GSubprocessFlags
    #[doc(alias = "g_subprocess_launcher_new")]
    pub fn new(flags: SubprocessFlags) -> SubprocessLauncher {
        unsafe { from_glib_full(ffi::g_subprocess_launcher_new(flags.into_glib())) }
    }

    /// Closes all the file descriptors previously passed to the object with
    /// g_subprocess_launcher_take_fd(), g_subprocess_launcher_take_stderr_fd(), etc.
    ///
    /// After calling this method, any subsequent calls to g_subprocess_launcher_spawn() or g_subprocess_launcher_spawnv() will
    /// return [`IOErrorEnum::Closed`][crate::IOErrorEnum::Closed]. This method is idempotent if
    /// called more than once.
    ///
    /// This function is called automatically when the #GSubprocessLauncher
    /// is disposed, but is provided separately so that garbage collected
    /// language bindings can call it earlier to guarantee when FDs are closed.
    #[cfg(unix)]
    #[cfg_attr(docsrs, doc(cfg(unix)))]
    #[cfg(feature = "v2_68")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v2_68")))]
    #[doc(alias = "g_subprocess_launcher_close")]
    pub fn close(&self) {
        unsafe {
            ffi::g_subprocess_launcher_close(self.to_glib_none().0);
        }
    }

    /// Returns the value of the environment variable @variable in the
    /// environment of processes launched from this launcher.
    ///
    /// On UNIX, the returned string can be an arbitrary byte string.
    /// On Windows, it will be UTF-8.
    /// ## `variable`
    /// the environment variable to get
    ///
    /// # Returns
    ///
    /// the value of the environment variable,
    ///     [`None`] if unset
    #[doc(alias = "g_subprocess_launcher_getenv")]
    pub fn getenv(&self, variable: impl AsRef<std::path::Path>) -> Option<std::path::PathBuf> {
        unsafe {
            from_glib_none(ffi::g_subprocess_launcher_getenv(
                self.to_glib_none().0,
                variable.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Sets up a child setup function.
    ///
    /// The child setup function will be called after fork() but before
    /// exec() on the child's side.
    ///
    /// @destroy_notify will not be automatically called on the child's side
    /// of the fork().  It will only be called when the last reference on the
    /// #GSubprocessLauncher is dropped or when a new child setup function is
    /// given.
    ///
    /// [`None`] can be given as @child_setup to disable the functionality.
    ///
    /// Child setup functions are only available on UNIX.
    /// ## `child_setup`
    /// a #GSpawnChildSetupFunc to use as the child setup function
    /// ## `destroy_notify`
    /// a #GDestroyNotify for @user_data
    #[cfg(unix)]
    #[cfg_attr(docsrs, doc(cfg(unix)))]
    #[doc(alias = "g_subprocess_launcher_set_child_setup")]
    pub fn set_child_setup<P: Fn() + 'static>(&self, child_setup: P) {
        let child_setup_data: Box_<P> = Box_::new(child_setup);
        unsafe extern "C" fn child_setup_func<P: Fn() + 'static>(data: glib::ffi::gpointer) {
            let callback = &*(data as *mut P);
            (*callback)()
        }
        let child_setup = Some(child_setup_func::<P> as _);
        unsafe extern "C" fn destroy_notify_func<P: Fn() + 'static>(data: glib::ffi::gpointer) {
            let _callback = Box_::from_raw(data as *mut P);
        }
        let destroy_call3 = Some(destroy_notify_func::<P> as _);
        let super_callback0: Box_<P> = child_setup_data;
        unsafe {
            ffi::g_subprocess_launcher_set_child_setup(
                self.to_glib_none().0,
                child_setup,
                Box_::into_raw(super_callback0) as *mut _,
                destroy_call3,
            );
        }
    }

    /// Sets the current working directory that processes will be launched
    /// with.
    ///
    /// By default processes are launched with the current working directory
    /// of the launching process at the time of launch.
    /// ## `cwd`
    /// the cwd for launched processes
    #[doc(alias = "g_subprocess_launcher_set_cwd")]
    pub fn set_cwd(&self, cwd: impl AsRef<std::path::Path>) {
        unsafe {
            ffi::g_subprocess_launcher_set_cwd(
                self.to_glib_none().0,
                cwd.as_ref().to_glib_none().0,
            );
        }
    }

    /// Replace the entire environment of processes launched from this
    /// launcher with the given 'environ' variable.
    ///
    /// Typically you will build this variable by using g_listenv() to copy
    /// the process 'environ' and using the functions g_environ_setenv(),
    /// g_environ_unsetenv(), etc.
    ///
    /// As an alternative, you can use g_subprocess_launcher_setenv(),
    /// g_subprocess_launcher_unsetenv(), etc.
    ///
    /// Pass an empty array to set an empty environment. Pass [`None`] to inherit the
    /// parent process’ environment. As of GLib 2.54, the parent process’ environment
    /// will be copied when g_subprocess_launcher_set_environ() is called.
    /// Previously, it was copied when the subprocess was executed. This means the
    /// copied environment may now be modified (using g_subprocess_launcher_setenv(),
    /// etc.) before launching the subprocess.
    ///
    /// On UNIX, all strings in this array can be arbitrary byte strings.
    /// On Windows, they should be in UTF-8.
    /// ## `env`
    ///
    ///     the replacement environment
    #[doc(alias = "g_subprocess_launcher_set_environ")]
    pub fn set_environ(&self, env: &[&std::path::Path]) {
        unsafe {
            ffi::g_subprocess_launcher_set_environ(self.to_glib_none().0, env.to_glib_none().0);
        }
    }

    /// Sets the flags on the launcher.
    ///
    /// The default flags are [`SubprocessFlags::NONE`][crate::SubprocessFlags::NONE].
    ///
    /// You may not set flags that specify conflicting options for how to
    /// handle a particular stdio stream (eg: specifying both
    /// [`SubprocessFlags::STDIN_PIPE`][crate::SubprocessFlags::STDIN_PIPE] and
    /// [`SubprocessFlags::STDIN_INHERIT`][crate::SubprocessFlags::STDIN_INHERIT]).
    ///
    /// You may also not set a flag that conflicts with a previous call to a
    /// function like g_subprocess_launcher_set_stdin_file_path() or
    /// g_subprocess_launcher_take_stdout_fd().
    /// ## `flags`
    /// #GSubprocessFlags
    #[doc(alias = "g_subprocess_launcher_set_flags")]
    pub fn set_flags(&self, flags: SubprocessFlags) {
        unsafe {
            ffi::g_subprocess_launcher_set_flags(self.to_glib_none().0, flags.into_glib());
        }
    }

    /// Sets the file path to use as the stderr for spawned processes.
    ///
    /// If @path is [`None`] then any previously given path is unset.
    ///
    /// The file will be created or truncated when the process is spawned, as
    /// would be the case if using '2>' at the shell.
    ///
    /// If you want to send both stdout and stderr to the same file then use
    /// [`SubprocessFlags::STDERR_MERGE`][crate::SubprocessFlags::STDERR_MERGE].
    ///
    /// You may not set a stderr file path if a stderr fd is already set or
    /// if the launcher flags contain any flags directing stderr elsewhere.
    ///
    /// This feature is only available on UNIX.
    /// ## `path`
    /// a filename or [`None`]
    #[cfg(unix)]
    #[cfg_attr(docsrs, doc(cfg(unix)))]
    #[doc(alias = "g_subprocess_launcher_set_stderr_file_path")]
    pub fn set_stderr_file_path(&self, path: Option<impl AsRef<std::path::Path>>) {
        unsafe {
            ffi::g_subprocess_launcher_set_stderr_file_path(
                self.to_glib_none().0,
                path.as_ref().map(|p| p.as_ref()).to_glib_none().0,
            );
        }
    }

    /// Sets the file path to use as the stdin for spawned processes.
    ///
    /// If @path is [`None`] then any previously given path is unset.
    ///
    /// The file must exist or spawning the process will fail.
    ///
    /// You may not set a stdin file path if a stdin fd is already set or if
    /// the launcher flags contain any flags directing stdin elsewhere.
    ///
    /// This feature is only available on UNIX.
    /// ## `path`
    /// a filename or [`None`]
    #[cfg(unix)]
    #[cfg_attr(docsrs, doc(cfg(unix)))]
    #[doc(alias = "g_subprocess_launcher_set_stdin_file_path")]
    pub fn set_stdin_file_path(&self, path: Option<impl AsRef<std::path::Path>>) {
        unsafe {
            ffi::g_subprocess_launcher_set_stdin_file_path(
                self.to_glib_none().0,
                path.as_ref().map(|p| p.as_ref()).to_glib_none().0,
            );
        }
    }

    /// Sets the file path to use as the stdout for spawned processes.
    ///
    /// If @path is [`None`] then any previously given path is unset.
    ///
    /// The file will be created or truncated when the process is spawned, as
    /// would be the case if using '>' at the shell.
    ///
    /// You may not set a stdout file path if a stdout fd is already set or
    /// if the launcher flags contain any flags directing stdout elsewhere.
    ///
    /// This feature is only available on UNIX.
    /// ## `path`
    /// a filename or [`None`]
    #[cfg(unix)]
    #[cfg_attr(docsrs, doc(cfg(unix)))]
    #[doc(alias = "g_subprocess_launcher_set_stdout_file_path")]
    pub fn set_stdout_file_path(&self, path: Option<impl AsRef<std::path::Path>>) {
        unsafe {
            ffi::g_subprocess_launcher_set_stdout_file_path(
                self.to_glib_none().0,
                path.as_ref().map(|p| p.as_ref()).to_glib_none().0,
            );
        }
    }

    /// Sets the environment variable @variable in the environment of
    /// processes launched from this launcher.
    ///
    /// On UNIX, both the variable's name and value can be arbitrary byte
    /// strings, except that the variable's name cannot contain '='.
    /// On Windows, they should be in UTF-8.
    /// ## `variable`
    /// the environment variable to set,
    ///     must not contain '='
    /// ## `value`
    /// the new value for the variable
    /// ## `overwrite`
    /// whether to change the variable if it already exists
    #[doc(alias = "g_subprocess_launcher_setenv")]
    pub fn setenv(
        &self,
        variable: impl AsRef<std::ffi::OsStr>,
        value: impl AsRef<std::ffi::OsStr>,
        overwrite: bool,
    ) {
        unsafe {
            ffi::g_subprocess_launcher_setenv(
                self.to_glib_none().0,
                variable.as_ref().to_glib_none().0,
                value.as_ref().to_glib_none().0,
                overwrite.into_glib(),
            );
        }
    }

    //#[doc(alias = "g_subprocess_launcher_spawn")]
    //pub fn spawn(&self, error: &mut glib::Error, argv0: &str, : /*Unknown conversion*//*Unimplemented*/Basic: VarArgs) -> Subprocess {
    //    unsafe { TODO: call ffi:g_subprocess_launcher_spawn() }
    //}

    /// Creates a #GSubprocess given a provided varargs list of arguments.
    /// ## `argv0`
    /// Command line arguments
    ///
    /// # Returns
    ///
    /// A new #GSubprocess, or [`None`] on error (and @error will be set)
    #[doc(alias = "g_subprocess_launcher_spawnv")]
    #[doc(alias = "spawnv")]
    pub fn spawn(&self, argv: &[&std::ffi::OsStr]) -> Result<Subprocess, glib::Error> {
        unsafe {
            let mut error = std::ptr::null_mut();
            let ret = ffi::g_subprocess_launcher_spawnv(
                self.to_glib_none().0,
                argv.to_glib_none().0,
                &mut error,
            );
            if error.is_null() {
                Ok(from_glib_full(ret))
            } else {
                Err(from_glib_full(error))
            }
        }
    }

    /// Removes the environment variable @variable from the environment of
    /// processes launched from this launcher.
    ///
    /// On UNIX, the variable's name can be an arbitrary byte string not
    /// containing '='. On Windows, it should be in UTF-8.
    /// ## `variable`
    /// the environment variable to unset,
    ///     must not contain '='
    #[doc(alias = "g_subprocess_launcher_unsetenv")]
    pub fn unsetenv(&self, variable: impl AsRef<std::ffi::OsStr>) {
        unsafe {
            ffi::g_subprocess_launcher_unsetenv(
                self.to_glib_none().0,
                variable.as_ref().to_glib_none().0,
            );
        }
    }
}