ImportPlugin.h

Go to the documentation of this file.

/**********************************************************************
 
  Audacity: A Digital Audio Editor
 
  ImportPlugin.h
 
  Joshua Haberman
  Leland Lucius
 
*******************************************************************//****************************************************************//****************************************************************//****************************************************************//*******************************************************************/
 
#ifndef __AUDACITY_IMPORTER__
#define __AUDACITY_IMPORTER__
 
#include "AcidizerTags.h"
#include "Identifier.h"
#include "Internat.h"
#include "wxArrayStringEx.h"
#include <memory>
#include <optional>
 
class AudacityProject;
class WaveTrackFactory;
class Track;
class TrackList;
class TranslatableString;
class Tags;
 
class ImportFileHandle;
 
class ImportProgressListener;
 
class IMPORT_EXPORT_API ImportPlugin /* not final */
{
public:
 
   // Get unique string ID of this plugin, usually it corresponds
   // to the underlying library, i.e. "libsndfile", "libflac", "libav"
   // These MUST NOT change across Audacity versions (but NEW IDs can
   // be added).
   virtual wxString GetPluginStringID() = 0;
 
   // Get a description of the file type this importer can import.
   // Examples: "Ogg Vorbis", "MP3", "Uncompressed PCM"
   virtual TranslatableString GetPluginFormatDescription() = 0;
 
   // Get a list of extensions this plugin expects to be able to
   // import.  If a filename matches any of these extensions,
   // this importer will get first dibs on importing it.
   virtual FileExtensions GetSupportedExtensions();
 
 
   virtual TranslatableString FailureHint() const;
 
   bool SupportsExtension(const FileExtension &extension);
 
   // Open the given file, returning true if it is in a recognized
   // format, false otherwise.  This puts the importer into the open
   // state.
   virtual std::unique_ptr<ImportFileHandle> Open(
      const FilePath &Filename, AudacityProject*) = 0;
 
   virtual ~ImportPlugin();
 
protected:
 
   ImportPlugin(FileExtensions supportedExtensions);
 
   const FileExtensions mExtensions;
};
 
 
class WaveTrack;
using TrackHolders = std::vector<std::shared_ptr<Track>>;
 
class IMPORT_EXPORT_API ImportFileHandle /* not final */
{
public:
 
   using ByteCount = unsigned long long;
 
   virtual ~ImportFileHandle();
 
   virtual FilePath GetFilename() const = 0;
 
   virtual TranslatableString GetErrorMessage() const;
 
   // This is similar to GetPluginFormatDescription, but if possible the
   // importer will return a more specific description of the
   // specific file that is open.
   virtual TranslatableString GetFileDescription() = 0;
 
   // Return an estimate of how many bytes the file will occupy once
   // imported.  In principle this may exceed main memory, so don't use
   // size_t.
   virtual ByteCount GetFileUncompressedBytes() = 0;
 
   // Return number of elements in stream list
   virtual wxInt32 GetStreamCount() = 0;
 
   // Return stream descriptions list, before Import() is called
   virtual const TranslatableStrings &GetStreamInfo() = 0;
 
   // Set stream "import/don't import" flag, before Import() is called
   virtual void SetStreamUsage(wxInt32 StreamID, bool Use) = 0;
 
   // do the actual import, creating whatever tracks are necessary with
   // the WaveTrackFactory and calling the progress callback every iteration
   // through the importing loop
   // The given Tags and AcidizerTags structures may also be modified.
   // In case of errors or exceptions, it is not necessary to leave outTracks,
   // tags or acidTags unmodified. If resulting outTracks is not empty, then
   // each member of it must be a nonempty vector.
   virtual void Import(
      ImportProgressListener& progressListener, WaveTrackFactory* trackFactory,
      TrackHolders& outTracks, Tags* tags,
      std::optional<LibFileFormats::AcidizerTags>& acidTags) = 0;
 
   virtual void Cancel() = 0;
 
   virtual void Stop() = 0;
};
 
class IMPORT_EXPORT_API ImportFileHandleEx : public ImportFileHandle
{
   FilePath mFilename;
   bool mCancelled{false};
   bool mStopped{false};
public:
   ImportFileHandleEx(const FilePath& filename);
 
   FilePath GetFilename() const override;
   void Cancel() override;
   void Stop() override;
 
protected:
   void BeginImport();
   bool IsCancelled() const noexcept;
   bool IsStopped() const noexcept;
};
 
class IMPORT_EXPORT_API UnusableImportPlugin
{
public:
   UnusableImportPlugin(
      const TranslatableString &formatName, FileExtensions extensions):
      mFormatName(formatName),
      mExtensions( std::move( extensions ) )
   {
   }
 
   TranslatableString GetPluginFormatDescription()
   {
      return mFormatName;
   }
 
   bool SupportsExtension(const FileExtension &extension)
   {
      return mExtensions.Index(extension, false) != wxNOT_FOUND;
   }
 
private:
   TranslatableString mFormatName;
   const FileExtensions mExtensions;
};
 
#endif