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 // ============================================================================ 61 /// 62 /// ModuleInterface is a generic dll or so interface for Audacity, that is 63 /// used for plug ins. Classes derived from it can handle more specific plug 64 /// in types. 65 /// 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 84 virtual EffectFamilySymbol GetOptionalFamilySymbol() = 0; 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. 121 using RegistrationCallback = 122 std::function< 123 const PluginID &(ModuleInterface *, ComponentInterface *) >; 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__ 183