Audacity  3.0.3
PluginManager.h
Go to the documentation of this file.
1 /**********************************************************************
2 
3  Audacity: A Digital Audio Editor
4 
5  PluginManager.h
6 
7  Leland Lucius
8 
9 **********************************************************************/
10 
11 #ifndef __AUDACITY_PLUGINMANAGER_H__
12 #define __AUDACITY_PLUGINMANAGER_H__
13 
14 #include <wx/defs.h>
15 
16 #include "wxArrayStringEx.h"
17 #include <map>
18 #include <memory>
19 
20 #include "EffectInterface.h"
21 #include "PluginInterface.h"
22 
23 class wxArrayString;
24 class FileConfig;
25 
27 //
28 // PluginDescriptor
29 //
31 
32 typedef enum : unsigned {
33  PluginTypeNone = 0, // 2.1.0 placeholder entries...not used by 2.1.1 or greater
34  PluginTypeStub =1, // Used for plugins that have not yet been registered
40 } PluginType;
41 
42 // TODO: Convert this to multiple derived classes
43 class AUDACITY_DLL_API PluginDescriptor
44 {
45 public:
48  virtual ~PluginDescriptor();
49 
50  bool IsInstantiated() const;
51 
52  PluginType GetPluginType() const;
53 
54  // All plugins
55 
56  // These return untranslated strings
57  const wxString & GetID() const;
58  const wxString & GetProviderID() const;
59  const PluginPath & GetPath() const;
60  const ComponentInterfaceSymbol & GetSymbol() const;
61 
62  wxString GetUntranslatedVersion() const;
63  // There is no translated version
64 
65  wxString GetVendor() const;
66 
67  bool IsEnabled() const;
68  bool IsValid() const;
69 
70  void SetEnabled(bool enable);
71  void SetValid(bool valid);
72 
73  // Effect plugins only
74 
75  // Internal string only, no translated counterpart!
76  // (Use Effect::GetFamilyName instead)
77  // This string persists in configuration files
78  // So config compatibility will break if it is changed across Audacity versions
79  wxString GetEffectFamily() const;
80 
81  EffectType GetEffectType() const;
82  bool IsEffectDefault() const;
83  bool IsEffectInteractive() const;
84  bool IsEffectLegacy() const;
85  bool IsEffectRealtime() const;
86  bool IsEffectAutomatable() const;
87 
88  // Importer plugins only
89 
90  const wxString & GetImporterIdentifier() const;
92  const FileExtensions & GetImporterExtensions() const;
93 
94 private:
95  friend class PluginManager;
96 
98  void SetInstance(std::unique_ptr<ComponentInterface> instance);
99 
100  void SetPluginType(PluginType type);
101 
102  // These should be passed an untranslated value
103  void SetID(const PluginID & ID);
104  void SetProviderID(const PluginID & providerID);
105  void SetPath(const PluginPath & path);
106  void SetSymbol(const ComponentInterfaceSymbol & symbol);
107 
108  // These should be passed an untranslated value wrapped in XO() so
109  // the value will still be extracted for translation
110  void SetVersion(const wxString & version);
111  void SetVendor(const wxString & vendor);
112 
113  // "family" should be an untranslated string wrapped in wxT()
114  void SetEffectFamily(const wxString & family);
115  void SetEffectType(EffectType type);
116  void SetEffectDefault(bool dflt);
117  void SetEffectInteractive(bool interactive);
118  void SetEffectLegacy(bool legacy);
119  void SetEffectRealtime(bool realtime);
120  void SetEffectAutomatable(bool automatable);
121 
122  void SetImporterIdentifier(const wxString & identifier);
124  void SetImporterExtensions(FileExtensions extensions);
125 
126  // Common
127 
128  // Among other purposes, PluginDescriptor acts as the resource handle,
129  // or smart pointer, to a resource created in a plugin library, and is responsible
130  // for a cleanup of this pointer.
131  std::unique_ptr<ComponentInterface> muInstance; // may be null for a module
133 
135 
136  wxString mID;
139  wxString mVersion;
140  wxString mVendor;
141  wxString mProviderID;
142  bool mEnabled;
143  bool mValid;
144 
145  // Effects
146 
147  wxString mEffectFamily;
154 
155  // Importers
156 
159 };
160 
162 //
163 // PluginManager
164 //
166 
167 typedef std::map<PluginID, PluginDescriptor> PluginMap;
168 
169 typedef wxArrayString PluginIDs;
170 
172 
173 class AUDACITY_DLL_API PluginManager final : public PluginManagerInterface
174 {
175 public:
176 
177  RegistryPath GetPluginEnabledSetting( const PluginID &ID ) const;
178  RegistryPath GetPluginEnabledSetting( const PluginDescriptor &desc ) const;
179 
180  // PluginManagerInterface implementation
181 
182  bool IsPluginRegistered(
183  const PluginPath &path, const TranslatableString *pSymbol) override;
184 
185  const PluginID & RegisterPlugin(ModuleInterface *module) override;
186  const PluginID & RegisterPlugin(ModuleInterface *provider, ComponentInterface *command);
187  const PluginID & RegisterPlugin(ModuleInterface *provider, EffectDefinitionInterface *effect, int type) override;
188 
189  void FindFilesInPathList(const wxString & pattern,
190  const FilePaths & pathList,
191  FilePaths & files,
192  bool directories = false) override;
193 
194  bool HasSharedConfigGroup(const PluginID & ID, const RegistryPath & group) /* not override */;
195  bool GetSharedConfigSubgroups(const PluginID & ID, const RegistryPath & group, RegistryPaths &subgroups) override;
196 
197  bool GetSharedConfig(const PluginID & ID, const RegistryPath & group, const RegistryPath & key, wxString & value, const wxString & defval = _T("")) override;
198  bool GetSharedConfig(const PluginID & ID, const RegistryPath & group, const RegistryPath & key, int & value, int defval = 0) override;
199  bool GetSharedConfig(const PluginID & ID, const RegistryPath & group, const RegistryPath & key, bool & value, bool defval = false) override;
200  bool GetSharedConfig(const PluginID & ID, const RegistryPath & group, const RegistryPath & key, float & value, float defval = 0.0) override;
201  bool GetSharedConfig(const PluginID & ID, const RegistryPath & group, const RegistryPath & key, double & value, double defval = 0.0) override;
202 
203  bool SetSharedConfig(const PluginID & ID, const RegistryPath & group, const RegistryPath & key, const wxString & value) override;
204  bool SetSharedConfig(const PluginID & ID, const RegistryPath & group, const RegistryPath & key, const int & value) override;
205  bool SetSharedConfig(const PluginID & ID, const RegistryPath & group, const RegistryPath & key, const bool & value) override;
206  bool SetSharedConfig(const PluginID & ID, const RegistryPath & group, const RegistryPath & key, const float & value) override;
207  bool SetSharedConfig(const PluginID & ID, const RegistryPath & group, const RegistryPath & key, const double & value) override;
208 
209  bool RemoveSharedConfigSubgroup(const PluginID & ID, const RegistryPath & group) override;
210  bool RemoveSharedConfig(const PluginID & ID, const RegistryPath & group, const RegistryPath & key) override;
211 
212  bool HasPrivateConfigGroup(const PluginID & ID, const RegistryPath & group) /* not override */;
213  bool GetPrivateConfigSubgroups(const PluginID & ID, const RegistryPath & group, RegistryPaths &subgroups) override;
214 
215  bool GetPrivateConfig(const PluginID & ID, const RegistryPath & group, const RegistryPath & key, wxString & value, const wxString & defval = _T("")) override;
216  bool GetPrivateConfig(const PluginID & ID, const RegistryPath & group, const RegistryPath & key, int & value, int defval = 0) override;
217  bool GetPrivateConfig(const PluginID & ID, const RegistryPath & group, const RegistryPath & key, bool & value, bool defval = false) override;
218  bool GetPrivateConfig(const PluginID & ID, const RegistryPath & group, const RegistryPath & key, float & value, float defval = 0.0) override;
219  bool GetPrivateConfig(const PluginID & ID, const RegistryPath & group, const RegistryPath & key, double & value, double defval = 0.0) override;
220 
221  bool SetPrivateConfig(const PluginID & ID, const RegistryPath & group, const RegistryPath & key, const wxString & value) override;
222  bool SetPrivateConfig(const PluginID & ID, const RegistryPath & group, const RegistryPath & key, const int & value) override;
223  bool SetPrivateConfig(const PluginID & ID, const RegistryPath & group, const RegistryPath & key, const bool & value) override;
224  bool SetPrivateConfig(const PluginID & ID, const RegistryPath & group, const RegistryPath & key, const float & value) override;
225  bool SetPrivateConfig(const PluginID & ID, const RegistryPath & group, const RegistryPath & key, const double & value) override;
226 
227  bool RemovePrivateConfigSubgroup(const PluginID & ID, const RegistryPath & group) override;
228  bool RemovePrivateConfig(const PluginID & ID, const RegistryPath & group, const RegistryPath & key) override;
229 
230  // PluginManager implementation
231 
232  void Initialize();
233  void Terminate();
234 
235  bool DropFile(const wxString &fileName);
236 
237  static PluginManager & Get();
238 
239  static PluginID GetID(ModuleInterface *module);
240  static PluginID GetID(ComponentInterface *command);
241  static PluginID GetID(EffectDefinitionInterface *effect);
242 
243  // This string persists in configuration files
244  // So config compatibility will break if it is changed across Audacity versions
245  static wxString GetPluginTypeString(PluginType type);
246 
247  int GetPluginCount(PluginType type);
248  const PluginDescriptor *GetPlugin(const PluginID & ID) const;
249 
252  class Iterator {
253  public:
255  explicit Iterator(PluginManager &manager);
257  Iterator(PluginManager &manager,
258  int pluginType
259  );
261  Iterator(PluginManager &manager, EffectType type);
262  bool operator != (int) const {
263  return mIterator != mPm.mPlugins.end();
264  }
265  Iterator &operator ++ ();
266  auto &operator *() const { return mIterator->second; }
267  private:
268  void Advance(bool incrementing);
270  PluginMap::iterator mIterator;
271  EffectType mEffectType{ EffectTypeNone };
272  int mPluginType{ PluginTypeNone };
273  };
274  struct Range {
276  Iterator begin() const { return first; }
277  int end() const { return 0; }
278  };
279 
280  Range AllPlugins() { return { Iterator{ *this } }; }
281  Range PluginsOfType(int type) { return { Iterator{ *this, type } }; }
282  Range EffectsOfType(EffectType type) { return { Iterator{ *this, type } }; }
284 
285  bool IsPluginEnabled(const PluginID & ID);
286  void EnablePlugin(const PluginID & ID, bool enable);
287 
288  const ComponentInterfaceSymbol & GetSymbol(const PluginID & ID);
289  ComponentInterface *GetInstance(const PluginID & ID);
290 
291  void CheckForUpdates(bool bFast = false);
292 
294  const PluginID & RegisterPlugin(
295  std::unique_ptr<EffectDefinitionInterface> effect, PluginType type );
296  void UnregisterPlugin(const PluginID & ID);
297 
299  void Load();
301  void Save();
302 
303 private:
304  // private! Use Get()
305  PluginManager();
306  ~PluginManager();
307 
308  void LoadGroup(FileConfig *pRegistry, PluginType type);
309  void SaveGroup(FileConfig *pRegistry, PluginType type);
310 
311  PluginDescriptor & CreatePlugin(const PluginID & id, ComponentInterface *ident, PluginType type);
312 
313  FileConfig *GetSettings();
314 
315  bool HasGroup(const RegistryPath & group);
316  bool GetSubgroups(const RegistryPath & group, RegistryPaths & subgroups);
317 
318  bool GetConfig(const RegistryPath & key, wxString & value, const wxString & defval = L"");
319  bool GetConfig(const RegistryPath & key, int & value, int defval = 0);
320  bool GetConfig(const RegistryPath & key, bool & value, bool defval = false);
321  bool GetConfig(const RegistryPath & key, float & value, float defval = 0.0);
322  bool GetConfig(const RegistryPath & key, double & value, double defval = 0.0);
323 
324  bool SetConfig(const RegistryPath & key, const wxString & value);
325  bool SetConfig(const RegistryPath & key, const int & value);
326  bool SetConfig(const RegistryPath & key, const bool & value);
327  bool SetConfig(const RegistryPath & key, const float & value);
328  bool SetConfig(const RegistryPath & key, const double & value);
329 
330  /* Return values are keys for lookup in a config file */
331  RegistryPath SettingsPath(const PluginID & ID, bool shared);
332  RegistryPath SharedGroup(const PluginID & ID, const RegistryPath & group);
333  RegistryPath SharedKey(const PluginID & ID, const RegistryPath & group, const RegistryPath & key);
334  RegistryPath PrivateGroup(const PluginID & ID, const RegistryPath & group);
335  RegistryPath PrivateKey(const PluginID & ID, const RegistryPath & group, const RegistryPath & key);
336 
337  // The PluginID must be kept unique. Since the wxFileConfig class does not preserve
338  // case, we use base64 encoding.
339  wxString ConvertID(const PluginID & ID);
340  wxString b64encode(const void *in, int len);
341  int b64decode(const wxString &in, void *out);
342 
343 private:
344  friend std::default_delete<PluginManager>;
345  static std::unique_ptr<PluginManager> mInstance;
346 
347  bool IsDirty();
348  void SetDirty(bool dirty = true);
349  std::unique_ptr<FileConfig> mSettings;
350 
351  bool mDirty;
353 
355 };
356 
357 // Defining these special names in the low-level PluginManager.h
358 // is unfortunate
359 // Internal name should be stable across versions
360 #define NYQUIST_PROMPT_ID wxT("Nyquist Prompt")
361 // User-visible name might change in later versions
362 #define NYQUIST_PROMPT_NAME XO("Nyquist Prompt")
363 
364 #endif /* __AUDACITY_PLUGINMANAGER_H__ */
PluginDescriptor::mEffectLegacy
bool mEffectLegacy
Definition: PluginManager.h:151
TranslatableString
Holds a msgid for the translation catalog; may also bind format arguments.
Definition: TranslatableString.h:32
PluginManager::GetInstance
ComponentInterface * GetInstance(const PluginID &ID)
Definition: PluginManager.cpp:1532
PluginDescriptor::mVendor
wxString mVendor
Definition: PluginManager.h:140
PluginTypeEffect
@ PluginTypeEffect
Definition: PluginManager.h:35
PluginDescriptor::mInstance
ComponentInterface * mInstance
Definition: PluginManager.h:132
operator*
Vector operator*(const Vector &left, const Vector &right)
Definition: Matrix.cpp:153
PluginManager::mPlugins
PluginMap mPlugins
Definition: PluginManager.h:354
PluginManagerInterface::RemoveSharedConfig
virtual bool RemoveSharedConfig(const PluginID &ID, const RegistryPath &group, const RegistryPath &key)=0
PluginManager::Range::begin
Iterator begin() const
Definition: PluginManager.h:276
EffectInterface.h
ident
static CommandHandlerObject & ident(AudacityProject &project)
Definition: ModNullCallback.cpp:65
PluginManagerInterface::RemoveSharedConfigSubgroup
virtual bool RemoveSharedConfigSubgroup(const PluginID &ID, const RegistryPath &group)=0
RegistryPaths
std::vector< RegistryPath > RegistryPaths
Definition: Identifier.h:219
PluginPath
wxString PluginPath
type alias for identifying a Plugin supplied by a module, each module defining its own interpretation...
Definition: Identifier.h:214
operator!=
bool operator!=(const Tags &lhs, const Tags &rhs)
Definition: Tags.h:140
PluginManager::mCurrentIndex
int mCurrentIndex
Definition: PluginManager.h:352
PluginDescriptor::mVersion
wxString mVersion
Definition: PluginManager.h:139
PluginManager::SetDirty
void SetDirty(bool dirty=true)
EffectTypeNone
@ EffectTypeNone
Definition: EffectInterface.h:56
PluginDescriptor::mProviderID
wxString mProviderID
Definition: PluginManager.h:141
PluginRegistrationDialog
Definition: PluginRegistrationDialog.h:25
PluginManagerInterface::RegisterPlugin
virtual const PluginID & RegisterPlugin(ModuleInterface *module)=0
PluginManagerInterface::SetPrivateConfig
virtual bool SetPrivateConfig(const PluginID &ID, const RegistryPath &group, const RegistryPath &key, const wxString &value)=0
PluginDescriptor::muInstance
std::unique_ptr< ComponentInterface > muInstance
Definition: PluginManager.h:131
PluginDescriptor::mEffectDefault
bool mEffectDefault
Definition: PluginManager.h:150
PluginDescriptor::mPluginType
PluginType mPluginType
Definition: PluginManager.h:134
wxArrayStringEx
Extend wxArrayString with move operations and construction and insertion fromstd::initializer_list.
Definition: wxArrayStringEx.h:18
desc
const TranslatableString desc
Definition: ExportPCM.cpp:58
ComponentInterfaceSymbol
ComponentInterfaceSymbol pairs a persistent string identifier used internally with an optional,...
Definition: ComponentInterfaceSymbol.h:27
PluginType
PluginType
Definition: PluginManager.h:32
ModuleInterface
Definition: ModuleInterface.h:70
PluginManager::Range
Definition: PluginManager.h:274
PluginManagerInterface::RemovePrivateConfig
virtual bool RemovePrivateConfig(const PluginID &ID, const RegistryPath &group, const RegistryPath &key)=0
PluginIDs
wxArrayString PluginIDs
Definition: PluginManager.h:169
PluginManagerInterface::GetSharedConfigSubgroups
virtual bool GetSharedConfigSubgroups(const PluginID &ID, const RegistryPath &group, RegistryPaths &subgroups)=0
PluginDescriptor::SetImporterFilterDescription
void SetImporterFilterDescription(const TranslatableString &filterDesc)
PluginManagerInterface::IsPluginRegistered
virtual bool IsPluginRegistered(const PluginPath &path, const TranslatableString *pName=nullptr)=0
Was the plugin registry already populated for a path (maybe from loading the config file)?
PluginManager::Iterator::mPm
const PluginManager & mPm
Definition: PluginManager.h:269
PluginMap
std::map< PluginID, PluginDescriptor > PluginMap
Definition: PluginManager.h:167
PluginManager::Iterator
Definition: PluginManager.h:252
PluginDescriptor::mPath
PluginPath mPath
Definition: PluginManager.h:137
PluginManager::IsDirty
bool IsDirty()
PluginManagerInterface
Definition: PluginInterface.h:55
PluginDescriptor::mEffectInteractive
bool mEffectInteractive
Definition: PluginManager.h:149
BasicUI::Get
Services * Get()
Fetch the global instance, or nullptr if none is yet installed.
Definition: BasicUI.cpp:26
PluginID
wxString PluginID
Definition: EffectManager.h:30
PluginDescriptor::GetImporterFilterDescription
const TranslatableString & GetImporterFilterDescription() const
PluginManager::mSettings
std::unique_ptr< FileConfig > mSettings
Definition: PluginManager.h:349
PluginTypeModule
@ PluginTypeModule
Definition: PluginManager.h:39
PluginManager::EffectsOfType
Range EffectsOfType(EffectType type)
Definition: PluginManager.h:282
PluginManagerInterface::RemovePrivateConfigSubgroup
virtual bool RemovePrivateConfigSubgroup(const PluginID &ID, const RegistryPath &group)=0
PluginManagerInterface::SetSharedConfig
virtual bool SetSharedConfig(const PluginID &ID, const RegistryPath &group, const RegistryPath &key, const wxString &value)=0
PluginManager::Range::first
Iterator first
Definition: PluginManager.h:275
PluginManager::Iterator::mIterator
PluginMap::iterator mIterator
Definition: PluginManager.h:270
PluginManager::mDirty
bool mDirty
Definition: PluginManager.h:351
PluginManagerInterface::GetPrivateConfig
virtual bool GetPrivateConfig(const PluginID &ID, const RegistryPath &group, const RegistryPath &key, wxString &value, const wxString &defval=wxString())=0
PluginTypeAudacityCommand
@ PluginTypeAudacityCommand
Definition: PluginManager.h:36
PluginDescriptor
Definition: PluginManager.h:44
PluginManagerInterface::FindFilesInPathList
virtual void FindFilesInPathList(const wxString &pattern, const FilePaths &pathList, FilePaths &files, bool directories=false)=0
PluginDescriptor::mValid
bool mValid
Definition: PluginManager.h:143
PluginDescriptor::mID
wxString mID
Definition: PluginManager.h:136
Journal::Events::Initialize
void Initialize()
Definition: JournalEvents.cpp:421
PluginDescriptor::mSymbol
ComponentInterfaceSymbol mSymbol
Definition: PluginManager.h:138
PluginTypeNone
@ PluginTypeNone
Definition: PluginManager.h:33
RegistryPath
wxString RegistryPath
Definition: Identifier.h:218
FileConfig
Definition: FileConfig.h:21
PluginManager::mInstance
static std::unique_ptr< PluginManager > mInstance
Definition: PluginManager.h:345
PluginDescriptor::mImporterIdentifier
wxString mImporterIdentifier
Definition: PluginManager.h:157
wxArrayStringEx.h
EffectDefinitionInterface
EffectDefinitionInterface is a ComponentInterface that additionally tracks flag-functions for interac...
Definition: EffectInterface.h:76
PluginTypeExporter
@ PluginTypeExporter
Definition: PluginManager.h:37
key
static const AudacityProject::AttachedObjects::RegisteredFactory key
Definition: CommandManager.cpp:201
PluginManager
PluginManager maintains a list of all plug ins. That covers modules, effects, generators,...
Definition: PluginManager.h:174
PluginManager::AllPlugins
Range AllPlugins()
Definition: PluginManager.h:280
PluginDescriptor::mEnabled
bool mEnabled
Definition: PluginManager.h:142
PluginDescriptor::mEffectRealtime
bool mEffectRealtime
Definition: PluginManager.h:152
PluginManager::PluginsOfType
Range PluginsOfType(int type)
Definition: PluginManager.h:281
ComponentInterface
ComponentInterface provides name / vendor / version functions to identify plugins....
Definition: ComponentInterface.h:62
PluginInterface.h
PluginDescriptor::mEffectAutomatable
bool mEffectAutomatable
Definition: PluginManager.h:153
PluginManagerInterface::GetPrivateConfigSubgroups
virtual bool GetPrivateConfigSubgroups(const PluginID &ID, const RegistryPath &group, RegistryPaths &subgroups)=0
PluginTypeStub
@ PluginTypeStub
Definition: PluginManager.h:34
EffectType
EffectType
Definition: EffectInterface.h:55
PluginManager::Range::end
int end() const
Definition: PluginManager.h:277
PluginDescriptor::mImporterExtensions
FileExtensions mImporterExtensions
Definition: PluginManager.h:158
PluginManagerInterface::GetSharedConfig
virtual bool GetSharedConfig(const PluginID &ID, const RegistryPath &group, const RegistryPath &key, wxString &value, const wxString &defval=wxString())=0
PluginDescriptor::mEffectType
EffectType mEffectType
Definition: PluginManager.h:148
PluginTypeImporter
@ PluginTypeImporter
Definition: PluginManager.h:38
PluginDescriptor::mEffectFamily
wxString mEffectFamily
Definition: PluginManager.h:147