The Battle for Wesnoth  1.17.12+dev
manager.hpp
Go to the documentation of this file.
1 /*
2  Copyright (C) 2008 - 2022
3  by Iris Morelle <shadowm2006@gmail.com>
4  Copyright (C) 2003 - 2008 by David White <dave@whitevine.net>
5  Part of the Battle for Wesnoth Project https://www.wesnoth.org/
6 
7  This program is free software; you can redistribute it and/or modify
8  it under the terms of the GNU General Public License as published by
9  the Free Software Foundation; either version 2 of the License, or
10  (at your option) any later version.
11  This program is distributed in the hope that it will be useful,
12  but WITHOUT ANY WARRANTY.
13 
14  See the COPYING file for more details.
15 */
16 
17 /**
18  * @file
19  * Local add-on content management interface.
20  *
21  * This API only concerns local functionality dealing with enumerating and
22  * manipulating installed add-ons, as well as extracting add-ons in WML pack
23  * form, usually but not necessarily obtained through the networked client.
24  *
25  * It also includes functions for the handling of add-on versioning
26  * information (_info.cfg) and publishing information (_server.pbl).
27  */
28 
29 #pragma once
30 
31 class config;
32 class version_info;
33 
34 #include "addon/validation.hpp"
35 
36 #include <functional>
37 #include <string>
38 #include <vector>
39 #include <utility>
40 #include <map>
41 
42 /**
43  * Exception thrown when the WML parser fails to read a .pbl file.
44  */
45 struct invalid_pbl_exception : public std::exception
46 {
47  /**
48  * Constructor.
49  *
50  * @param pbl_path Path to the faulty .pbl file.
51  * @param msg An error message to display.
52  */
53  invalid_pbl_exception(const std::string& pbl_path, const std::string& msg)
54  : path(pbl_path), message(msg)
55  {}
56 
57  /** Path to the faulty .pbl file. */
58  const std::string path;
59 
60  /** Error message to display. */
61  const std::string message;
62 
63  /** Destructor.
64  * Virtual to allow for subclassing.
65  */
66  virtual ~invalid_pbl_exception() noexcept {}
67 
68  /** Returns a pointer to the (constant) error description.
69  * @return A pointer to a const char*. The underlying memory
70  * is in posession of the Exception object. Callers must
71  * not attempt to free the memory.
72  */
73  virtual const char* what() const noexcept {
74  return message.c_str();
75  }
76 };
77 
78 /**
79  * Removes the specified add-on, deleting its full directory structure.
80  */
81 bool remove_local_addon(const std::string& addon);
82 
83 /**
84  * Returns whether a .pbl file is present for the specified add-on or not.
85  */
86 bool have_addon_pbl_info(const std::string& addon_name);
87 
88 /**
89  * Returns whether the specified add-on appears to be managed by a VCS or not.
90  *
91  * This is used by the add-ons client to prompt the user before overwriting
92  * add-ons that may currently be managed externally instead of through the
93  * built-in campaignd client.
94  *
95  * Currently supported VCSes are: Subversion, Git, Mercurial.
96  */
97 bool have_addon_in_vcs_tree(const std::string& addon_name);
98 
99 /**
100  * Gets the publish information for an add-on.
101  *
102  * @param addon_name The add-on's main directory/file name.
103  * @param do_validate Whether we want to run validation on the .pbl file.
104  *
105  * @exception invalid_pbl_exception If it is not possible to read the .pbl file
106  * (often due to invalid WML).
107  */
108 config get_addon_pbl_info(const std::string& addon_name, bool do_validate);
109 
110 /**
111  * Sets the publish information for an add-on.
112  *
113  * @param addon_name The add-on's main directory/file name.
114  * @param cfg A config object from which the add-on's
115  * properties are copied.
116  */
117 void set_addon_pbl_info(const std::string& addon_name, const class config& cfg);
118 
119 /**
120  * Returns true if there is a local installation info (_info.cfg) file for the add-on.
121  */
122 bool have_addon_install_info(const std::string& addon_name);
123 
124 /**
125  * Gets the installation info (_info.cfg) for an add-on.
126  *
127  * @param addon_name The add-on's main directory/file name.
128  * @param cfg A config object to store the add-on's
129  * properties.
130  */
131 void get_addon_install_info(const std::string& addon_name, class config& cfg);
132 
133 /**
134  * Writes the installation info (_info.cfg) for an add-on to disk.
135  *
136  * @param addon_name The add-on's main directory/file name.
137  * @param cfg A config object containing the add-on's
138  * properties.
139  */
140 void write_addon_install_info(const std::string& addon_name, const class config& cfg);
141 
142 /** Returns a list of local add-ons that can be published. */
143 std::vector<std::string> available_addons();
144 
145 /** Retrieves the names of all installed add-ons. */
146 std::vector<std::string> installed_addons();
147 
148 /** Retrieves the ids and versions of all installed add-ons. */
149 std::map<std::string, std::string> installed_addons_and_versions();
150 
151 /** Check whether the specified add-on is currently installed. */
152 bool is_addon_installed(const std::string& addon_name);
153 
154 /** Archives an add-on into a config object for campaignd transactions. */
155 void archive_addon(const std::string& addon_name, class config& cfg);
156 
157 /** Unarchives an add-on from campaignd's retrieved config object. */
158 void unarchive_addon(const class config& cfg, std::function<void(unsigned)> progress_callback = {});
159 
160 /** Removes the listed files from the addon. */
161 void purge_addon(const config& removelist);
162 
163 /** Refreshes the per-session cache of add-on's version information structs. */
165 
166 /** Returns a particular installed add-on's version information. */
167 version_info get_addon_version_info(const std::string& addon);
std::vector< std::string > available_addons()
Returns a list of local add-ons that can be published.
Definition: manager.cpp:186
invalid_pbl_exception(const std::string &pbl_path, const std::string &msg)
Constructor.
Definition: manager.hpp:53
void refresh_addon_version_info_cache()
Refreshes the per-session cache of add-on&#39;s version information structs.
Definition: manager.cpp:388
const std::string path
Path to the faulty .pbl file.
Definition: manager.hpp:58
void set_addon_pbl_info(const std::string &addon_name, const class config &cfg)
Sets the publish information for an add-on.
bool have_addon_in_vcs_tree(const std::string &addon_name)
Returns whether the specified add-on appears to be managed by a VCS or not.
Definition: manager.cpp:56
config get_addon_pbl_info(const std::string &addon_name, bool do_validate)
Gets the publish information for an add-on.
Definition: manager.cpp:70
bool have_addon_install_info(const std::string &addon_name)
Returns true if there is a local installation info (_info.cfg) file for the add-on.
Definition: manager.cpp:101
Exception thrown when the WML parser fails to read a .pbl file.
Definition: manager.hpp:45
bool have_addon_pbl_info(const std::string &addon_name)
Returns whether a .pbl file is present for the specified add-on or not.
Definition: manager.cpp:65
bool remove_local_addon(const std::string &addon)
Removes the specified add-on, deleting its full directory structure.
Definition: manager.cpp:143
static void msg(const char *act, debug_info &i, const char *to="", const char *result="")
Definition: debugger.cpp:110
void archive_addon(const std::string &addon_name, class config &cfg)
Archives an add-on into a config object for campaignd transactions.
Definition: manager.cpp:297
std::map< std::string, std::string > installed_addons_and_versions()
Retrieves the ids and versions of all installed add-ons.
Definition: manager.cpp:196
void purge_addon(const config &removelist)
Removes the listed files from the addon.
Definition: manager.cpp:378
const std::string message
Error message to display.
Definition: manager.hpp:61
bool is_addon_installed(const std::string &addon_name)
Check whether the specified add-on is currently installed.
Definition: manager.cpp:219
void unarchive_addon(const class config &cfg, std::function< void(unsigned)> progress_callback={})
Unarchives an add-on from campaignd&#39;s retrieved config object.
void write_addon_install_info(const std::string &addon_name, const class config &cfg)
Writes the installation info (_info.cfg) for an add-on to disk.
virtual ~invalid_pbl_exception() noexcept
Destructor.
Definition: manager.hpp:66
version_info get_addon_version_info(const std::string &addon)
Returns a particular installed add-on&#39;s version information.
Definition: manager.cpp:429
virtual const char * what() const noexcept
Returns a pointer to the (constant) error description.
Definition: manager.hpp:73
Represents version numbers.
void get_addon_install_info(const std::string &addon_name, class config &cfg)
Gets the installation info (_info.cfg) for an add-on.
Definition: manager.cpp:106
A config object defines a single node in a WML file, with access to child nodes.
Definition: config.hpp:60
std::vector< std::string > installed_addons()
Retrieves the names of all installed add-ons.
Definition: manager.cpp:191