1 /*
2  * This file is part of gtkD.
3  *
4  * gtkD is free software; you can redistribute it and/or modify
5  * it under the terms of the GNU Lesser General Public License
6  * as published by the Free Software Foundation; either version 3
7  * of the License, or (at your option) any later version, with
8  * some exceptions, please read the COPYING file.
9  *
10  * gtkD is distributed in the hope that it will be useful,
11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
13  * GNU Lesser General Public License for more details.
14  *
15  * You should have received a copy of the GNU Lesser General Public License
16  * along with gtkD; if not, write to the Free Software
17  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110, USA
18  */
19 
20 // generated automatically - do not change
21 // find conversion definition on APILookup.txt
22 // implement new conversion functionalities on the wrap.utils pakage
23 
24 
25 module gio.AppInfoIF;
26 
27 private import gio.AppInfoIF;
28 private import gio.AppLaunchContext;
29 private import gio.AsyncResultIF;
30 private import gio.Cancellable;
31 private import gio.FileIF;
32 private import gio.IconIF;
33 private import gio.c.functions;
34 public  import gio.c.types;
35 private import glib.ErrorG;
36 private import glib.GException;
37 private import glib.ListG;
38 private import glib.Str;
39 private import gobject.ObjectG;
40 public  import gtkc.giotypes;
41 
42 
43 /**
44  * #GAppInfo and #GAppLaunchContext are used for describing and launching
45  * applications installed on the system.
46  * 
47  * As of GLib 2.20, URIs will always be converted to POSIX paths
48  * (using g_file_get_path()) when using g_app_info_launch() even if
49  * the application requested an URI and not a POSIX path. For example
50  * for an desktop-file based application with Exec key `totem
51  * %U` and a single URI, `sftp://foo/file.avi`, then
52  * `/home/user/.gvfs/sftp on foo/file.avi` will be passed. This will
53  * only work if a set of suitable GIO extensions (such as gvfs 2.26
54  * compiled with FUSE support), is available and operational; if this
55  * is not the case, the URI will be passed unmodified to the application.
56  * Some URIs, such as `mailto:`, of course cannot be mapped to a POSIX
57  * path (in gvfs there's no FUSE mount for it); such URIs will be
58  * passed unmodified to the application.
59  * 
60  * Specifically for gvfs 2.26 and later, the POSIX URI will be mapped
61  * back to the GIO URI in the #GFile constructors (since gvfs
62  * implements the #GVfs extension point). As such, if the application
63  * needs to examine the URI, it needs to use g_file_get_uri() or
64  * similar on #GFile. In other words, an application cannot assume
65  * that the URI passed to e.g. g_file_new_for_commandline_arg() is
66  * equal to the result of g_file_get_uri(). The following snippet
67  * illustrates this:
68  * 
69  * |[
70  * GFile *f;
71  * char *uri;
72  * 
73  * file = g_file_new_for_commandline_arg (uri_from_commandline);
74  * 
75  * uri = g_file_get_uri (file);
76  * strcmp (uri, uri_from_commandline) == 0;
77  * g_free (uri);
78  * 
79  * if (g_file_has_uri_scheme (file, "cdda"))
80  * {
81  * // do something special with uri
82  * }
83  * g_object_unref (file);
84  * ]|
85  * 
86  * This code will work when both `cdda://sr0/Track 1.wav` and
87  * `/home/user/.gvfs/cdda on sr0/Track 1.wav` is passed to the
88  * application. It should be noted that it's generally not safe
89  * for applications to rely on the format of a particular URIs.
90  * Different launcher applications (e.g. file managers) may have
91  * different ideas of what a given URI means.
92  */
93 public interface AppInfoIF{
94 	/** Get the main Gtk struct */
95 	public GAppInfo* getAppInfoStruct(bool transferOwnership = false);
96 
97 	/** the main Gtk struct as a void* */
98 	protected void* getStruct();
99 
100 
101 	/** */
102 	public static GType getType()
103 	{
104 		return g_app_info_get_type();
105 	}
106 
107 	/**
108 	 * Creates a new #GAppInfo from the given information.
109 	 *
110 	 * Note that for @commandline, the quoting rules of the Exec key of the
111 	 * [freedesktop.org Desktop Entry Specification](http://freedesktop.org/Standards/desktop-entry-spec)
112 	 * are applied. For example, if the @commandline contains
113 	 * percent-encoded URIs, the percent-character must be doubled in order to prevent it from
114 	 * being swallowed by Exec key unquoting. See the specification for exact quoting rules.
115 	 *
116 	 * Params:
117 	 *     commandline = the commandline to use
118 	 *     applicationName = the application name, or %NULL to use @commandline
119 	 *     flags = flags that can specify details of the created #GAppInfo
120 	 *
121 	 * Returns: new #GAppInfo for given command.
122 	 *
123 	 * Throws: GException on failure.
124 	 */
125 	public static AppInfoIF createFromCommandline(string commandline, string applicationName, GAppInfoCreateFlags flags)
126 	{
127 		GError* err = null;
128 
129 		auto p = g_app_info_create_from_commandline(Str.toStringz(commandline), Str.toStringz(applicationName), flags, &err);
130 
131 		if (err !is null)
132 		{
133 			throw new GException( new ErrorG(err) );
134 		}
135 
136 		if(p is null)
137 		{
138 			return null;
139 		}
140 
141 		return ObjectG.getDObject!(AppInfoIF)(cast(GAppInfo*) p, true);
142 	}
143 
144 	/**
145 	 * Gets a list of all of the applications currently registered
146 	 * on this system.
147 	 *
148 	 * For desktop files, this includes applications that have
149 	 * `NoDisplay=true` set or are excluded from display by means
150 	 * of `OnlyShowIn` or `NotShowIn`. See g_app_info_should_show().
151 	 * The returned list does not include applications which have
152 	 * the `Hidden` key set.
153 	 *
154 	 * Returns: a newly allocated #GList of references to #GAppInfos.
155 	 */
156 	public static ListG getAll()
157 	{
158 		auto p = g_app_info_get_all();
159 
160 		if(p is null)
161 		{
162 			return null;
163 		}
164 
165 		return new ListG(cast(GList*) p, true);
166 	}
167 
168 	/**
169 	 * Gets a list of all #GAppInfos for a given content type,
170 	 * including the recommended and fallback #GAppInfos. See
171 	 * g_app_info_get_recommended_for_type() and
172 	 * g_app_info_get_fallback_for_type().
173 	 *
174 	 * Params:
175 	 *     contentType = the content type to find a #GAppInfo for
176 	 *
177 	 * Returns: #GList of #GAppInfos
178 	 *     for given @content_type or %NULL on error.
179 	 */
180 	public static ListG getAllForType(string contentType)
181 	{
182 		auto p = g_app_info_get_all_for_type(Str.toStringz(contentType));
183 
184 		if(p is null)
185 		{
186 			return null;
187 		}
188 
189 		return new ListG(cast(GList*) p, true);
190 	}
191 
192 	/**
193 	 * Gets the default #GAppInfo for a given content type.
194 	 *
195 	 * Params:
196 	 *     contentType = the content type to find a #GAppInfo for
197 	 *     mustSupportUris = if %TRUE, the #GAppInfo is expected to
198 	 *         support URIs
199 	 *
200 	 * Returns: #GAppInfo for given @content_type or
201 	 *     %NULL on error.
202 	 */
203 	public static AppInfoIF getDefaultForType(string contentType, bool mustSupportUris)
204 	{
205 		auto p = g_app_info_get_default_for_type(Str.toStringz(contentType), mustSupportUris);
206 
207 		if(p is null)
208 		{
209 			return null;
210 		}
211 
212 		return ObjectG.getDObject!(AppInfoIF)(cast(GAppInfo*) p, true);
213 	}
214 
215 	/**
216 	 * Gets the default application for handling URIs with
217 	 * the given URI scheme. A URI scheme is the initial part
218 	 * of the URI, up to but not including the ':', e.g. "http",
219 	 * "ftp" or "sip".
220 	 *
221 	 * Params:
222 	 *     uriScheme = a string containing a URI scheme.
223 	 *
224 	 * Returns: #GAppInfo for given @uri_scheme or %NULL on error.
225 	 */
226 	public static AppInfoIF getDefaultForUriScheme(string uriScheme)
227 	{
228 		auto p = g_app_info_get_default_for_uri_scheme(Str.toStringz(uriScheme));
229 
230 		if(p is null)
231 		{
232 			return null;
233 		}
234 
235 		return ObjectG.getDObject!(AppInfoIF)(cast(GAppInfo*) p, true);
236 	}
237 
238 	/**
239 	 * Gets a list of fallback #GAppInfos for a given content type, i.e.
240 	 * those applications which claim to support the given content type
241 	 * by MIME type subclassing and not directly.
242 	 *
243 	 * Params:
244 	 *     contentType = the content type to find a #GAppInfo for
245 	 *
246 	 * Returns: #GList of #GAppInfos
247 	 *     for given @content_type or %NULL on error.
248 	 *
249 	 * Since: 2.28
250 	 */
251 	public static ListG getFallbackForType(string contentType)
252 	{
253 		auto p = g_app_info_get_fallback_for_type(Str.toStringz(contentType));
254 
255 		if(p is null)
256 		{
257 			return null;
258 		}
259 
260 		return new ListG(cast(GList*) p, true);
261 	}
262 
263 	/**
264 	 * Gets a list of recommended #GAppInfos for a given content type, i.e.
265 	 * those applications which claim to support the given content type exactly,
266 	 * and not by MIME type subclassing.
267 	 * Note that the first application of the list is the last used one, i.e.
268 	 * the last one for which g_app_info_set_as_last_used_for_type() has been
269 	 * called.
270 	 *
271 	 * Params:
272 	 *     contentType = the content type to find a #GAppInfo for
273 	 *
274 	 * Returns: #GList of #GAppInfos
275 	 *     for given @content_type or %NULL on error.
276 	 *
277 	 * Since: 2.28
278 	 */
279 	public static ListG getRecommendedForType(string contentType)
280 	{
281 		auto p = g_app_info_get_recommended_for_type(Str.toStringz(contentType));
282 
283 		if(p is null)
284 		{
285 			return null;
286 		}
287 
288 		return new ListG(cast(GList*) p, true);
289 	}
290 
291 	/**
292 	 * Utility function that launches the default application
293 	 * registered to handle the specified uri. Synchronous I/O
294 	 * is done on the uri to detect the type of the file if
295 	 * required.
296 	 *
297 	 * Params:
298 	 *     uri = the uri to show
299 	 *     context = an optional #GAppLaunchContext
300 	 *
301 	 * Returns: %TRUE on success, %FALSE on error.
302 	 *
303 	 * Throws: GException on failure.
304 	 */
305 	public static bool launchDefaultForUri(string uri, AppLaunchContext context)
306 	{
307 		GError* err = null;
308 
309 		auto p = g_app_info_launch_default_for_uri(Str.toStringz(uri), (context is null) ? null : context.getAppLaunchContextStruct(), &err) != 0;
310 
311 		if (err !is null)
312 		{
313 			throw new GException( new ErrorG(err) );
314 		}
315 
316 		return p;
317 	}
318 
319 	/**
320 	 * Async version of g_app_info_launch_default_for_uri().
321 	 *
322 	 * This version is useful if you are interested in receiving
323 	 * error information in the case where the application is
324 	 * sandboxed and the portal may present an application chooser
325 	 * dialog to the user.
326 	 *
327 	 * Params:
328 	 *     uri = the uri to show
329 	 *     context = an optional #GAppLaunchContext
330 	 *     cancellable = a #GCancellable
331 	 *     callback = a #GASyncReadyCallback to call when the request is done
332 	 *     userData = data to pass to @callback
333 	 *
334 	 * Since: 2.50
335 	 */
336 	public static void launchDefaultForUriAsync(string uri, AppLaunchContext context, Cancellable cancellable, GAsyncReadyCallback callback, void* userData)
337 	{
338 		g_app_info_launch_default_for_uri_async(Str.toStringz(uri), (context is null) ? null : context.getAppLaunchContextStruct(), (cancellable is null) ? null : cancellable.getCancellableStruct(), callback, userData);
339 	}
340 
341 	/**
342 	 * Finishes an asynchronous launch-default-for-uri operation.
343 	 *
344 	 * Params:
345 	 *     result = a #GAsyncResult
346 	 *
347 	 * Returns: %TRUE if the launch was successful, %FALSE if @error is set
348 	 *
349 	 * Since: 2.50
350 	 *
351 	 * Throws: GException on failure.
352 	 */
353 	public static bool launchDefaultForUriFinish(AsyncResultIF result)
354 	{
355 		GError* err = null;
356 
357 		auto p = g_app_info_launch_default_for_uri_finish((result is null) ? null : result.getAsyncResultStruct(), &err) != 0;
358 
359 		if (err !is null)
360 		{
361 			throw new GException( new ErrorG(err) );
362 		}
363 
364 		return p;
365 	}
366 
367 	/**
368 	 * Removes all changes to the type associations done by
369 	 * g_app_info_set_as_default_for_type(),
370 	 * g_app_info_set_as_default_for_extension(),
371 	 * g_app_info_add_supports_type() or
372 	 * g_app_info_remove_supports_type().
373 	 *
374 	 * Params:
375 	 *     contentType = a content type
376 	 *
377 	 * Since: 2.20
378 	 */
379 	public static void resetTypeAssociations(string contentType)
380 	{
381 		g_app_info_reset_type_associations(Str.toStringz(contentType));
382 	}
383 
384 	/**
385 	 * Adds a content type to the application information to indicate the
386 	 * application is capable of opening files with the given content type.
387 	 *
388 	 * Params:
389 	 *     contentType = a string.
390 	 *
391 	 * Returns: %TRUE on success, %FALSE on error.
392 	 *
393 	 * Throws: GException on failure.
394 	 */
395 	public bool addSupportsType(string contentType);
396 
397 	/**
398 	 * Obtains the information whether the #GAppInfo can be deleted.
399 	 * See g_app_info_delete().
400 	 *
401 	 * Returns: %TRUE if @appinfo can be deleted
402 	 *
403 	 * Since: 2.20
404 	 */
405 	public bool canDelete();
406 
407 	/**
408 	 * Checks if a supported content type can be removed from an application.
409 	 *
410 	 * Returns: %TRUE if it is possible to remove supported
411 	 *     content types from a given @appinfo, %FALSE if not.
412 	 */
413 	public bool canRemoveSupportsType();
414 
415 	/**
416 	 * Tries to delete a #GAppInfo.
417 	 *
418 	 * On some platforms, there may be a difference between user-defined
419 	 * #GAppInfos which can be deleted, and system-wide ones which cannot.
420 	 * See g_app_info_can_delete().
421 	 *
422 	 * Returns: %TRUE if @appinfo has been deleted
423 	 *
424 	 * Since: 2.20
425 	 */
426 	public bool delet();
427 
428 	/**
429 	 * Creates a duplicate of a #GAppInfo.
430 	 *
431 	 * Returns: a duplicate of @appinfo.
432 	 */
433 	public AppInfoIF dup();
434 
435 	/**
436 	 * Checks if two #GAppInfos are equal.
437 	 *
438 	 * Note that the check <emphasis>may not</emphasis> compare each individual
439 	 * field, and only does an identity check. In case detecting changes in the
440 	 * contents is needed, program code must additionally compare relevant fields.
441 	 *
442 	 * Params:
443 	 *     appinfo2 = the second #GAppInfo.
444 	 *
445 	 * Returns: %TRUE if @appinfo1 is equal to @appinfo2. %FALSE otherwise.
446 	 */
447 	public bool equal(AppInfoIF appinfo2);
448 
449 	/**
450 	 * Gets the commandline with which the application will be
451 	 * started.
452 	 *
453 	 * Returns: a string containing the @appinfo's commandline,
454 	 *     or %NULL if this information is not available
455 	 *
456 	 * Since: 2.20
457 	 */
458 	public string getCommandline();
459 
460 	/**
461 	 * Gets a human-readable description of an installed application.
462 	 *
463 	 * Returns: a string containing a description of the
464 	 *     application @appinfo, or %NULL if none.
465 	 */
466 	public string getDescription();
467 
468 	/**
469 	 * Gets the display name of the application. The display name is often more
470 	 * descriptive to the user than the name itself.
471 	 *
472 	 * Returns: the display name of the application for @appinfo, or the name if
473 	 *     no display name is available.
474 	 *
475 	 * Since: 2.24
476 	 */
477 	public string getDisplayName();
478 
479 	/**
480 	 * Gets the executable's name for the installed application.
481 	 *
482 	 * Returns: a string containing the @appinfo's application
483 	 *     binaries name
484 	 */
485 	public string getExecutable();
486 
487 	/**
488 	 * Gets the icon for the application.
489 	 *
490 	 * Returns: the default #GIcon for @appinfo or %NULL
491 	 *     if there is no default icon.
492 	 */
493 	public IconIF getIcon();
494 
495 	/**
496 	 * Gets the ID of an application. An id is a string that
497 	 * identifies the application. The exact format of the id is
498 	 * platform dependent. For instance, on Unix this is the
499 	 * desktop file id from the xdg menu specification.
500 	 *
501 	 * Note that the returned ID may be %NULL, depending on how
502 	 * the @appinfo has been constructed.
503 	 *
504 	 * Returns: a string containing the application's ID.
505 	 */
506 	public string getId();
507 
508 	/**
509 	 * Gets the installed name of the application.
510 	 *
511 	 * Returns: the name of the application for @appinfo.
512 	 */
513 	public string getName();
514 
515 	/**
516 	 * Retrieves the list of content types that @app_info claims to support.
517 	 * If this information is not provided by the environment, this function
518 	 * will return %NULL.
519 	 * This function does not take in consideration associations added with
520 	 * g_app_info_add_supports_type(), but only those exported directly by
521 	 * the application.
522 	 *
523 	 * Returns: a list of content types.
524 	 *
525 	 * Since: 2.34
526 	 */
527 	public string[] getSupportedTypes();
528 
529 	/**
530 	 * Launches the application. Passes @files to the launched application
531 	 * as arguments, using the optional @context to get information
532 	 * about the details of the launcher (like what screen it is on).
533 	 * On error, @error will be set accordingly.
534 	 *
535 	 * To launch the application without arguments pass a %NULL @files list.
536 	 *
537 	 * Note that even if the launch is successful the application launched
538 	 * can fail to start if it runs into problems during startup. There is
539 	 * no way to detect this.
540 	 *
541 	 * Some URIs can be changed when passed through a GFile (for instance
542 	 * unsupported URIs with strange formats like mailto:), so if you have
543 	 * a textual URI you want to pass in as argument, consider using
544 	 * g_app_info_launch_uris() instead.
545 	 *
546 	 * The launched application inherits the environment of the launching
547 	 * process, but it can be modified with g_app_launch_context_setenv()
548 	 * and g_app_launch_context_unsetenv().
549 	 *
550 	 * On UNIX, this function sets the `GIO_LAUNCHED_DESKTOP_FILE`
551 	 * environment variable with the path of the launched desktop file and
552 	 * `GIO_LAUNCHED_DESKTOP_FILE_PID` to the process id of the launched
553 	 * process. This can be used to ignore `GIO_LAUNCHED_DESKTOP_FILE`,
554 	 * should it be inherited by further processes. The `DISPLAY` and
555 	 * `DESKTOP_STARTUP_ID` environment variables are also set, based
556 	 * on information provided in @context.
557 	 *
558 	 * Params:
559 	 *     files = a #GList of #GFile objects
560 	 *     context = a #GAppLaunchContext or %NULL
561 	 *
562 	 * Returns: %TRUE on successful launch, %FALSE otherwise.
563 	 *
564 	 * Throws: GException on failure.
565 	 */
566 	public bool launch(ListG files, AppLaunchContext context);
567 
568 	/**
569 	 * Launches the application. This passes the @uris to the launched application
570 	 * as arguments, using the optional @context to get information
571 	 * about the details of the launcher (like what screen it is on).
572 	 * On error, @error will be set accordingly.
573 	 *
574 	 * To launch the application without arguments pass a %NULL @uris list.
575 	 *
576 	 * Note that even if the launch is successful the application launched
577 	 * can fail to start if it runs into problems during startup. There is
578 	 * no way to detect this.
579 	 *
580 	 * Params:
581 	 *     uris = a #GList containing URIs to launch.
582 	 *     context = a #GAppLaunchContext or %NULL
583 	 *
584 	 * Returns: %TRUE on successful launch, %FALSE otherwise.
585 	 *
586 	 * Throws: GException on failure.
587 	 */
588 	public bool launchUris(ListG uris, AppLaunchContext context);
589 
590 	/**
591 	 * Removes a supported type from an application, if possible.
592 	 *
593 	 * Params:
594 	 *     contentType = a string.
595 	 *
596 	 * Returns: %TRUE on success, %FALSE on error.
597 	 *
598 	 * Throws: GException on failure.
599 	 */
600 	public bool removeSupportsType(string contentType);
601 
602 	/**
603 	 * Sets the application as the default handler for the given file extension.
604 	 *
605 	 * Params:
606 	 *     extension = a string containing the file extension
607 	 *         (without the dot).
608 	 *
609 	 * Returns: %TRUE on success, %FALSE on error.
610 	 *
611 	 * Throws: GException on failure.
612 	 */
613 	public bool setAsDefaultForExtension(string extension);
614 
615 	/**
616 	 * Sets the application as the default handler for a given type.
617 	 *
618 	 * Params:
619 	 *     contentType = the content type.
620 	 *
621 	 * Returns: %TRUE on success, %FALSE on error.
622 	 *
623 	 * Throws: GException on failure.
624 	 */
625 	public bool setAsDefaultForType(string contentType);
626 
627 	/**
628 	 * Sets the application as the last used application for a given type.
629 	 * This will make the application appear as first in the list returned
630 	 * by g_app_info_get_recommended_for_type(), regardless of the default
631 	 * application for that content type.
632 	 *
633 	 * Params:
634 	 *     contentType = the content type.
635 	 *
636 	 * Returns: %TRUE on success, %FALSE on error.
637 	 *
638 	 * Throws: GException on failure.
639 	 */
640 	public bool setAsLastUsedForType(string contentType);
641 
642 	/**
643 	 * Checks if the application info should be shown in menus that
644 	 * list available applications.
645 	 *
646 	 * Returns: %TRUE if the @appinfo should be shown, %FALSE otherwise.
647 	 */
648 	public bool shouldShow();
649 
650 	/**
651 	 * Checks if the application accepts files as arguments.
652 	 *
653 	 * Returns: %TRUE if the @appinfo supports files.
654 	 */
655 	public bool supportsFiles();
656 
657 	/**
658 	 * Checks if the application supports reading files and directories from URIs.
659 	 *
660 	 * Returns: %TRUE if the @appinfo supports URIs.
661 	 */
662 	public bool supportsUris();
663 }