Audacity  3.0.3
ModuleInterface.h
Go to the documentation of this file.
1 /**********************************************************************
2 
3  Audacity: A Digital Audio Editor
4 
5  ModuleInterface.h
6 
7  Leland Lucius
8 
9  Copyright (c) 2014, Audacity Team
10  All rights reserved.
11 
12  Redistribution and use in source and binary forms, with or without
13  modification, are permitted provided that the following conditions
14  are met:
15 
16  1. Redistributions of source code must retain the above copyright
17  notice, this list of conditions and the following disclaimer.
18 
19  2. Redistributions in binary form must reproduce the above copyright
20  notice, this list of conditions and the following disclaimer in the
21  documentation and/or other materials provided with the distribution.
22 
23  3. Neither the name of the copyright holder nor the names of its
24  contributors may be used to endorse or promote products derived from
25  this software without specific prior written permission.
26 
27  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
28  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
29  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
30  FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
31  COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
32  INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
33  BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
34  LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
35  CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
36  LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
37  ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
38  POSSIBILITY OF SUCH DAMAGE.
39 
40 **********************************************************************/
41 
42 #ifndef __AUDACITY_MODULEINTERFACE_H__
43 #define __AUDACITY_MODULEINTERFACE_H__
44 
45 #include <functional>
46 #include <memory>
47 #include "Identifier.h"
48 #include "ComponentInterface.h"
49 #include "PluginInterface.h"
50 
51 // ============================================================================
52 //
53 // Don't even think about adding module types, like effect, importer, etc. in
54 // here. The module interface should not have to change when new types of
55 // plugins are added to Audacity.
56 //
57 // In addition a single module may want to provide multiple plugin types.
58 // ============================================================================
59 
60 // ============================================================================
66 // ============================================================================
67 
68 class COMPONENTS_API ModuleInterface /* not final */
69  : public ComponentInterface
70 {
71 public:
72  virtual ~ModuleInterface();
73 
74  // Called immediately after creation to give the instance a chance to
75  // initialize. Return "true" if initialziation was successful.
76  virtual bool Initialize() = 0;
77 
78  // Called just prior to deletion to allow releasing any resources.
79  virtual void Terminate() = 0;
80 
81  // A symbol identifying the family of plugin provided by this module;
82  // if it is not empty, then the family as a whole can be enabled or
83  // disabled by the user in Preferences
85 
86  // "Paths" returned by FindPluginPaths() and passed back to
87  // DiscoverPluginsAtPath() have module-specific meaning.
88  // They are not necessarily file system paths to existent files that
89  // could be placed in any folder and queried for
90  // plugin information.
91  // This function returns nonempty only when that is the case, and lists
92  // the possible extensions of such files (an empty string in a nonempty
93  // array means any file is a candidate).
94  virtual const FileExtensions &GetFileExtensions() = 0;
95 
96  // Returns empty, or else, where to copy a plug-in file or bundle.
97  // Drag-and-drop is supported only if GetFileExtensions() returns nonempty and
98  // this function returns nonempty.
99  virtual FilePath InstallPath() = 0;
100 
101  // Modules providing a single or static set of plugins may use
102  // AutoRegisterPlugins() to register those plugins.
103  virtual bool AutoRegisterPlugins(PluginManagerInterface & pluginManager) = 0;
104 
105  // For modules providing an interface to other dynamically loaded plugins,
106  // the module returns a list of path names that will be presented to the
107  // user as "New" for enablement.
108  virtual PluginPaths FindPluginPaths(PluginManagerInterface & pluginManager) = 0;
109 
110  // Once the user selects desired paths from FindPluginPaths(),
111  // a call to DiscoverPluginsAtPath()
112  // will be made to request registration of one or more plugins. If the module must create
113  // an instance of the plugin to register it, then the instance should be deleted
114  // after registration.
115  // May discover more than one plug-in at the path, and
116  // may call-back with paths not equal to path (perhaps appending
117  // other information to it).
118  // Error message does not need to mention the path and may be nonempty
119  // even if some plugins are also discovered successfully.
120  // Return value is the number of plugins found.
122  std::function<
124  virtual unsigned DiscoverPluginsAtPath(
125  const PluginPath & path, TranslatableString &errMsg,
126  const RegistrationCallback &callback )
127  = 0;
128 
129  // For modules providing an interface to other dynamically loaded plugins,
130  // the module returns true if the plugin is still valid, otherwise false.
131  virtual bool IsPluginValid(const PluginPath & path, bool bFast) = 0;
132 
133  // When appropriate, CreateInstance() will be called to instantiate the plugin.
134  virtual std::unique_ptr<ComponentInterface>
135  CreateInstance(const PluginPath & path) = 0;
136 };
137 
138 // ----------------------------------------------------------------------------
139 // Since there may be multiple embedded modules, the module entry function will
140 // be declared static so as not to interfere with other modules during link.
141 // ----------------------------------------------------------------------------
142 #define DECLARE_MODULE_ENTRY(name) \
143 static ModuleInterface * name()
144 
145 // ----------------------------------------------------------------------------
146 // This will create a class and instance that will register the module entry
147 // point during Audacity startup. At the appropriate time, the entry point
148 // will be called to create the module instance.
149 // ----------------------------------------------------------------------------
150 
151 // ----------------------------------------------------------------------------
152 // Provides the base for embedded module registration. If used, a Register()
153 // method must be supplied explicitly.
154 // ----------------------------------------------------------------------------
155 
156 #define DECLARE_BUILTIN_MODULE_BASE(name) \
157 class name \
158 { \
159 public: \
160  name() {Register();} \
161  ~name() {Unregister();} \
162  void Register(); \
163  void Unregister(); \
164 }; \
165 static name name ## _instance;
166 
167 // ----------------------------------------------------------------------------
168 // Provides the full embedded module registration process. Nothing further is
169 // required (other than supplying the module entry point function).
170 // ----------------------------------------------------------------------------
171 #define DECLARE_BUILTIN_MODULE(name) \
172 DECLARE_BUILTIN_MODULE_BASE(name) \
173 void name::Register() \
174 { \
175  RegisterProvider(AudacityModule); \
176 } \
177 void name::Unregister() \
178 { \
179  UnregisterProvider(AudacityModule); \
180 }
181 
182 #endif // __AUDACITY_MODULEINTERFACE_H__
ModuleInterface::AutoRegisterPlugins
virtual bool AutoRegisterPlugins(PluginManagerInterface &pluginManager)=0
TranslatableString
Holds a msgid for the translation catalog; may also bind format arguments.
Definition: TranslatableString.h:32
PluginPath
wxString PluginPath
type alias for identifying a Plugin supplied by a module, each module defining its own interpretation...
Definition: Identifier.h:214
ModuleInterface::~ModuleInterface
virtual ~ModuleInterface()
ModuleInterface::InstallPath
virtual FilePath InstallPath()=0
wxArrayStringEx
Extend wxArrayString with move operations and construction and insertion fromstd::initializer_list.
Definition: wxArrayStringEx.h:18
ComponentInterfaceSymbol
ComponentInterfaceSymbol pairs a persistent string identifier used internally with an optional,...
Definition: ComponentInterfaceSymbol.h:27
ModuleInterface
Definition: ModuleInterface.h:70
ModuleInterface::FindPluginPaths
virtual PluginPaths FindPluginPaths(PluginManagerInterface &pluginManager)=0
ModuleInterface::CreateInstance
virtual std::unique_ptr< ComponentInterface > CreateInstance(const PluginPath &path)=0
ComponentInterface.h
FilePath
wxString FilePath
Definition: Project.h:20
PluginManagerInterface
Definition: PluginInterface.h:55
ModuleInterface::Initialize
virtual bool Initialize()=0
PluginID
wxString PluginID
Definition: EffectManager.h:30
Identifier.h
PluginPaths
std::vector< PluginPath > PluginPaths
Definition: Identifier.h:215
ModuleInterface::GetOptionalFamilySymbol
virtual EffectFamilySymbol GetOptionalFamilySymbol()=0
ComponentInterface
ComponentInterface provides name / vendor / version functions to identify plugins....
Definition: ComponentInterface.h:62
PluginInterface.h
ModuleInterface::DiscoverPluginsAtPath
virtual unsigned DiscoverPluginsAtPath(const PluginPath &path, TranslatableString &errMsg, const RegistrationCallback &callback)=0
ModuleInterface::RegistrationCallback
std::function< const PluginID &(ModuleInterface *, ComponentInterface *) > RegistrationCallback
Definition: ModuleInterface.h:123
ModuleInterface::Terminate
virtual void Terminate()=0
ModuleInterface::GetFileExtensions
virtual const FileExtensions & GetFileExtensions()=0
ModuleInterface::IsPluginValid
virtual bool IsPluginValid(const PluginPath &path, bool bFast)=0