gio/auto/
application_command_line.rs

1// This file was generated by gir (https://github.com/gtk-rs/gir)
2// from gir-files (https://github.com/gtk-rs/gir-files)
3// DO NOT EDIT
4
5use crate::{ffi, File, InputStream};
6use glib::{
7    prelude::*,
8    signal::{connect_raw, SignalHandlerId},
9    translate::*,
10};
11use std::boxed::Box as Box_;
12
13glib::wrapper! {
14    /// `GApplicationCommandLine` represents a command-line invocation of
15    /// an application.
16    ///
17    /// It is created by [`Application`][crate::Application] and emitted
18    /// in the [`command-line`][struct@crate::Application#command-line] signal and virtual function.
19    ///
20    /// The class contains the list of arguments that the program was invoked
21    /// with. It is also possible to query if the commandline invocation was
22    /// local (ie: the current process is running in direct response to the
23    /// invocation) or remote (ie: some other process forwarded the
24    /// commandline to this process).
25    ///
26    /// The `GApplicationCommandLine` object can provide the @argc and @argv
27    /// parameters for use with the `GLib::OptionContext` command-line parsing API,
28    /// with the [`ApplicationCommandLineExt::arguments()`][crate::prelude::ApplicationCommandLineExt::arguments()] function. See
29    /// [gapplication-example-cmdline3.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gapplication-example-cmdline3.c)
30    /// for an example.
31    ///
32    /// The exit status of the originally-invoked process may be set and
33    /// messages can be printed to stdout or stderr of that process.
34    ///
35    /// For remote invocation, the originally-invoked process exits when
36    /// [`ApplicationCommandLineExt::done()`][crate::prelude::ApplicationCommandLineExt::done()] method is called. This method is
37    /// also automatically called when the object is disposed.
38    ///
39    /// The main use for `GApplicationCommandLine` (and the
40    /// [`command-line`][struct@crate::Application#command-line] signal) is 'Emacs server' like use cases:
41    /// You can set the `EDITOR` environment variable to have e.g. git use
42    /// your favourite editor to edit commit messages, and if you already
43    /// have an instance of the editor running, the editing will happen
44    /// in the running instance, instead of opening a new one. An important
45    /// aspect of this use case is that the process that gets started by git
46    /// does not return until the editing is done.
47    ///
48    /// Normally, the commandline is completely handled in the
49    /// [`command-line`][struct@crate::Application#command-line] handler. The launching instance exits
50    /// once the signal handler in the primary instance has returned, and
51    /// the return value of the signal handler becomes the exit status
52    /// of the launching instance.
53    ///
54    /// **⚠️ The following code is in c ⚠️**
55    ///
56    /// ```c
57    /// static int
58    /// command_line (GApplication            *application,
59    ///               GApplicationCommandLine *cmdline)
60    /// {
61    ///   gchar **argv;
62    ///   gint argc;
63    ///   gint i;
64    ///
65    ///   argv = g_application_command_line_get_arguments (cmdline, &argc);
66    ///
67    ///   g_application_command_line_print (cmdline,
68    ///                                     "This text is written back\n"
69    ///                                     "to stdout of the caller\n");
70    ///
71    ///   for (i = 0; i < argc; i++)
72    ///     g_print ("argument %d: %s\n", i, argv[i]);
73    ///
74    ///   g_strfreev (argv);
75    ///
76    ///   return 0;
77    /// }
78    /// ```
79    ///
80    /// The complete example can be found here:
81    /// [gapplication-example-cmdline.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gapplication-example-cmdline.c)
82    ///
83    /// In more complicated cases, the handling of the commandline can be
84    /// split between the launcher and the primary instance.
85    ///
86    /// **⚠️ The following code is in c ⚠️**
87    ///
88    /// ```c
89    /// static gboolean
90    ///  test_local_cmdline (GApplication   *application,
91    ///                      gchar        ***arguments,
92    ///                      gint           *exit_status)
93    /// {
94    ///   gint i, j;
95    ///   gchar **argv;
96    ///
97    ///   argv = *arguments;
98    ///
99    ///   if (argv[0] == NULL)
100    ///     {
101    ///       *exit_status = 0;
102    ///       return FALSE;
103    ///     }
104    ///
105    ///   i = 1;
106    ///   while (argv[i])
107    ///     {
108    ///       if (g_str_has_prefix (argv[i], "--local-"))
109    ///         {
110    ///           g_print ("handling argument %s locally\n", argv[i]);
111    ///           g_free (argv[i]);
112    ///           for (j = i; argv[j]; j++)
113    ///             argv[j] = argv[j + 1];
114    ///         }
115    ///       else
116    ///         {
117    ///           g_print ("not handling argument %s locally\n", argv[i]);
118    ///           i++;
119    ///         }
120    ///     }
121    ///
122    ///   *exit_status = 0;
123    ///
124    ///   return FALSE;
125    /// }
126    ///
127    /// static void
128    /// test_application_class_init (TestApplicationClass *class)
129    /// {
130    ///   G_APPLICATION_CLASS (class)->local_command_line = test_local_cmdline;
131    ///
132    ///   ...
133    /// }
134    /// ```
135    ///
136    /// In this example of split commandline handling, options that start
137    /// with `--local-` are handled locally, all other options are passed
138    /// to the [`command-line`][struct@crate::Application#command-line] handler which runs in the primary
139    /// instance.
140    ///
141    /// The complete example can be found here:
142    /// [gapplication-example-cmdline2.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gapplication-example-cmdline2.c)
143    ///
144    /// If handling the commandline requires a lot of work, it may be better to defer it.
145    ///
146    /// **⚠️ The following code is in c ⚠️**
147    ///
148    /// ```c
149    /// static gboolean
150    /// my_cmdline_handler (gpointer data)
151    /// {
152    ///   GApplicationCommandLine *cmdline = data;
153    ///
154    ///   // do the heavy lifting in an idle
155    ///
156    ///   g_application_command_line_set_exit_status (cmdline, 0);
157    ///   g_object_unref (cmdline); // this releases the application
158    ///
159    ///   return G_SOURCE_REMOVE;
160    /// }
161    ///
162    /// static int
163    /// command_line (GApplication            *application,
164    ///               GApplicationCommandLine *cmdline)
165    /// {
166    ///   // keep the application running until we are done with this commandline
167    ///   g_application_hold (application);
168    ///
169    ///   g_object_set_data_full (G_OBJECT (cmdline),
170    ///                           "application", application,
171    ///                           (GDestroyNotify)g_application_release);
172    ///
173    ///   g_object_ref (cmdline);
174    ///   g_idle_add (my_cmdline_handler, cmdline);
175    ///
176    ///   return 0;
177    /// }
178    /// ```
179    ///
180    /// In this example the commandline is not completely handled before
181    /// the [`command-line`][struct@crate::Application#command-line] handler returns. Instead, we keep
182    /// a reference to the `GApplicationCommandLine` object and handle it
183    /// later (in this example, in an idle). Note that it is necessary to
184    /// hold the application until you are done with the commandline.
185    ///
186    /// The complete example can be found here:
187    /// [gapplication-example-cmdline3.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gapplication-example-cmdline3.c)
188    ///
189    /// ## Properties
190    ///
191    ///
192    /// #### `arguments`
193    ///  The commandline that caused this [`command-line`][struct@crate::Application#command-line]
194    /// signal emission.
195    ///
196    /// Writeable | Construct Only
197    ///
198    ///
199    /// #### `is-remote`
200    ///  Whether this is a remote commandline.
201    ///
202    /// Readable
203    ///
204    ///
205    /// #### `options`
206    ///  The options sent along with the commandline.
207    ///
208    /// Writeable | Construct Only
209    ///
210    ///
211    /// #### `platform-data`
212    ///  Platform-specific data for the commandline.
213    ///
214    /// Writeable | Construct Only
215    ///
216    /// # Implements
217    ///
218    /// [`ApplicationCommandLineExt`][trait@crate::prelude::ApplicationCommandLineExt], [`trait@glib::ObjectExt`], [`ApplicationCommandLineExtManual`][trait@crate::prelude::ApplicationCommandLineExtManual]
219    #[doc(alias = "GApplicationCommandLine")]
220    pub struct ApplicationCommandLine(Object<ffi::GApplicationCommandLine, ffi::GApplicationCommandLineClass>);
221
222    match fn {
223        type_ => || ffi::g_application_command_line_get_type(),
224    }
225}
226
227impl ApplicationCommandLine {
228    pub const NONE: Option<&'static ApplicationCommandLine> = None;
229}
230
231/// Trait containing all [`struct@ApplicationCommandLine`] methods.
232///
233/// # Implementors
234///
235/// [`ApplicationCommandLine`][struct@crate::ApplicationCommandLine]
236pub trait ApplicationCommandLineExt: IsA<ApplicationCommandLine> + 'static {
237    /// Creates a #GFile corresponding to a filename that was given as part
238    /// of the invocation of @self.
239    ///
240    /// This differs from g_file_new_for_commandline_arg() in that it
241    /// resolves relative pathnames using the current working directory of
242    /// the invoking process rather than the local process.
243    /// ## `arg`
244    /// an argument from @self
245    ///
246    /// # Returns
247    ///
248    /// a new #GFile
249    #[doc(alias = "g_application_command_line_create_file_for_arg")]
250    fn create_file_for_arg(&self, arg: impl AsRef<std::ffi::OsStr>) -> File {
251        unsafe {
252            from_glib_full(ffi::g_application_command_line_create_file_for_arg(
253                self.as_ref().to_glib_none().0,
254                arg.as_ref().to_glib_none().0,
255            ))
256        }
257    }
258
259    /// Signals that command line processing is completed.
260    ///
261    /// For remote invocation, it causes the invoking process to terminate.
262    ///
263    /// For local invocation, it does nothing.
264    ///
265    /// This method should be called in the [`command-line`][struct@crate::Application#command-line]
266    /// handler, after the exit status is set and all messages are printed.
267    ///
268    /// After this call, g_application_command_line_set_exit_status() has no effect.
269    /// Subsequent calls to this method are no-ops.
270    ///
271    /// This method is automatically called when the #GApplicationCommandLine
272    /// object is disposed — so you can omit the call in non-garbage collected
273    /// languages.
274    #[cfg(feature = "v2_80")]
275    #[cfg_attr(docsrs, doc(cfg(feature = "v2_80")))]
276    #[doc(alias = "g_application_command_line_done")]
277    fn done(&self) {
278        unsafe {
279            ffi::g_application_command_line_done(self.as_ref().to_glib_none().0);
280        }
281    }
282
283    /// Gets the list of arguments that was passed on the command line.
284    ///
285    /// The strings in the array may contain non-UTF-8 data on UNIX (such as
286    /// filenames or arguments given in the system locale) but are always in
287    /// UTF-8 on Windows.
288    ///
289    /// If you wish to use the return value with #GOptionContext, you must
290    /// use g_option_context_parse_strv().
291    ///
292    /// The return value is [`None`]-terminated and should be freed using
293    /// g_strfreev().
294    ///
295    /// # Returns
296    ///
297    ///
298    ///      the string array containing the arguments (the argv)
299    #[doc(alias = "g_application_command_line_get_arguments")]
300    #[doc(alias = "get_arguments")]
301    fn arguments(&self) -> Vec<std::ffi::OsString> {
302        unsafe {
303            let mut argc = std::mem::MaybeUninit::uninit();
304            let ret = FromGlibContainer::from_glib_full_num(
305                ffi::g_application_command_line_get_arguments(
306                    self.as_ref().to_glib_none().0,
307                    argc.as_mut_ptr(),
308                ),
309                argc.assume_init() as _,
310            );
311            ret
312        }
313    }
314
315    /// Gets the working directory of the command line invocation.
316    /// The string may contain non-utf8 data.
317    ///
318    /// It is possible that the remote application did not send a working
319    /// directory, so this may be [`None`].
320    ///
321    /// The return value should not be modified or freed and is valid for as
322    /// long as @self exists.
323    ///
324    /// # Returns
325    ///
326    /// the current directory, or [`None`]
327    #[doc(alias = "g_application_command_line_get_cwd")]
328    #[doc(alias = "get_cwd")]
329    fn cwd(&self) -> Option<std::path::PathBuf> {
330        unsafe {
331            from_glib_none(ffi::g_application_command_line_get_cwd(
332                self.as_ref().to_glib_none().0,
333            ))
334        }
335    }
336
337    /// Gets the contents of the 'environ' variable of the command line
338    /// invocation, as would be returned by g_get_environ(), ie as a
339    /// [`None`]-terminated list of strings in the form 'NAME=VALUE'.
340    /// The strings may contain non-utf8 data.
341    ///
342    /// The remote application usually does not send an environment.  Use
343    /// [`ApplicationFlags::SEND_ENVIRONMENT`][crate::ApplicationFlags::SEND_ENVIRONMENT] to affect that.  Even with this flag
344    /// set it is possible that the environment is still not available (due
345    /// to invocation messages from other applications).
346    ///
347    /// The return value should not be modified or freed and is valid for as
348    /// long as @self exists.
349    ///
350    /// See g_application_command_line_getenv() if you are only interested
351    /// in the value of a single environment variable.
352    ///
353    /// # Returns
354    ///
355    ///
356    ///     the environment strings, or [`None`] if they were not sent
357    #[doc(alias = "g_application_command_line_get_environ")]
358    #[doc(alias = "get_environ")]
359    fn environ(&self) -> Vec<std::ffi::OsString> {
360        unsafe {
361            FromGlibPtrContainer::from_glib_none(ffi::g_application_command_line_get_environ(
362                self.as_ref().to_glib_none().0,
363            ))
364        }
365    }
366
367    /// Determines if @self represents a remote invocation.
368    ///
369    /// # Returns
370    ///
371    /// [`true`] if the invocation was remote
372    #[doc(alias = "g_application_command_line_get_is_remote")]
373    #[doc(alias = "get_is_remote")]
374    #[doc(alias = "is-remote")]
375    fn is_remote(&self) -> bool {
376        unsafe {
377            from_glib(ffi::g_application_command_line_get_is_remote(
378                self.as_ref().to_glib_none().0,
379            ))
380        }
381    }
382
383    /// Gets the options that were passed to g_application_command_line().
384    ///
385    /// If you did not override local_command_line() then these are the same
386    /// options that were parsed according to the #GOptionEntrys added to the
387    /// application with g_application_add_main_option_entries() and possibly
388    /// modified from your GApplication::handle-local-options handler.
389    ///
390    /// If no options were sent then an empty dictionary is returned so that
391    /// you don't need to check for [`None`].
392    ///
393    /// The data has been passed via an untrusted external process, so the types of
394    /// all values must be checked before being used.
395    ///
396    /// # Returns
397    ///
398    /// a #GVariantDict with the options
399    #[doc(alias = "g_application_command_line_get_options_dict")]
400    #[doc(alias = "get_options_dict")]
401    fn options_dict(&self) -> glib::VariantDict {
402        unsafe {
403            from_glib_none(ffi::g_application_command_line_get_options_dict(
404                self.as_ref().to_glib_none().0,
405            ))
406        }
407    }
408
409    /// Gets the platform data associated with the invocation of @self.
410    ///
411    /// This is a #GVariant dictionary containing information about the
412    /// context in which the invocation occurred.  It typically contains
413    /// information like the current working directory and the startup
414    /// notification ID.
415    ///
416    /// It comes from an untrusted external process and hence the types of all
417    /// values must be validated before being used.
418    ///
419    /// For local invocation, it will be [`None`].
420    ///
421    /// # Returns
422    ///
423    /// the platform data, or [`None`]
424    #[doc(alias = "g_application_command_line_get_platform_data")]
425    #[doc(alias = "get_platform_data")]
426    fn platform_data(&self) -> Option<glib::Variant> {
427        unsafe {
428            from_glib_full(ffi::g_application_command_line_get_platform_data(
429                self.as_ref().to_glib_none().0,
430            ))
431        }
432    }
433
434    /// Gets the stdin of the invoking process.
435    ///
436    /// The #GInputStream can be used to read data passed to the standard
437    /// input of the invoking process.
438    /// This doesn't work on all platforms.  Presently, it is only available
439    /// on UNIX when using a D-Bus daemon capable of passing file descriptors.
440    /// If stdin is not available then [`None`] will be returned.  In the
441    /// future, support may be expanded to other platforms.
442    ///
443    /// You must only call this function once per commandline invocation.
444    ///
445    /// # Returns
446    ///
447    /// a #GInputStream for stdin
448    #[doc(alias = "g_application_command_line_get_stdin")]
449    #[doc(alias = "get_stdin")]
450    fn stdin(&self) -> Option<InputStream> {
451        unsafe {
452            from_glib_full(ffi::g_application_command_line_get_stdin(
453                self.as_ref().to_glib_none().0,
454            ))
455        }
456    }
457
458    /// Gets the value of a particular environment variable of the command
459    /// line invocation, as would be returned by g_getenv().  The strings may
460    /// contain non-utf8 data.
461    ///
462    /// The remote application usually does not send an environment.  Use
463    /// [`ApplicationFlags::SEND_ENVIRONMENT`][crate::ApplicationFlags::SEND_ENVIRONMENT] to affect that.  Even with this flag
464    /// set it is possible that the environment is still not available (due
465    /// to invocation messages from other applications).
466    ///
467    /// The return value should not be modified or freed and is valid for as
468    /// long as @self exists.
469    /// ## `name`
470    /// the environment variable to get
471    ///
472    /// # Returns
473    ///
474    /// the value of the variable, or [`None`] if unset or unsent
475    #[doc(alias = "g_application_command_line_getenv")]
476    fn getenv(&self, name: impl AsRef<std::ffi::OsStr>) -> Option<glib::GString> {
477        unsafe {
478            from_glib_none(ffi::g_application_command_line_getenv(
479                self.as_ref().to_glib_none().0,
480                name.as_ref().to_glib_none().0,
481            ))
482        }
483    }
484
485    //#[doc(alias = "g_application_command_line_print")]
486    //fn print(&self, format: &str, : /*Unknown conversion*//*Unimplemented*/Basic: VarArgs) {
487    //    unsafe { TODO: call ffi:g_application_command_line_print() }
488    //}
489
490    /// Prints a message using the stdout print handler in the invoking process.
491    ///
492    /// Unlike g_application_command_line_print(), @message is not a `printf()`-style
493    /// format string. Use this function if @message contains text you don't have
494    /// control over, that could include `printf()` escape sequences.
495    /// ## `message`
496    /// the message
497    #[cfg(feature = "v2_80")]
498    #[cfg_attr(docsrs, doc(cfg(feature = "v2_80")))]
499    #[doc(alias = "g_application_command_line_print_literal")]
500    fn print_literal(&self, message: &str) {
501        unsafe {
502            ffi::g_application_command_line_print_literal(
503                self.as_ref().to_glib_none().0,
504                message.to_glib_none().0,
505            );
506        }
507    }
508
509    //#[doc(alias = "g_application_command_line_printerr")]
510    //fn printerr(&self, format: &str, : /*Unknown conversion*//*Unimplemented*/Basic: VarArgs) {
511    //    unsafe { TODO: call ffi:g_application_command_line_printerr() }
512    //}
513
514    /// Prints a message using the stderr print handler in the invoking process.
515    ///
516    /// Unlike g_application_command_line_printerr(), @message is not
517    /// a `printf()`-style format string. Use this function if @message contains text
518    /// you don't have control over, that could include `printf()` escape sequences.
519    /// ## `message`
520    /// the message
521    #[cfg(feature = "v2_80")]
522    #[cfg_attr(docsrs, doc(cfg(feature = "v2_80")))]
523    #[doc(alias = "g_application_command_line_printerr_literal")]
524    fn printerr_literal(&self, message: &str) {
525        unsafe {
526            ffi::g_application_command_line_printerr_literal(
527                self.as_ref().to_glib_none().0,
528                message.to_glib_none().0,
529            );
530        }
531    }
532
533    #[doc(alias = "is-remote")]
534    fn connect_is_remote_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
535        unsafe extern "C" fn notify_is_remote_trampoline<
536            P: IsA<ApplicationCommandLine>,
537            F: Fn(&P) + 'static,
538        >(
539            this: *mut ffi::GApplicationCommandLine,
540            _param_spec: glib::ffi::gpointer,
541            f: glib::ffi::gpointer,
542        ) {
543            let f: &F = &*(f as *const F);
544            f(ApplicationCommandLine::from_glib_borrow(this).unsafe_cast_ref())
545        }
546        unsafe {
547            let f: Box_<F> = Box_::new(f);
548            connect_raw(
549                self.as_ptr() as *mut _,
550                c"notify::is-remote".as_ptr() as *const _,
551                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
552                    notify_is_remote_trampoline::<Self, F> as *const (),
553                )),
554                Box_::into_raw(f),
555            )
556        }
557    }
558}
559
560impl<O: IsA<ApplicationCommandLine>> ApplicationCommandLineExt for O {}