OpenCPN Partial API docs
Loading...
Searching...
No Matches
plugin_loader.h
Go to the documentation of this file.
1/**************************************************************************
2 * Copyright (C) 2010 - 2023 by David S. Register *
3 * Copyright (C) 2023 - 2025 Alec Leamas *
4 * *
5 * This program is free software; you can redistribute it and/or modify *
6 * it under the terms of the GNU General Public License as published by *
7 * the Free Software Foundation; either version 2 of the License, or *
8 * (at your option) any later version. *
9 * *
10 * This program 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 General Public License for more details. *
14 * *
15 * You should have received a copy of the GNU General Public License *
16 * along with this program; if not, write to the *
17 * Free Software Foundation, Inc., *
18 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. *
19 **************************************************************************/
20
26#ifndef PLUGIN_LOADER_H_GUARD
27#define PLUGIN_LOADER_H_GUARD
28
29#include <functional>
30
31#include <wx/wx.h>
32#include <wx/bitmap.h>
33#include <wx/dynarray.h>
34#include <wx/dynlib.h>
35
36#include "config.h"
37
39#include "model/plugin_blacklist.h"
40#include "model/semantic_vers.h"
41#include "observable_evtvar.h"
42#include "ocpn_plugin.h"
43
44enum class PluginStatus {
45 System,
46 Managed,
47 Unmanaged,
48 Ghost,
49 Unknown,
50 LegacyUpdateAvailable,
51 ManagedInstallAvailable,
52 ManagedInstalledUpdateAvailable,
53 ManagedInstalledCurrentVersion,
54 ManagedInstalledDowngradeAvailable,
55 Imported,
56 PendingListRemoval
57};
58
59class PlugInContainer; // forward
60
63public:
65 explicit PlugInData(const PluginMetadata& md);
66
67 PlugInData();
68
70 bool m_enabled;
71 bool m_init_state;
72 bool m_toolbox_panel;
74 wxString m_plugin_file;
77 wxString m_common_name;
78 wxString m_short_description;
79 wxString m_long_description;
80 int m_api_version;
81 int m_version_major;
82 int m_version_minor;
83 PluginStatus m_status;
84 PluginMetadata m_managed_metadata;
85 wxBitmap m_bitmap;
86 wxString m_version_str;
87 std::string m_manifest_version;
88
90 std::string Key() const;
91};
92
98public:
100
101 ~PlugInContainer() = default;
102
103 opencpn_plugin* m_pplugin;
104 wxDynamicLibrary m_library;
105 destroy_t* m_destroy_fn;
106};
107
110public:
111 enum class Type {
112 Unloadable, //<! wrong magic, wrong type of binary...
113 Unreadable,
114 Incompatible,
115 NoCreate, //<! Missing linkage (is this a plugin?)
116 NoDestroy, //<! Missing linkage (is this a plugin?)
117 Blacklisted
118 } type;
119 const std::string lib_path; //<! Complete path to failing library
120 //<! As determined from plugin API
121 const SemanticVersion plugin_version; //<! As determined from plugin API
122
123 LoadError(Type t, const std::string& l, SemanticVersion pv)
124 : type(t), lib_path(l), plugin_version(pv) {}
125
126 LoadError(Type t, std::string l)
127 : type(t), lib_path(std::move(l)), plugin_version(SemanticVersion()) {}
128};
129
130// Declare an array of PlugIn Containers
131WX_DEFINE_ARRAY_PTR(PlugInContainer*, ArrayOfPlugIns);
132
154public:
155 static PluginLoader* GetInstance();
156 virtual ~PluginLoader() = default;
157
162 static void MarkAsLoadable(const std::string& library_path);
166 static void UpdatePlugin(PlugInContainer* plugin, const PluginMetadata& md);
167
169 static std::string GetPluginVersion(
170 const PlugInData pd,
171 std::function<const PluginMetadata(const std::string&)> get_metadata);
172
174 static PluginMetadata MetadataByName(const std::string& name);
175
176 EventVar evt_blacklisted_plugin;
177
178 EventVar evt_load_directory;
179 EventVar evt_load_plugin;
180 EventVar evt_plugin_unload;
181 EventVar evt_pluglist_change;
182 EventVar evt_unreadable_plugin;
183
189
192
198
201
210 bool LoadAllPlugIns(bool enabled_plugins, bool keep_orphans = false);
211
212 const wxBitmap* GetPluginDefaultIcon();
213 void SetPluginDefaultIcon(const wxBitmap* bitmap);
214
216 void SetOnDeactivateCb(std::function<void(const PlugInContainer*)> cb) {
217 m_on_deactivate_cb = cb;
218 }
220 void ShowPreferencesDialog(const PlugInData& pd, wxWindow* parent);
221
222 void NotifySetupOptionsPlugin(const PlugInData* pic);
223
225 void RemovePlugin(const PlugInData& pd);
226
228 void SortPlugins(int (*cmp_func)(PlugInContainer**, PlugInContainer**));
229
231 bool UnLoadPlugIn(size_t ix);
232
233 bool UnLoadAllPlugIns();
234 bool DeactivateAllPlugIns();
235 bool DeactivatePlugIn(PlugInContainer* pic);
236 bool DeactivatePlugIn(const PlugInData& pic);
237 bool UpdatePlugIns();
238 void UpdateManagedPlugins(bool keep_orphans);
239 PlugInContainer* LoadPlugIn(const wxString& plugin_file);
240 PlugInContainer* LoadPlugIn(const wxString& plugin_file,
241 PlugInContainer* pic);
242
243 const ArrayOfPlugIns* GetPlugInArray() { return &plugin_array; }
244 bool IsPlugInAvailable(const wxString& commonName);
245 bool CheckPluginCompatibility(const wxString& plugin_file);
246
248 void SetEnabled(const wxString& common_name, bool enabled);
249
251 void SetToolboxPanel(const wxString& common_name, bool value);
252
254 void SetSetupOptions(const wxString& common_name, bool value);
255
256private:
257 PluginLoader();
258 bool LoadPlugInDirectory(const wxString& plugin_dir, bool load_enabled);
259 bool LoadPluginCandidate(const wxString& file_name, bool load_enabled);
260 std::unique_ptr<AbstractBlacklist> m_blacklist;
261 ArrayOfPlugIns plugin_array;
262 wxString m_last_error_string;
263 wxString m_plugin_location;
264
265#ifdef __WXMSW__
266 wxString m_module_name;
267 bool m_found_wxwidgets;
268#endif
269
270 const wxBitmap* m_default_plugin_icon;
271 std::function<void(const PlugInContainer*)> m_on_deactivate_cb;
272
273 std::vector<LoadError> load_errors;
274};
275
276#endif // PLUGIN_LOADER_H_GUARD
Datatypes and methods to parse ocpn-plugins.xml XML data, either complete catalog or a single plugin.
Generic event handling between MVC Model and Controller based on a shared EventVar variable.
Error condition when loading a plugin.
Data for a loaded plugin, including dl-loaded library.
Basic data for a loaded plugin, trivially copyable.
wxString m_plugin_filename
The short file path.
wxString m_plugin_file
The full file path.
int m_cap_flag
PlugIn Capabilities descriptor.
wxString m_common_name
A common name string for the plugin.
bool m_has_setup_options
Has run NotifySetupOptionsPlugin()
std::string Key() const
sort key.
std::string m_manifest_version
As detected from manifest.
wxDateTime m_plugin_modification
used to detect upgraded plugins
wxString m_version_str
Complete version as of semantic_vers.
PluginLoader is a backend module without any direct GUI functionality.
void SetOnDeactivateCb(std::function< void(const PlugInContainer *)> cb)
Callback invoked in late stage on deactivating a plugin.
bool LoadAllPlugIns(bool enabled_plugins, bool keep_orphans=false)
Update catalog with imported metadata and load all plugin library files.
static void MarkAsLoadable(const std::string &library_path)
Mark a library file (complete path) as loadable i.
EventVar evt_plugin_loadall_finalize
Emitted after all plugins are loaded.
static std::string GetPluginVersion(const PlugInData pd, std::function< const PluginMetadata(const std::string &)> get_metadata)
Return version string for a plugin, possibly with an "Imported" suffix.
bool UnLoadPlugIn(size_t ix)
Unload, delete and remove item ix in GetPlugInArray().
void SortPlugins(int(*cmp_func)(PlugInContainer **, PlugInContainer **))
Sort GetPluginArray().
static void UpdatePlugin(PlugInContainer *plugin, const PluginMetadata &md)
Update PlugInContainer status using data from PluginMetadata and manifest.
void SetSetupOptions(const wxString &common_name, bool value)
Update m_has_setup_options state for plugin with given name.
void SetEnabled(const wxString &common_name, bool enabled)
Update enabled/disabled state for plugin with given name.
void SetToolboxPanel(const wxString &common_name, bool value)
Update m_toolbox_panel state for plugin with given name.
static PluginMetadata MetadataByName(const std::string &name)
Find metadata for given plugin.
void RemovePlugin(const PlugInData &pd)
Remove a plugin from *GetPluginArray().
void ShowPreferencesDialog(const PlugInData &pd, wxWindow *parent)
Display the preferences dialog for a plugin.
EventVar evt_version_incompatible_plugin
FIXME (leamas) not notified.
EventVar evt_deactivate_plugin
Carries a malloc'ed read-only copy of a PlugInContainer owned: by listener.
EventVar evt_update_chart_types
Notified without data after all plugins loaded ot updated.
Base class for OpenCPN plugins.
PlugIn Object Definition/API.
PluginStatus
@ Ghost
Managed, shadowing another (packaged?) plugin.
@ Unmanaged
Unmanaged, probably a package.
@ Managed
Managed by installer.
@ System
One of the four system plugins, unmanaged.
Plugin metadata, reflects the xml format directly.
Versions uses a modified semantic versioning scheme: major.minor.revision.post-tag+build.