The Battle for Wesnoth  1.19.0-dev
open.hpp
Go to the documentation of this file.
1 /*
2  Copyright (C) 2013 - 2024
3  by Iris Morelle <shadowm2006@gmail.com>
4  Part of the Battle for Wesnoth Project https://www.wesnoth.org/
5 
6  This program is free software; you can redistribute it and/or modify
7  it under the terms of the GNU General Public License as published by
8  the Free Software Foundation; either version 2 of the License, or
9  (at your option) any later version.
10  This program is distributed in the hope that it will be useful,
11  but WITHOUT ANY WARRANTY.
12 
13  See the COPYING file for more details.
14 */
15 
16 /**
17  * @file
18  * Desktop environment interaction functions.
19  */
20 
21 #pragma once
22 
23 #include <string>
24 
25 namespace desktop {
26 
27 /**
28  * Opens the specified object with the default application configured for its type.
29  *
30  * The default application for handling the object represented by
31  * @a path_or_url is defined by the operating system and desktop environment
32  * under which Wesnoth is running, and it is not under our control. Therefore,
33  * <b>EXTREME CAUTION</b> is advised when using this function with URLs or
34  * paths that are entirely or partially constructed from user-provided input
35  * (e.g., WML from user-made add-ons, chat log messages).
36  *
37  * If the content pointed to by @a path_or_url cannot be trusted, you should
38  * either refrain from using this function, or warn the user before calling
39  * this function.
40  *
41  * @note Currently, only X11, Apple OS X, and Microsoft Windows are supported.
42  * Using this function on unsupported platforms will result in an error
43  * message logged in stderr.
44  *
45  * @return @a true on success, @a false otherwise. Failure to perform the
46  * platform call means either that we do not currently support the
47  * running platform, the child process exited with a non-zero status,
48  * or something else went wrong. Thus, a value of @a true does not
49  * truly guarantee success -- take it with a grain of salt.
50  */
51 bool open_object(const std::string& path_or_url);
52 
53 /** Returns whether open_object() is supported/implemented for the current platform. */
54 constexpr bool open_object_is_supported()
55 {
56 #if defined(_X11) || defined(__APPLE__) || defined(_WIN32)
57  return true;
58 #else
59  return false;
60 #endif
61 }
62 
63 }
bool open_object([[maybe_unused]] const std::string &path_or_url)
Definition: open.cpp:46
constexpr bool open_object_is_supported()
Returns whether open_object() is supported/implemented for the current platform.
Definition: open.hpp:54