PluginProvider.h

Go to the documentation of this file.

/*!*******************************************************************
 
   Audacity: A Digital Audio Editor
 
   @file PluginProvider.h
   @brief Generalized interface for discovery of plug-ins for one protocol
 
   Leland Lucius
 
   Copyright (c) 2014, Audacity Team 
   All rights reserved.
 
   Redistribution and use in source and binary forms, with or without
   modification, are permitted provided that the following conditions
   are met:
 
   1. Redistributions of source code must retain the above copyright
   notice, this list of conditions and the following disclaimer.
 
   2. Redistributions in binary form must reproduce the above copyright
   notice, this list of conditions and the following disclaimer in the
   documentation and/or other materials provided with the distribution.
 
   3. Neither the name of the copyright holder nor the names of its
   contributors may be used to endorse or promote products derived from
   this software without specific prior written permission.
 
   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
   "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
   LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
   FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
   COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
   INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
   BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
   LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
   CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
   LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
   ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
   POSSIBILITY OF SUCH DAMAGE.
   
**********************************************************************/
 
#ifndef __AUDACITY_PLUGINPROVIDER_H__
#define __AUDACITY_PLUGINPROVIDER_H__
 
#include <functional>
#include <memory>
#include "Identifier.h"
#include "ComponentInterface.h"
#include "ComponentInterfaceSymbol.h"
 
using PluginID = wxString;
using PluginIDs = wxArrayString;
// Incomplete type not defined in libraries -- TODO clean that up:
class PluginManagerInterface;
 
// ============================================================================
//
// Don't even think about adding provider types, like effect, importer, etc. in
// here.  The provider interface should not have to change when new types of
// plug-ins are added to Audacity.
//
// In addition a single provider may want to provide multiple plug-in types.
// ============================================================================
 
// ============================================================================
// ============================================================================
 
class COMPONENTS_API PluginProvider  /* not final */
   : public ComponentInterface
{
public:
 
   //TODO: it may seem reasonable to require providers to perform that check
   //in DiscoverPluginsAtPath, but some plugin types can safely provide meta
   //data, which is a good reason to ask to avoid such checks during plugin
   //discovery...
   class COMPONENTS_API Validator
   {
   public:
      virtual void Validate(ComponentInterface& pluginInterface) = 0;
      virtual ~Validator();
   };
 
   virtual ~PluginProvider();
 
 
   virtual bool Initialize() = 0;
 
   virtual void Terminate() = 0;
 
 
   virtual EffectFamilySymbol GetOptionalFamilySymbol() = 0;
 
 
   virtual const FileExtensions &GetFileExtensions() = 0;
 
 
   virtual FilePath InstallPath() = 0;
 
   virtual void AutoRegisterPlugins(PluginManagerInterface & pluginManager) = 0;
 
   virtual bool SupportsCustomModulePaths() const;
 
 
   virtual PluginPaths
      FindModulePaths(PluginManagerInterface & pluginManager) = 0;
 
 
   using RegistrationCallback = std::function<
      const PluginID &(PluginProvider *, ComponentInterface *) >;
   virtual unsigned DiscoverPluginsAtPath(
      const PluginPath & path, TranslatableString &errMsg,
      const RegistrationCallback &callback )
         = 0;
 
   virtual bool CheckPluginExist(const PluginPath& path) const = 0;
 
   virtual std::unique_ptr<Validator> MakeValidator() const;
 
 
   virtual std::unique_ptr<ComponentInterface>
      LoadPlugin(const PluginPath & path) = 0;
};
 
// ----------------------------------------------------------------------------
// Since there may be multiple embedded providers, the entry function will
// be declared static so as not to interfere with other providers during link.
// ----------------------------------------------------------------------------
#define DECLARE_PROVIDER_ENTRY(name)                  \
static std::unique_ptr<PluginProvider> name()
 
// ----------------------------------------------------------------------------
// This will create a class and instance that will register the provider entry
// point during Audacity startup.  At the appropriate time, the entry point
// will be called to create the provider instance.
// ----------------------------------------------------------------------------
 
// ----------------------------------------------------------------------------
// Provides the base for embedded provider registration.  If used, a Register()
// method must be supplied explicitly.
// ----------------------------------------------------------------------------
 
#define DECLARE_BUILTIN_PROVIDER_BASE(name)           \
class name                                            \
{                                                     \
public:                                               \
   name() {Register();}                               \
   ~name() {Unregister();}                            \
   void Register();                                   \
   void Unregister();                                 \
};                                                    \
static name name ## _instance;
 
// ----------------------------------------------------------------------------
// Provides the full embedded provider registration process.  Nothing further is
// required (other than supplying the provider entry point function).
// ----------------------------------------------------------------------------
#define DECLARE_BUILTIN_PROVIDER(name)                \
DECLARE_BUILTIN_PROVIDER_BASE(name)                   \
void name::Register()                                 \
{                                                     \
   RegisterProviderFactory(AudacityModule);                  \
}                                                     \
void name::Unregister()                               \
{                                                     \
   UnregisterProviderFactory(AudacityModule);                \
}
 
#endif // __AUDACITY_MODULEINTERFACE_H__