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`]
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
231mod sealed {
232    pub trait Sealed {}
233    impl<T: super::IsA<super::ApplicationCommandLine>> Sealed for T {}
234}
235
236/// Trait containing all [`struct@ApplicationCommandLine`] methods.
237///
238/// # Implementors
239///
240/// [`ApplicationCommandLine`][struct@crate::ApplicationCommandLine]
241pub trait ApplicationCommandLineExt:
242    IsA<ApplicationCommandLine> + sealed::Sealed + 'static
243{
244    /// Creates a #GFile corresponding to a filename that was given as part
245    /// of the invocation of @self.
246    ///
247    /// This differs from g_file_new_for_commandline_arg() in that it
248    /// resolves relative pathnames using the current working directory of
249    /// the invoking process rather than the local process.
250    /// ## `arg`
251    /// an argument from @self
252    ///
253    /// # Returns
254    ///
255    /// a new #GFile
256    #[doc(alias = "g_application_command_line_create_file_for_arg")]
257    fn create_file_for_arg(&self, arg: impl AsRef<std::ffi::OsStr>) -> File {
258        unsafe {
259            from_glib_full(ffi::g_application_command_line_create_file_for_arg(
260                self.as_ref().to_glib_none().0,
261                arg.as_ref().to_glib_none().0,
262            ))
263        }
264    }
265
266    /// Signals that command line processing is completed.
267    ///
268    /// For remote invocation, it causes the invoking process to terminate.
269    ///
270    /// For local invocation, it does nothing.
271    ///
272    /// This method should be called in the [`command-line`][struct@crate::Application#command-line]
273    /// handler, after the exit status is set and all messages are printed.
274    ///
275    /// After this call, g_application_command_line_set_exit_status() has no effect.
276    /// Subsequent calls to this method are no-ops.
277    ///
278    /// This method is automatically called when the #GApplicationCommandLine
279    /// object is disposed — so you can omit the call in non-garbage collected
280    /// languages.
281    #[cfg(feature = "v2_80")]
282    #[cfg_attr(docsrs, doc(cfg(feature = "v2_80")))]
283    #[doc(alias = "g_application_command_line_done")]
284    fn done(&self) {
285        unsafe {
286            ffi::g_application_command_line_done(self.as_ref().to_glib_none().0);
287        }
288    }
289
290    /// Gets the list of arguments that was passed on the command line.
291    ///
292    /// The strings in the array may contain non-UTF-8 data on UNIX (such as
293    /// filenames or arguments given in the system locale) but are always in
294    /// UTF-8 on Windows.
295    ///
296    /// If you wish to use the return value with #GOptionContext, you must
297    /// use g_option_context_parse_strv().
298    ///
299    /// The return value is [`None`]-terminated and should be freed using
300    /// g_strfreev().
301    ///
302    /// # Returns
303    ///
304    ///
305    ///      the string array containing the arguments (the argv)
306    #[doc(alias = "g_application_command_line_get_arguments")]
307    #[doc(alias = "get_arguments")]
308    fn arguments(&self) -> Vec<std::ffi::OsString> {
309        unsafe {
310            let mut argc = std::mem::MaybeUninit::uninit();
311            let ret = FromGlibContainer::from_glib_full_num(
312                ffi::g_application_command_line_get_arguments(
313                    self.as_ref().to_glib_none().0,
314                    argc.as_mut_ptr(),
315                ),
316                argc.assume_init() as _,
317            );
318            ret
319        }
320    }
321
322    /// Gets the working directory of the command line invocation.
323    /// The string may contain non-utf8 data.
324    ///
325    /// It is possible that the remote application did not send a working
326    /// directory, so this may be [`None`].
327    ///
328    /// The return value should not be modified or freed and is valid for as
329    /// long as @self exists.
330    ///
331    /// # Returns
332    ///
333    /// the current directory, or [`None`]
334    #[doc(alias = "g_application_command_line_get_cwd")]
335    #[doc(alias = "get_cwd")]
336    fn cwd(&self) -> Option<std::path::PathBuf> {
337        unsafe {
338            from_glib_none(ffi::g_application_command_line_get_cwd(
339                self.as_ref().to_glib_none().0,
340            ))
341        }
342    }
343
344    /// Gets the contents of the 'environ' variable of the command line
345    /// invocation, as would be returned by g_get_environ(), ie as a
346    /// [`None`]-terminated list of strings in the form 'NAME=VALUE'.
347    /// The strings may contain non-utf8 data.
348    ///
349    /// The remote application usually does not send an environment.  Use
350    /// [`ApplicationFlags::SEND_ENVIRONMENT`][crate::ApplicationFlags::SEND_ENVIRONMENT] to affect that.  Even with this flag
351    /// set it is possible that the environment is still not available (due
352    /// to invocation messages from other applications).
353    ///
354    /// The return value should not be modified or freed and is valid for as
355    /// long as @self exists.
356    ///
357    /// See g_application_command_line_getenv() if you are only interested
358    /// in the value of a single environment variable.
359    ///
360    /// # Returns
361    ///
362    ///
363    ///     the environment strings, or [`None`] if they were not sent
364    #[doc(alias = "g_application_command_line_get_environ")]
365    #[doc(alias = "get_environ")]
366    fn environ(&self) -> Vec<std::ffi::OsString> {
367        unsafe {
368            FromGlibPtrContainer::from_glib_none(ffi::g_application_command_line_get_environ(
369                self.as_ref().to_glib_none().0,
370            ))
371        }
372    }
373
374    /// Gets the exit status of @self.  See
375    /// g_application_command_line_set_exit_status() for more information.
376    ///
377    /// # Returns
378    ///
379    /// the exit status
380    #[doc(alias = "g_application_command_line_get_exit_status")]
381    #[doc(alias = "get_exit_status")]
382    fn exit_status(&self) -> i32 {
383        unsafe { ffi::g_application_command_line_get_exit_status(self.as_ref().to_glib_none().0) }
384    }
385
386    /// Determines if @self represents a remote invocation.
387    ///
388    /// # Returns
389    ///
390    /// [`true`] if the invocation was remote
391    #[doc(alias = "g_application_command_line_get_is_remote")]
392    #[doc(alias = "get_is_remote")]
393    #[doc(alias = "is-remote")]
394    fn is_remote(&self) -> bool {
395        unsafe {
396            from_glib(ffi::g_application_command_line_get_is_remote(
397                self.as_ref().to_glib_none().0,
398            ))
399        }
400    }
401
402    /// Gets the options that were passed to g_application_command_line().
403    ///
404    /// If you did not override local_command_line() then these are the same
405    /// options that were parsed according to the #GOptionEntrys added to the
406    /// application with g_application_add_main_option_entries() and possibly
407    /// modified from your GApplication::handle-local-options handler.
408    ///
409    /// If no options were sent then an empty dictionary is returned so that
410    /// you don't need to check for [`None`].
411    ///
412    /// The data has been passed via an untrusted external process, so the types of
413    /// all values must be checked before being used.
414    ///
415    /// # Returns
416    ///
417    /// a #GVariantDict with the options
418    #[doc(alias = "g_application_command_line_get_options_dict")]
419    #[doc(alias = "get_options_dict")]
420    fn options_dict(&self) -> glib::VariantDict {
421        unsafe {
422            from_glib_none(ffi::g_application_command_line_get_options_dict(
423                self.as_ref().to_glib_none().0,
424            ))
425        }
426    }
427
428    /// Gets the platform data associated with the invocation of @self.
429    ///
430    /// This is a #GVariant dictionary containing information about the
431    /// context in which the invocation occurred.  It typically contains
432    /// information like the current working directory and the startup
433    /// notification ID.
434    ///
435    /// It comes from an untrusted external process and hence the types of all
436    /// values must be validated before being used.
437    ///
438    /// For local invocation, it will be [`None`].
439    ///
440    /// # Returns
441    ///
442    /// the platform data, or [`None`]
443    #[doc(alias = "g_application_command_line_get_platform_data")]
444    #[doc(alias = "get_platform_data")]
445    fn platform_data(&self) -> Option<glib::Variant> {
446        unsafe {
447            from_glib_full(ffi::g_application_command_line_get_platform_data(
448                self.as_ref().to_glib_none().0,
449            ))
450        }
451    }
452
453    /// Gets the stdin of the invoking process.
454    ///
455    /// The #GInputStream can be used to read data passed to the standard
456    /// input of the invoking process.
457    /// This doesn't work on all platforms.  Presently, it is only available
458    /// on UNIX when using a D-Bus daemon capable of passing file descriptors.
459    /// If stdin is not available then [`None`] will be returned.  In the
460    /// future, support may be expanded to other platforms.
461    ///
462    /// You must only call this function once per commandline invocation.
463    ///
464    /// # Returns
465    ///
466    /// a #GInputStream for stdin
467    #[doc(alias = "g_application_command_line_get_stdin")]
468    #[doc(alias = "get_stdin")]
469    fn stdin(&self) -> Option<InputStream> {
470        unsafe {
471            from_glib_full(ffi::g_application_command_line_get_stdin(
472                self.as_ref().to_glib_none().0,
473            ))
474        }
475    }
476
477    /// Gets the value of a particular environment variable of the command
478    /// line invocation, as would be returned by g_getenv().  The strings may
479    /// contain non-utf8 data.
480    ///
481    /// The remote application usually does not send an environment.  Use
482    /// [`ApplicationFlags::SEND_ENVIRONMENT`][crate::ApplicationFlags::SEND_ENVIRONMENT] to affect that.  Even with this flag
483    /// set it is possible that the environment is still not available (due
484    /// to invocation messages from other applications).
485    ///
486    /// The return value should not be modified or freed and is valid for as
487    /// long as @self exists.
488    /// ## `name`
489    /// the environment variable to get
490    ///
491    /// # Returns
492    ///
493    /// the value of the variable, or [`None`] if unset or unsent
494    #[doc(alias = "g_application_command_line_getenv")]
495    fn getenv(&self, name: impl AsRef<std::ffi::OsStr>) -> Option<glib::GString> {
496        unsafe {
497            from_glib_none(ffi::g_application_command_line_getenv(
498                self.as_ref().to_glib_none().0,
499                name.as_ref().to_glib_none().0,
500            ))
501        }
502    }
503
504    //#[doc(alias = "g_application_command_line_print")]
505    //fn print(&self, format: &str, : /*Unknown conversion*//*Unimplemented*/Basic: VarArgs) {
506    //    unsafe { TODO: call ffi:g_application_command_line_print() }
507    //}
508
509    /// Prints a message using the stdout print handler in the invoking process.
510    ///
511    /// Unlike g_application_command_line_print(), @message is not a `printf()`-style
512    /// format string. Use this function if @message contains text you don't have
513    /// control over, that could include `printf()` escape sequences.
514    /// ## `message`
515    /// the message
516    #[cfg(feature = "v2_80")]
517    #[cfg_attr(docsrs, doc(cfg(feature = "v2_80")))]
518    #[doc(alias = "g_application_command_line_print_literal")]
519    fn print_literal(&self, message: &str) {
520        unsafe {
521            ffi::g_application_command_line_print_literal(
522                self.as_ref().to_glib_none().0,
523                message.to_glib_none().0,
524            );
525        }
526    }
527
528    //#[doc(alias = "g_application_command_line_printerr")]
529    //fn printerr(&self, format: &str, : /*Unknown conversion*//*Unimplemented*/Basic: VarArgs) {
530    //    unsafe { TODO: call ffi:g_application_command_line_printerr() }
531    //}
532
533    /// Prints a message using the stderr print handler in the invoking process.
534    ///
535    /// Unlike g_application_command_line_printerr(), @message is not
536    /// a `printf()`-style format string. Use this function if @message contains text
537    /// you don't have control over, that could include `printf()` escape sequences.
538    /// ## `message`
539    /// the message
540    #[cfg(feature = "v2_80")]
541    #[cfg_attr(docsrs, doc(cfg(feature = "v2_80")))]
542    #[doc(alias = "g_application_command_line_printerr_literal")]
543    fn printerr_literal(&self, message: &str) {
544        unsafe {
545            ffi::g_application_command_line_printerr_literal(
546                self.as_ref().to_glib_none().0,
547                message.to_glib_none().0,
548            );
549        }
550    }
551
552    /// Sets the exit status that will be used when the invoking process
553    /// exits.
554    ///
555    /// The return value of the #GApplication::command-line signal is
556    /// passed to this function when the handler returns.  This is the usual
557    /// way of setting the exit status.
558    ///
559    /// In the event that you want the remote invocation to continue running
560    /// and want to decide on the exit status in the future, you can use this
561    /// call.  For the case of a remote invocation, the remote process will
562    /// typically exit when the last reference is dropped on @self.  The
563    /// exit status of the remote process will be equal to the last value
564    /// that was set with this function.
565    ///
566    /// In the case that the commandline invocation is local, the situation
567    /// is slightly more complicated.  If the commandline invocation results
568    /// in the mainloop running (ie: because the use-count of the application
569    /// increased to a non-zero value) then the application is considered to
570    /// have been 'successful' in a certain sense, and the exit status is
571    /// always zero.  If the application use count is zero, though, the exit
572    /// status of the local #GApplicationCommandLine is used.
573    ///
574    /// This method is a no-op if g_application_command_line_done() has
575    /// been called.
576    /// ## `exit_status`
577    /// the exit status
578    #[doc(alias = "g_application_command_line_set_exit_status")]
579    fn set_exit_status(&self, exit_status: i32) {
580        unsafe {
581            ffi::g_application_command_line_set_exit_status(
582                self.as_ref().to_glib_none().0,
583                exit_status,
584            );
585        }
586    }
587
588    #[doc(alias = "is-remote")]
589    fn connect_is_remote_notify<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId {
590        unsafe extern "C" fn notify_is_remote_trampoline<
591            P: IsA<ApplicationCommandLine>,
592            F: Fn(&P) + 'static,
593        >(
594            this: *mut ffi::GApplicationCommandLine,
595            _param_spec: glib::ffi::gpointer,
596            f: glib::ffi::gpointer,
597        ) {
598            let f: &F = &*(f as *const F);
599            f(ApplicationCommandLine::from_glib_borrow(this).unsafe_cast_ref())
600        }
601        unsafe {
602            let f: Box_<F> = Box_::new(f);
603            connect_raw(
604                self.as_ptr() as *mut _,
605                b"notify::is-remote\0".as_ptr() as *const _,
606                Some(std::mem::transmute::<*const (), unsafe extern "C" fn()>(
607                    notify_is_remote_trampoline::<Self, F> as *const (),
608                )),
609                Box_::into_raw(f),
610            )
611        }
612    }
613}
614
615impl<O: IsA<ApplicationCommandLine>> ApplicationCommandLineExt for O {}