Audacity 3.2.0
PluginProvider.h
Go to the documentation of this file.
1/*!*******************************************************************
2
3 Audacity: A Digital Audio Editor
4
5 @file PluginProvider.h
6 @brief Generalized interface for discovery of plug-ins for one protocol
7
8 Leland Lucius
9
10 Copyright (c) 2014, Audacity Team
11 All rights reserved.
12
13 Redistribution and use in source and binary forms, with or without
14 modification, are permitted provided that the following conditions
15 are met:
16
17 1. Redistributions of source code must retain the above copyright
18 notice, this list of conditions and the following disclaimer.
19
20 2. Redistributions in binary form must reproduce the above copyright
21 notice, this list of conditions and the following disclaimer in the
22 documentation and/or other materials provided with the distribution.
23
24 3. Neither the name of the copyright holder nor the names of its
25 contributors may be used to endorse or promote products derived from
26 this software without specific prior written permission.
27
28 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
29 "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
30 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
31 FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
32 COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
33 INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
34 BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
35 LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
36 CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
37 LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
38 ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
39 POSSIBILITY OF SUCH DAMAGE.
40
41**********************************************************************/
42
43#ifndef __AUDACITY_PLUGINPROVIDER_H__
44#define __AUDACITY_PLUGINPROVIDER_H__
45
46#include <functional>
47#include <memory>
48#include "Identifier.h"
49#include "ComponentInterface.h"
51
52using PluginID = wxString;
53using PluginIDs = wxArrayString;
54// Incomplete type not defined in libraries -- TODO clean that up:
56
57// ============================================================================
58//
59// Don't even think about adding provider types, like effect, importer, etc. in
60// here. The provider interface should not have to change when new types of
61// plug-ins are added to Audacity.
62//
63// In addition a single provider may want to provide multiple plug-in types.
64// ============================================================================
65
66// ============================================================================
73// ============================================================================
74
78class COMPONENTS_API PluginProvider /* not final */
79 : public ComponentInterface
80{
81public:
82
87 //TODO: it may seem reasonable to require providers to perform that check
88 //in DiscoverPluginsAtPath, but some plugin types can safely provide meta
89 //data, which is a good reason to ask to avoid such checks during plugin
90 //discovery...
92 {
93 public:
95 virtual void Validate(ComponentInterface& pluginInterface) = 0;
96 };
97
98 virtual ~PluginProvider();
99
101
102 virtual bool Initialize() = 0;
103
105 virtual void Terminate() = 0;
106
108
113
115
125 virtual const FileExtensions &GetFileExtensions() = 0;
126
128
132 virtual FilePath InstallPath() = 0;
133
135 virtual void AutoRegisterPlugins(PluginManagerInterface & pluginManager) = 0;
136
139
146 virtual PluginPaths
148
150
167 using RegistrationCallback = std::function<
169 virtual unsigned DiscoverPluginsAtPath(
170 const PluginPath & path, TranslatableString &errMsg,
171 const RegistrationCallback &callback )
172 = 0;
173
180 virtual bool CheckPluginExist(const PluginPath& path) const = 0;
181
184 virtual std::unique_ptr<Validator> MakeValidator() const;
185
187
190 virtual std::unique_ptr<ComponentInterface>
191 LoadPlugin(const PluginPath & path) = 0;
192};
193
194// ----------------------------------------------------------------------------
195// Since there may be multiple embedded providers, the entry function will
196// be declared static so as not to interfere with other providers during link.
197// ----------------------------------------------------------------------------
198#define DECLARE_PROVIDER_ENTRY(name) \
199static std::unique_ptr<PluginProvider> name()
200
201// ----------------------------------------------------------------------------
202// This will create a class and instance that will register the provider entry
203// point during Audacity startup. At the appropriate time, the entry point
204// will be called to create the provider instance.
205// ----------------------------------------------------------------------------
206
207// ----------------------------------------------------------------------------
208// Provides the base for embedded provider registration. If used, a Register()
209// method must be supplied explicitly.
210// ----------------------------------------------------------------------------
211
212#define DECLARE_BUILTIN_PROVIDER_BASE(name) \
213class name \
214{ \
215public: \
216 name() {Register();} \
217 ~name() {Unregister();} \
218 void Register(); \
219 void Unregister(); \
220}; \
221static name name ## _instance;
222
223// ----------------------------------------------------------------------------
224// Provides the full embedded provider registration process. Nothing further is
225// required (other than supplying the provider entry point function).
226// ----------------------------------------------------------------------------
227#define DECLARE_BUILTIN_PROVIDER(name) \
228DECLARE_BUILTIN_PROVIDER_BASE(name) \
229void name::Register() \
230{ \
231 RegisterProviderFactory(AudacityModule); \
232} \
233void name::Unregister() \
234{ \
235 UnregisterProviderFactory(AudacityModule); \
236}
237
238#endif // __AUDACITY_MODULEINTERFACE_H__
wxString PluginID
Definition: EffectManager.h:30
std::vector< PluginPath > PluginPaths
Definition: Identifier.h:215
wxString PluginPath
type alias for identifying a Plugin supplied by a module, each module defining its own interpretation...
Definition: Identifier.h:214
wxArrayString PluginIDs
Definition: Menus.h:34
wxString FilePath
Definition: Project.h:20
ComponentInterface provides name / vendor / version functions to identify plugins....
ComponentInterfaceSymbol pairs a persistent string identifier used internally with an optional,...
virtual void Validate(ComponentInterface &pluginInterface)=0
virtual ~PluginProvider()
virtual EffectFamilySymbol GetOptionalFamilySymbol()=0
A symbol identifying the family of plug-ins provided by this.
virtual unsigned DiscoverPluginsAtPath(const PluginPath &path, TranslatableString &errMsg, const RegistrationCallback &callback)=0
virtual void Terminate()=0
Called just prior to deletion to allow releasing any resources.
virtual PluginPaths FindModulePaths(PluginManagerInterface &pluginManager)=0
virtual std::unique_ptr< ComponentInterface > LoadPlugin(const PluginPath &path)=0
Load the plug-in at a path reported by DiscoverPluginsAtPath.
virtual void AutoRegisterPlugins(PluginManagerInterface &pluginManager)=0
Called so that a provider of a static set of plug-ins can register them.
virtual const FileExtensions & GetFileExtensions()=0
File types associated with this protocol.
std::function< const PluginID &(PluginProvider *, ComponentInterface *) > RegistrationCallback
Further expand a path reported by FindModulePaths.
virtual bool Initialize()=0
Called immediately after creation. Let provider initialize.
virtual bool CheckPluginExist(const PluginPath &path) const =0
Performs plugin/module existence check, still plugin may fail to load. Implementation should avoid lo...
virtual FilePath InstallPath()=0
Where plug-in files should be copied to install them.
Holds a msgid for the translation catalog; may also bind format arguments.
Extend wxArrayString with move operations and construction and insertion fromstd::initializer_list.