gio/auto/

application_command_line.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, File, InputStream};
use glib::{
    prelude::*,
    signal::{connect_raw, SignalHandlerId},
    translate::*,
};
use std::boxed::Box as Box_;

glib::wrapper! {
    /// `GApplicationCommandLine` represents a command-line invocation of
    /// an application.
    ///
    /// It is created by [`Application`][crate::Application] and emitted
    /// in the [`command-line`][struct@crate::Application#command-line] signal and virtual function.
    ///
    /// The class contains the list of arguments that the program was invoked
    /// with. It is also possible to query if the commandline invocation was
    /// local (ie: the current process is running in direct response to the
    /// invocation) or remote (ie: some other process forwarded the
    /// commandline to this process).
    ///
    /// The `GApplicationCommandLine` object can provide the @argc and @argv
    /// parameters for use with the `GLib::OptionContext` command-line parsing API,
    /// with the [`ApplicationCommandLineExt::arguments()`][crate::prelude::ApplicationCommandLineExt::arguments()] function. See
    /// [gapplication-example-cmdline3.c][gapplication-example-cmdline3]
    /// for an example.
    ///
    /// The exit status of the originally-invoked process may be set and
    /// messages can be printed to stdout or stderr of that process.
    ///
    /// For remote invocation, the originally-invoked process exits when
    /// [`ApplicationCommandLineExt::done()`][crate::prelude::ApplicationCommandLineExt::done()] method is called. This method is
    /// also automatically called when the object is disposed.
    ///
    /// The main use for `GApplicationCommandLine` (and the
    /// [`command-line`][struct@crate::Application#command-line] signal) is 'Emacs server' like use cases:
    /// You can set the `EDITOR` environment variable to have e.g. git use
    /// your favourite editor to edit commit messages, and if you already
    /// have an instance of the editor running, the editing will happen
    /// in the running instance, instead of opening a new one. An important
    /// aspect of this use case is that the process that gets started by git
    /// does not return until the editing is done.
    ///
    /// Normally, the commandline is completely handled in the
    /// [`command-line`][struct@crate::Application#command-line] handler. The launching instance exits
    /// once the signal handler in the primary instance has returned, and
    /// the return value of the signal handler becomes the exit status
    /// of the launching instance.
    ///
    /// **⚠️ The following code is in c ⚠️**
    ///
    /// ```c
    /// static int
    /// command_line (GApplication            *application,
    ///               GApplicationCommandLine *cmdline)
    /// {
    ///   gchar **argv;
    ///   gint argc;
    ///   gint i;
    ///
    ///   argv = g_application_command_line_get_arguments (cmdline, &argc);
    ///
    ///   g_application_command_line_print (cmdline,
    ///                                     "This text is written back\n"
    ///                                     "to stdout of the caller\n");
    ///
    ///   for (i = 0; i < argc; i++)
    ///     g_print ("argument %d: %s\n", i, argv[i]);
    ///
    ///   g_strfreev (argv);
    ///
    ///   return 0;
    /// }
    /// ```
    ///
    /// The complete example can be found here:
    /// [gapplication-example-cmdline.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gapplication-example-cmdline.c)
    ///
    /// In more complicated cases, the handling of the commandline can be
    /// split between the launcher and the primary instance.
    ///
    /// **⚠️ The following code is in c ⚠️**
    ///
    /// ```c
    /// static gboolean
    ///  test_local_cmdline (GApplication   *application,
    ///                      gchar        ***arguments,
    ///                      gint           *exit_status)
    /// {
    ///   gint i, j;
    ///   gchar **argv;
    ///
    ///   argv = *arguments;
    ///
    ///   if (argv[0] == NULL)
    ///     {
    ///       *exit_status = 0;
    ///       return FALSE;
    ///     }
    ///
    ///   i = 1;
    ///   while (argv[i])
    ///     {
    ///       if (g_str_has_prefix (argv[i], "--local-"))
    ///         {
    ///           g_print ("handling argument %s locally\n", argv[i]);
    ///           g_free (argv[i]);
    ///           for (j = i; argv[j]; j++)
    ///             argv[j] = argv[j + 1];
    ///         }
    ///       else
    ///         {
    ///           g_print ("not handling argument %s locally\n", argv[i]);
    ///           i++;
    ///         }
    ///     }
    ///
    ///   *exit_status = 0;
    ///
    ///   return FALSE;
    /// }
    ///
    /// static void
    /// test_application_class_init (TestApplicationClass *class)
    /// {
    ///   G_APPLICATION_CLASS (class)->local_command_line = test_local_cmdline;
    ///
    ///   ...
    /// }
    /// ```
    ///
    /// In this example of split commandline handling, options that start
    /// with `--local-` are handled locally, all other options are passed
    /// to the [`command-line`][struct@crate::Application#command-line] handler which runs in the primary
    /// instance.
    ///
    /// The complete example can be found here:
    /// [gapplication-example-cmdline2.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gapplication-example-cmdline2.c)
    ///
    /// If handling the commandline requires a lot of work, it may be better to defer it.
    ///
    /// **⚠️ The following code is in c ⚠️**
    ///
    /// ```c
    /// static gboolean
    /// my_cmdline_handler (gpointer data)
    /// {
    ///   GApplicationCommandLine *cmdline = data;
    ///
    ///   // do the heavy lifting in an idle
    ///
    ///   g_application_command_line_set_exit_status (cmdline, 0);
    ///   g_object_unref (cmdline); // this releases the application
    ///
    ///   return G_SOURCE_REMOVE;
    /// }
    ///
    /// static int
    /// command_line (GApplication            *application,
    ///               GApplicationCommandLine *cmdline)
    /// {
    ///   // keep the application running until we are done with this commandline
    ///   g_application_hold (application);
    ///
    ///   g_object_set_data_full (G_OBJECT (cmdline),
    ///                           "application", application,
    ///                           (GDestroyNotify)g_application_release);
    ///
    ///   g_object_ref (cmdline);
    ///   g_idle_add (my_cmdline_handler, cmdline);
    ///
    ///   return 0;
    /// }
    /// ```
    ///
    /// In this example the commandline is not completely handled before
    /// the [`command-line`][struct@crate::Application#command-line] handler returns. Instead, we keep
    /// a reference to the `GApplicationCommandLine` object and handle it
    /// later (in this example, in an idle). Note that it is necessary to
    /// hold the application until you are done with the commandline.
    ///
    /// The complete example can be found here:
    /// [gapplication-example-cmdline3.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gapplication-example-cmdline3.c)
    ///
    /// ## Properties
    ///
    ///
    /// #### `arguments`
    ///  The commandline that caused this [`command-line`][struct@crate::Application#command-line]
    /// signal emission.
    ///
    /// Writeable | Construct Only
    ///
    ///
    /// #### `is-remote`
    ///  Whether this is a remote commandline.
    ///
    /// Readable
    ///
    ///
    /// #### `options`
    ///  The options sent along with the commandline.
    ///
    /// Writeable | Construct Only
    ///
    ///
    /// #### `platform-data`
    ///  Platform-specific data for the commandline.
    ///
    /// Writeable | Construct Only
    ///
    /// # Implements
    ///
    /// [`ApplicationCommandLineExt`][trait@crate::prelude::ApplicationCommandLineExt], [`trait@glib::ObjectExt`]
    #[doc(alias = "GApplicationCommandLine")]
    pub struct ApplicationCommandLine(Object<ffi::GApplicationCommandLine, ffi::GApplicationCommandLineClass>);

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

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

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

/// Trait containing all [`struct@ApplicationCommandLine`] methods.
///
/// # Implementors
///
/// [`ApplicationCommandLine`][struct@crate::ApplicationCommandLine]
pub trait ApplicationCommandLineExt:
    IsA<ApplicationCommandLine> + sealed::Sealed + 'static
{
    /// Creates a #GFile corresponding to a filename that was given as part
    /// of the invocation of @self.
    ///
    /// This differs from g_file_new_for_commandline_arg() in that it
    /// resolves relative pathnames using the current working directory of
    /// the invoking process rather than the local process.
    /// ## `arg`
    /// an argument from @self
    ///
    /// # Returns
    ///
    /// a new #GFile
    #[doc(alias = "g_application_command_line_create_file_for_arg")]
    fn create_file_for_arg(&self, arg: impl AsRef<std::ffi::OsStr>) -> File {
        unsafe {
            from_glib_full(ffi::g_application_command_line_create_file_for_arg(
                self.as_ref().to_glib_none().0,
                arg.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Signals that command line processing is completed.
    ///
    /// For remote invocation, it causes the invoking process to terminate.
    ///
    /// For local invocation, it does nothing.
    ///
    /// This method should be called in the [`command-line`][struct@crate::Application#command-line]
    /// handler, after the exit status is set and all messages are printed.
    ///
    /// After this call, g_application_command_line_set_exit_status() has no effect.
    /// Subsequent calls to this method are no-ops.
    ///
    /// This method is automatically called when the #GApplicationCommandLine
    /// object is disposed — so you can omit the call in non-garbage collected
    /// languages.
    #[cfg(feature = "v2_80")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v2_80")))]
    #[doc(alias = "g_application_command_line_done")]
    fn done(&self) {
        unsafe {
            ffi::g_application_command_line_done(self.as_ref().to_glib_none().0);
        }
    }

    /// Gets the list of arguments that was passed on the command line.
    ///
    /// The strings in the array may contain non-UTF-8 data on UNIX (such as
    /// filenames or arguments given in the system locale) but are always in
    /// UTF-8 on Windows.
    ///
    /// If you wish to use the return value with #GOptionContext, you must
    /// use g_option_context_parse_strv().
    ///
    /// The return value is [`None`]-terminated and should be freed using
    /// g_strfreev().
    ///
    /// # Returns
    ///
    ///
    ///      the string array containing the arguments (the argv)
    #[doc(alias = "g_application_command_line_get_arguments")]
    #[doc(alias = "get_arguments")]
    fn arguments(&self) -> Vec<std::ffi::OsString> {
        unsafe {
            let mut argc = std::mem::MaybeUninit::uninit();
            let ret = FromGlibContainer::from_glib_full_num(
                ffi::g_application_command_line_get_arguments(
                    self.as_ref().to_glib_none().0,
                    argc.as_mut_ptr(),
                ),
                argc.assume_init() as _,
            );
            ret
        }
    }

    /// Gets the working directory of the command line invocation.
    /// The string may contain non-utf8 data.
    ///
    /// It is possible that the remote application did not send a working
    /// directory, so this may be [`None`].
    ///
    /// The return value should not be modified or freed and is valid for as
    /// long as @self exists.
    ///
    /// # Returns
    ///
    /// the current directory, or [`None`]
    #[doc(alias = "g_application_command_line_get_cwd")]
    #[doc(alias = "get_cwd")]
    fn cwd(&self) -> Option<std::path::PathBuf> {
        unsafe {
            from_glib_none(ffi::g_application_command_line_get_cwd(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Gets the contents of the 'environ' variable of the command line
    /// invocation, as would be returned by g_get_environ(), ie as a
    /// [`None`]-terminated list of strings in the form 'NAME=VALUE'.
    /// The strings may contain non-utf8 data.
    ///
    /// The remote application usually does not send an environment.  Use
    /// [`ApplicationFlags::SEND_ENVIRONMENT`][crate::ApplicationFlags::SEND_ENVIRONMENT] to affect that.  Even with this flag
    /// set it is possible that the environment is still not available (due
    /// to invocation messages from other applications).
    ///
    /// The return value should not be modified or freed and is valid for as
    /// long as @self exists.
    ///
    /// See g_application_command_line_getenv() if you are only interested
    /// in the value of a single environment variable.
    ///
    /// # Returns
    ///
    ///
    ///     the environment strings, or [`None`] if they were not sent
    #[doc(alias = "g_application_command_line_get_environ")]
    #[doc(alias = "get_environ")]
    fn environ(&self) -> Vec<std::ffi::OsString> {
        unsafe {
            FromGlibPtrContainer::from_glib_none(ffi::g_application_command_line_get_environ(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Gets the exit status of @self.  See
    /// g_application_command_line_set_exit_status() for more information.
    ///
    /// # Returns
    ///
    /// the exit status
    #[doc(alias = "g_application_command_line_get_exit_status")]
    #[doc(alias = "get_exit_status")]
    fn exit_status(&self) -> i32 {
        unsafe { ffi::g_application_command_line_get_exit_status(self.as_ref().to_glib_none().0) }
    }

    /// Determines if @self represents a remote invocation.
    ///
    /// # Returns
    ///
    /// [`true`] if the invocation was remote
    #[doc(alias = "g_application_command_line_get_is_remote")]
    #[doc(alias = "get_is_remote")]
    #[doc(alias = "is-remote")]
    fn is_remote(&self) -> bool {
        unsafe {
            from_glib(ffi::g_application_command_line_get_is_remote(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Gets the options that were passed to g_application_command_line().
    ///
    /// If you did not override local_command_line() then these are the same
    /// options that were parsed according to the #GOptionEntrys added to the
    /// application with g_application_add_main_option_entries() and possibly
    /// modified from your GApplication::handle-local-options handler.
    ///
    /// If no options were sent then an empty dictionary is returned so that
    /// you don't need to check for [`None`].
    ///
    /// The data has been passed via an untrusted external process, so the types of
    /// all values must be checked before being used.
    ///
    /// # Returns
    ///
    /// a #GVariantDict with the options
    #[doc(alias = "g_application_command_line_get_options_dict")]
    #[doc(alias = "get_options_dict")]
    fn options_dict(&self) -> glib::VariantDict {
        unsafe {
            from_glib_none(ffi::g_application_command_line_get_options_dict(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Gets the platform data associated with the invocation of @self.
    ///
    /// This is a #GVariant dictionary containing information about the
    /// context in which the invocation occurred.  It typically contains
    /// information like the current working directory and the startup
    /// notification ID.
    ///
    /// It comes from an untrusted external process and hence the types of all
    /// values must be validated before being used.
    ///
    /// For local invocation, it will be [`None`].
    ///
    /// # Returns
    ///
    /// the platform data, or [`None`]
    #[doc(alias = "g_application_command_line_get_platform_data")]
    #[doc(alias = "get_platform_data")]
    fn platform_data(&self) -> Option<glib::Variant> {
        unsafe {
            from_glib_full(ffi::g_application_command_line_get_platform_data(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Gets the stdin of the invoking process.
    ///
    /// The #GInputStream can be used to read data passed to the standard
    /// input of the invoking process.
    /// This doesn't work on all platforms.  Presently, it is only available
    /// on UNIX when using a D-Bus daemon capable of passing file descriptors.
    /// If stdin is not available then [`None`] will be returned.  In the
    /// future, support may be expanded to other platforms.
    ///
    /// You must only call this function once per commandline invocation.
    ///
    /// # Returns
    ///
    /// a #GInputStream for stdin
    #[doc(alias = "g_application_command_line_get_stdin")]
    #[doc(alias = "get_stdin")]
    fn stdin(&self) -> Option<InputStream> {
        unsafe {
            from_glib_full(ffi::g_application_command_line_get_stdin(
                self.as_ref().to_glib_none().0,
            ))
        }
    }

    /// Gets the value of a particular environment variable of the command
    /// line invocation, as would be returned by g_getenv().  The strings may
    /// contain non-utf8 data.
    ///
    /// The remote application usually does not send an environment.  Use
    /// [`ApplicationFlags::SEND_ENVIRONMENT`][crate::ApplicationFlags::SEND_ENVIRONMENT] to affect that.  Even with this flag
    /// set it is possible that the environment is still not available (due
    /// to invocation messages from other applications).
    ///
    /// The return value should not be modified or freed and is valid for as
    /// long as @self exists.
    /// ## `name`
    /// the environment variable to get
    ///
    /// # Returns
    ///
    /// the value of the variable, or [`None`] if unset or unsent
    #[doc(alias = "g_application_command_line_getenv")]
    fn getenv(&self, name: impl AsRef<std::ffi::OsStr>) -> Option<glib::GString> {
        unsafe {
            from_glib_none(ffi::g_application_command_line_getenv(
                self.as_ref().to_glib_none().0,
                name.as_ref().to_glib_none().0,
            ))
        }
    }

    //#[doc(alias = "g_application_command_line_print")]
    //fn print(&self, format: &str, : /*Unknown conversion*//*Unimplemented*/Basic: VarArgs) {
    //    unsafe { TODO: call ffi:g_application_command_line_print() }
    //}

    /// Prints a message using the stdout print handler in the invoking process.
    ///
    /// Unlike g_application_command_line_print(), @message is not a `printf()`-style
    /// format string. Use this function if @message contains text you don't have
    /// control over, that could include `printf()` escape sequences.
    /// ## `message`
    /// the message
    #[cfg(feature = "v2_80")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v2_80")))]
    #[doc(alias = "g_application_command_line_print_literal")]
    fn print_literal(&self, message: &str) {
        unsafe {
            ffi::g_application_command_line_print_literal(
                self.as_ref().to_glib_none().0,
                message.to_glib_none().0,
            );
        }
    }

    //#[doc(alias = "g_application_command_line_printerr")]
    //fn printerr(&self, format: &str, : /*Unknown conversion*//*Unimplemented*/Basic: VarArgs) {
    //    unsafe { TODO: call ffi:g_application_command_line_printerr() }
    //}

    /// Prints a message using the stderr print handler in the invoking process.
    ///
    /// Unlike g_application_command_line_printerr(), @message is not
    /// a `printf()`-style format string. Use this function if @message contains text
    /// you don't have control over, that could include `printf()` escape sequences.
    /// ## `message`
    /// the message
    #[cfg(feature = "v2_80")]
    #[cfg_attr(docsrs, doc(cfg(feature = "v2_80")))]
    #[doc(alias = "g_application_command_line_printerr_literal")]
    fn printerr_literal(&self, message: &str) {
        unsafe {
            ffi::g_application_command_line_printerr_literal(
                self.as_ref().to_glib_none().0,
                message.to_glib_none().0,
            );
        }
    }

    /// Sets the exit status that will be used when the invoking process
    /// exits.
    ///
    /// The return value of the #GApplication::command-line signal is
    /// passed to this function when the handler returns.  This is the usual
    /// way of setting the exit status.
    ///
    /// In the event that you want the remote invocation to continue running
    /// and want to decide on the exit status in the future, you can use this
    /// call.  For the case of a remote invocation, the remote process will
    /// typically exit when the last reference is dropped on @self.  The
    /// exit status of the remote process will be equal to the last value
    /// that was set with this function.
    ///
    /// In the case that the commandline invocation is local, the situation
    /// is slightly more complicated.  If the commandline invocation results
    /// in the mainloop running (ie: because the use-count of the application
    /// increased to a non-zero value) then the application is considered to
    /// have been 'successful' in a certain sense, and the exit status is
    /// always zero.  If the application use count is zero, though, the exit
    /// status of the local #GApplicationCommandLine is used.
    ///
    /// This method is a no-op if g_application_command_line_done() has
    /// been called.
    /// ## `exit_status`
    /// the exit status
    #[doc(alias = "g_application_command_line_set_exit_status")]
    fn set_exit_status(&self, exit_status: i32) {
        unsafe {
            ffi::g_application_command_line_set_exit_status(
                self.as_ref().to_glib_none().0,
                exit_status,
            );
        }
    }

    #[doc(alias = "is-remote")]
    fn connect_is_remote_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
        unsafe extern "C" fn notify_is_remote_trampoline<
            P: IsA<ApplicationCommandLine>,
            F: Fn(&P) + 'static,
        >(
            this: *mut ffi::GApplicationCommandLine,
            _param_spec: glib::ffi::gpointer,
            f: glib::ffi::gpointer,
        ) {
            let f: &F = &*(f as *const F);
            f(ApplicationCommandLine::from_glib_borrow(this).unsafe_cast_ref())
        }
        unsafe {
            let f: Box_<F> = Box_::new(f);
            connect_raw(
                self.as_ptr() as *mut _,
                b"notify::is-remote\0".as_ptr() as *const _,
                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
                    notify_is_remote_trampoline::<Self, F> as *const (),
                )),
                Box_::into_raw(f),
            )
        }
    }
}

impl<O: IsA<ApplicationCommandLine>> ApplicationCommandLineExt for O {}