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 virtual ~PluginProvider();
83
85
86 virtual bool Initialize() = 0;
87
89 virtual void Terminate() = 0;
90
92
97
99
109 virtual const FileExtensions &GetFileExtensions() = 0;
110
112
116 virtual FilePath InstallPath() = 0;
117
119 virtual void AutoRegisterPlugins(PluginManagerInterface & pluginManager) = 0;
120
123
130 virtual PluginPaths
132
134
151 using RegistrationCallback = std::function<
153 virtual unsigned DiscoverPluginsAtPath(
154 const PluginPath & path, TranslatableString &errMsg,
155 const RegistrationCallback &callback )
156 = 0;
157
164 virtual bool CheckPluginExist(const PluginPath& path) const = 0;
165
167
170 virtual std::unique_ptr<ComponentInterface>
171 LoadPlugin(const PluginPath & path) = 0;
172};
173
174// ----------------------------------------------------------------------------
175// Since there may be multiple embedded providers, the entry function will
176// be declared static so as not to interfere with other providers during link.
177// ----------------------------------------------------------------------------
178#define DECLARE_PROVIDER_ENTRY(name) \
179static std::unique_ptr<PluginProvider> name()
180
181// ----------------------------------------------------------------------------
182// This will create a class and instance that will register the provider entry
183// point during Audacity startup. At the appropriate time, the entry point
184// will be called to create the provider instance.
185// ----------------------------------------------------------------------------
186
187// ----------------------------------------------------------------------------
188// Provides the base for embedded provider registration. If used, a Register()
189// method must be supplied explicitly.
190// ----------------------------------------------------------------------------
191
192#define DECLARE_BUILTIN_PROVIDER_BASE(name) \
193class name \
194{ \
195public: \
196 name() {Register();} \
197 ~name() {Unregister();} \
198 void Register(); \
199 void Unregister(); \
200}; \
201static name name ## _instance;
202
203// ----------------------------------------------------------------------------
204// Provides the full embedded provider registration process. Nothing further is
205// required (other than supplying the provider entry point function).
206// ----------------------------------------------------------------------------
207#define DECLARE_BUILTIN_PROVIDER(name) \
208DECLARE_BUILTIN_PROVIDER_BASE(name) \
209void name::Register() \
210{ \
211 RegisterProviderFactory(AudacityModule); \
212} \
213void name::Unregister() \
214{ \
215 UnregisterProviderFactory(AudacityModule); \
216}
217
218#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 ~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.