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 {}