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