source/includes/vst3sdk/pluginterfaces/base/ipluginbase.h

   1 //-----------------------------------------------------------------------------
   2 // Project     : SDK Core
   3 //
   4 // Category    : SDK Core Interfaces
   5 // Filename    : pluginterfaces/base/ipluginbase.h
   6 // Created by  : Steinberg, 01/2004
   7 // Description : Basic Plug-in Interfaces
   8 //
   9 //-----------------------------------------------------------------------------
  10 // This file is part of a Steinberg SDK. It is subject to the license terms
  11 // in the LICENSE file found in the top-level directory of this distribution
  12 // and at www.steinberg.net/sdklicenses.
  13 // No part of the SDK, including this file, may be copied, modified, propagated,
  14 // or distributed except according to the terms contained in the LICENSE file.
  15 //-----------------------------------------------------------------------------
  16
  17 #pragma once
  18
  19 #include "funknown.h"
  20 #include "fstrdefs.h"
  21
  22 namespace Steinberg {
  23
  24 //------------------------------------------------------------------------
  25 /**  Basic interface to a plug-in component: IPluginBase
  26 \ingroup pluginBase
  27 - [plug imp]
  28 - initialize/terminate the plug-in component
  29
  30 The host uses this interface to initialize and to terminate the plug-in component.
  31 The context that is passed to the initialize method contains any interface to the
  32 host that the plug-in will need to work. These interfaces can vary from category to category.
  33 A list of supported host context interfaces should be included in the documentation
  34 of a specific category.
  35 */
  36 class IPluginBase: public FUnknown
  37 {
  38 public:
  39 //------------------------------------------------------------------------
  40         /** The host passes a number of interfaces as context to initialize the plug-in class.
  41                 @note Extensive memory allocations etc. should be performed in this method rather than in the class' constructor!
  42                 If the method does NOT return kResultOk, the object is released immediately. In this case terminate is not called! */
  43         virtual tresult PLUGIN_API initialize (FUnknown* context) = 0;
  44
  45         /** This function is called before the plug-in is unloaded and can be used for
  46             cleanups. You have to release all references to any host application interfaces. */
  47         virtual tresult PLUGIN_API terminate () = 0;
  48
  49 //------------------------------------------------------------------------
  50         static const FUID iid;
  51 };
  52
  53 DECLARE_CLASS_IID (IPluginBase, 0x22888DDB, 0x156E45AE, 0x8358B348, 0x08190625)
  54
  55
  56 //------------------------------------------------------------------------
  57 /** Basic Information about the class factory of the plug-in.
  58 \ingroup pluginBase
  59 */
  60 struct PFactoryInfo
  61 {
  62 //------------------------------------------------------------------------
  63         enum FactoryFlags
  64         {
  65                 kNoFlags                                        = 0,            ///< Nothing
  66                 kClassesDiscardable                     = 1 << 0,       ///< The number of exported classes can change each time the Module is loaded. If this flag is set, the host does not cache class information. This leads to a longer startup time because the host always has to load the Module to get the current class information.
  67                 kLicenseCheck                           = 1 << 1,       ///< Class IDs of components are interpreted as Syncrosoft-License (LICENCE_UID). Loaded in a Steinberg host, the module will not be loaded when the license is not valid
  68                 kComponentNonDiscardable        = 1 << 3,       ///< Component will not be unloaded until process exit
  69                 kUnicode                    = 1 << 4    ///< Components have entirely unicode encoded strings. (True for VST 3 plug-ins so far)
  70         };
  71
  72         enum
  73         {
  74                 kURLSize = 256,
  75                 kEmailSize = 128,
  76                 kNameSize = 64
  77         };
  78
  79 //------------------------------------------------------------------------
  80         char8 vendor[kNameSize];                ///< e.g. "Steinberg Media Technologies"
  81         char8 url[kURLSize];                    ///< e.g. "http://www.steinberg.de"
  82         char8 email[kEmailSize];                ///< e.g. "info@steinberg.de"
  83         int32 flags;                            ///< (see above)
  84 //------------------------------------------------------------------------
  85         PFactoryInfo (const char8* _vendor, const char8* _url, const char8* _email, int32 _flags)
  86         {
  87                 strncpy8 (vendor, _vendor, kNameSize);
  88                 strncpy8 (url, _url, kURLSize);
  89                 strncpy8 (email, _email, kEmailSize);
  90                 flags = _flags;
  91 #ifdef UNICODE
  92                 flags |= kUnicode;
  93 #endif
  94         }
  95 #if SMTG_CPP11
  96         constexpr PFactoryInfo () : vendor (), url (), email (), flags () {}
  97 #else
  98         PFactoryInfo () { memset (this, 0, sizeof (PFactoryInfo)); }
  99 #endif
 100 };
 101
 102 //------------------------------------------------------------------------
 103 /**  Basic Information about a class provided by the plug-in.
 104 \ingroup pluginBase
 105 */
 106 struct PClassInfo
 107 {
 108 //------------------------------------------------------------------------
 109         enum ClassCardinality
 110         {
 111                 kManyInstances = 0x7FFFFFFF
 112         };
 113
 114         enum
 115         {
 116                 kCategorySize = 32,
 117                 kNameSize = 64
 118         };
 119 //------------------------------------------------------------------------
 120         TUID cid;                       ///< Class ID 16 Byte class GUID
 121         int32 cardinality;              ///< cardinality of the class, set to kManyInstances (see \ref ClassCardinality)
 122         char8 category[kCategorySize];  ///< class category, host uses this to categorize interfaces
 123         char8 name[kNameSize];          ///< class name, visible to the user
 124 //------------------------------------------------------------------------
 125
 126         PClassInfo (const TUID _cid, int32 _cardinality, const char8* _category, const char8* _name)
 127         {
 128                 memset (this, 0, sizeof (PClassInfo));
 129                 memcpy (cid, _cid, sizeof (TUID));
 130                 if (_category)
 131                         strncpy8 (category, _category, kCategorySize);
 132                 if (_name)
 133                         strncpy8 (name, _name, kNameSize);
 134                 cardinality = _cardinality;
 135         }
 136 #if SMTG_CPP11
 137         constexpr PClassInfo () : cid (), cardinality (), category (), name () {}
 138 #else
 139         PClassInfo () { memset (this, 0, sizeof (PClassInfo)); }
 140 #endif
 141 };
 142
 143 //------------------------------------------------------------------------
 144 //  IPluginFactory interface declaration
 145 //------------------------------------------------------------------------
 146 /**     Class factory that any plug-in defines for creating class instances: IPluginFactory
 147 \ingroup pluginBase
 148 - [plug imp]
 149
 150 From the host's point of view a plug-in module is a factory which can create
 151 a certain kind of object(s). The interface IPluginFactory provides methods
 152 to get information about the classes exported by the plug-in and a
 153 mechanism to create instances of these classes (that usually define the IPluginBase interface).
 154
 155 <b> An implementation is provided in public.sdk/source/common/pluginfactory.cpp </b>
 156 \see GetPluginFactory
 157 */
 158 class IPluginFactory : public FUnknown
 159 {
 160 public:
 161 //------------------------------------------------------------------------
 162         /** Fill a PFactoryInfo structure with information about the plug-in vendor. */
 163         virtual tresult PLUGIN_API getFactoryInfo (PFactoryInfo* info) = 0;
 164
 165         /** Returns the number of exported classes by this factory.
 166         If you are using the CPluginFactory implementation provided by the SDK, it returns the number of classes you registered with CPluginFactory::registerClass. */
 167         virtual int32 PLUGIN_API countClasses () = 0;
 168
 169         /** Fill a PClassInfo structure with information about the class at the specified index. */
 170         virtual tresult PLUGIN_API getClassInfo (int32 index, PClassInfo* info) = 0;
 171
 172         /** Create a new class instance. */
 173         virtual tresult PLUGIN_API createInstance (FIDString cid, FIDString _iid, void** obj) = 0;
 174
 175 //------------------------------------------------------------------------
 176         static const FUID iid;
 177 };
 178
 179 DECLARE_CLASS_IID (IPluginFactory, 0x7A4D811C, 0x52114A1F, 0xAED9D2EE, 0x0B43BF9F)
 180
 181
 182 //------------------------------------------------------------------------
 183 /**  Version 2 of Basic Information about a class provided by the plug-in.
 184 \ingroup pluginBase
 185 */
 186 struct PClassInfo2
 187 {
 188 //------------------------------------------------------------------------
 189         TUID cid;                                                                       ///< Class ID 16 Byte class GUID
 190         int32 cardinality;                                                      ///< cardinality of the class, set to kManyInstances (see \ref PClassInfo::ClassCardinality)
 191         char8 category[PClassInfo::kCategorySize];      ///< class category, host uses this to categorize interfaces
 192         char8 name[PClassInfo::kNameSize];                      ///< class name, visible to the user
 193
 194         enum {
 195                 kVendorSize = 64,
 196                 kVersionSize = 64,
 197                 kSubCategoriesSize = 128
 198         };
 199
 200         uint32 classFlags;                              ///< flags used for a specific category, must be defined where category is defined
 201         char8 subCategories[kSubCategoriesSize];        ///< module specific subcategories, can be more than one, logically added by the \c OR operator
 202         char8 vendor[kVendorSize];              ///< overwrite vendor information from factory info
 203         char8 version[kVersionSize];    ///< Version string (e.g. "1.0.0.512" with Major.Minor.Subversion.Build)
 204         char8 sdkVersion[kVersionSize]; ///< SDK version used to build this class (e.g. "VST 3.0")
 205
 206 //------------------------------------------------------------------------
 207
 208         PClassInfo2 (const TUID _cid, int32 _cardinality, const char8* _category, const char8* _name,
 209                 int32 _classFlags, const char8* _subCategories, const char8* _vendor, const char8* _version,
 210                 const char8* _sdkVersion)
 211         {
 212                 memset (this, 0, sizeof (PClassInfo2));
 213                 memcpy (cid, _cid, sizeof (TUID));
 214                 cardinality = _cardinality;
 215                 if (_category)
 216                         strncpy8 (category, _category, PClassInfo::kCategorySize);
 217                 if (_name)
 218                         strncpy8 (name, _name, PClassInfo::kNameSize);
 219                 classFlags = static_cast<uint32> (_classFlags);
 220                 if (_subCategories)
 221                         strncpy8 (subCategories, _subCategories, kSubCategoriesSize);
 222                 if (_vendor)
 223                         strncpy8 (vendor, _vendor, kVendorSize);
 224                 if (_version)
 225                         strncpy8 (version, _version, kVersionSize);
 226                 if (_sdkVersion)
 227                         strncpy8 (sdkVersion, _sdkVersion, kVersionSize);
 228         }
 229 #if SMTG_CPP11
 230         constexpr PClassInfo2 ()
 231         : cid ()
 232         , cardinality ()
 233         , category ()
 234         , name ()
 235         , classFlags ()
 236         , subCategories ()
 237         , vendor ()
 238         , version ()
 239         , sdkVersion ()
 240         {
 241         }
 242 #else
 243         PClassInfo2 () { memset (this, 0, sizeof (PClassInfo2)); }
 244 #endif
 245 };
 246
 247 //------------------------------------------------------------------------
 248 //  IPluginFactory2 interface declaration
 249 //------------------------------------------------------------------------
 250 /**     Version 2 of class factory supporting PClassInfo2: IPluginFactory2
 251 \ingroup pluginBase
 252 \copydoc IPluginFactory
 253 */
 254 class IPluginFactory2 : public IPluginFactory
 255 {
 256 public:
 257 //------------------------------------------------------------------------
 258         /** Returns the class info (version 2) for a given index. */
 259         virtual tresult PLUGIN_API getClassInfo2 (int32 index, PClassInfo2* info) = 0;
 260
 261 //------------------------------------------------------------------------
 262         static const FUID iid;
 263 };
 264 DECLARE_CLASS_IID (IPluginFactory2, 0x0007B650, 0xF24B4C0B, 0xA464EDB9, 0xF00B2ABB)
 265
 266
 267 //------------------------------------------------------------------------
 268 /** Unicode Version of Basic Information about a class provided by the plug-in
 269 */
 270 struct PClassInfoW
 271 {
 272 //------------------------------------------------------------------------
 273         TUID cid;                                                       ///< see \ref PClassInfo
 274         int32 cardinality;                                      ///< see \ref PClassInfo
 275         char8 category[PClassInfo::kCategorySize];      ///< see \ref PClassInfo
 276         char16 name[PClassInfo::kNameSize];     ///< see \ref PClassInfo
 277
 278         enum {
 279                 kVendorSize = 64,
 280                 kVersionSize = 64,
 281                 kSubCategoriesSize = 128
 282         };
 283
 284         uint32 classFlags;                                      ///< flags used for a specific category, must be defined where category is defined
 285         char8 subCategories[kSubCategoriesSize];///< module specific subcategories, can be more than one, logically added by the \c OR operator
 286         char16 vendor[kVendorSize];                     ///< overwrite vendor information from factory info
 287         char16 version[kVersionSize];           ///< Version string (e.g. "1.0.0.512" with Major.Minor.Subversion.Build)
 288         char16 sdkVersion[kVersionSize];        ///< SDK version used to build this class (e.g. "VST 3.0")
 289
 290 //------------------------------------------------------------------------
 291         PClassInfoW (const TUID _cid, int32 _cardinality, const char8* _category, const char16* _name,
 292                 int32 _classFlags, const char8* _subCategories, const char16* _vendor, const char16* _version,
 293                 const char16* _sdkVersion)
 294         {
 295                 memset (this, 0, sizeof (PClassInfoW));
 296                 memcpy (cid, _cid, sizeof (TUID));
 297                 cardinality = _cardinality;
 298                 if (_category)
 299                         strncpy8 (category, _category, PClassInfo::kCategorySize);
 300                 if (_name)
 301                         strncpy16 (name, _name, PClassInfo::kNameSize);
 302                 classFlags = static_cast<uint32> (_classFlags);
 303                 if (_subCategories)
 304                         strncpy8 (subCategories, _subCategories, kSubCategoriesSize);
 305                 if (_vendor)
 306                         strncpy16 (vendor, _vendor, kVendorSize);
 307                 if (_version)
 308                         strncpy16 (version, _version, kVersionSize);
 309                 if (_sdkVersion)
 310                         strncpy16 (sdkVersion, _sdkVersion, kVersionSize);
 311         }
 312 #if SMTG_CPP11
 313         constexpr PClassInfoW ()
 314         : cid ()
 315         , cardinality ()
 316         , category ()
 317         , name ()
 318         , classFlags ()
 319         , subCategories ()
 320         , vendor ()
 321         , version ()
 322         , sdkVersion ()
 323         {
 324         }
 325 #else
 326         PClassInfoW () { memset (this, 0, sizeof (PClassInfoW)); }
 327 #endif
 328
 329         void fromAscii (const PClassInfo2& ci2)
 330         {
 331                 memcpy (cid, ci2.cid, sizeof (TUID));
 332                 cardinality = ci2.cardinality;
 333                 strncpy8 (category, ci2.category, PClassInfo::kCategorySize);
 334                 str8ToStr16 (name, ci2.name, PClassInfo::kNameSize);
 335                 classFlags = ci2.classFlags;
 336                 strncpy8 (subCategories, ci2.subCategories, kSubCategoriesSize);
 337
 338                 str8ToStr16 (vendor, ci2.vendor, kVendorSize);
 339                 str8ToStr16 (version, ci2.version, kVersionSize);
 340                 str8ToStr16 (sdkVersion, ci2.sdkVersion, kVersionSize);
 341         }
 342 };
 343
 344 //------------------------------------------------------------------------
 345 //  IPluginFactory3 interface declaration
 346 //------------------------------------------------------------------------
 347 /**     Version 3 of class factory supporting PClassInfoW: IPluginFactory3
 348 \ingroup pluginBase
 349 \copydoc IPluginFactory
 350 */
 351 class IPluginFactory3 : public IPluginFactory2
 352 {
 353 public:
 354 //------------------------------------------------------------------------
 355         /** Returns the unicode class info for a given index. */
 356         virtual tresult PLUGIN_API getClassInfoUnicode (int32 index, PClassInfoW* info) = 0;
 357
 358         /** Receives information about host*/
 359         virtual tresult PLUGIN_API setHostContext (FUnknown* context) = 0;
 360
 361 //------------------------------------------------------------------------
 362         static const FUID iid;
 363 };
 364 DECLARE_CLASS_IID (IPluginFactory3, 0x4555A2AB, 0xC1234E57, 0x9B122910, 0x36878931)
 365 //------------------------------------------------------------------------
 366 } // namespace Steinberg
 367
 368 //------------------------------------------------------------------------
 369 #define LICENCE_UID(l1, l2, l3, l4) \
 370 { \
 371         (int8)((l1 & 0xFF000000) >> 24), (int8)((l1 & 0x00FF0000) >> 16), \
 372         (int8)((l1 & 0x0000FF00) >>  8), (int8)((l1 & 0x000000FF)      ), \
 373         (int8)((l2 & 0xFF000000) >> 24), (int8)((l2 & 0x00FF0000) >> 16), \
 374         (int8)((l2 & 0x0000FF00) >>  8), (int8)((l2 & 0x000000FF)      ), \
 375         (int8)((l3 & 0xFF000000) >> 24), (int8)((l3 & 0x00FF0000) >> 16), \
 376         (int8)((l3 & 0x0000FF00) >>  8), (int8)((l3 & 0x000000FF)      ), \
 377         (int8)((l4 & 0xFF000000) >> 24), (int8)((l4 & 0x00FF0000) >> 16), \
 378         (int8)((l4 & 0x0000FF00) >>  8), (int8)((l4 & 0x000000FF)      )  \
 379 }
 380
 381 //------------------------------------------------------------------------
 382 // GetPluginFactory
 383 //------------------------------------------------------------------------
 384 /**  Plug-in entry point.
 385 \ingroup pluginBase
 386 Any plug-in must define and export this function. \n
 387 A typical implementation of GetPluginFactory looks like this
 388 \code{.cpp}
 389 SMTG_EXPORT_SYMBOL IPluginFactory* PLUGIN_API GetPluginFactory ()
 390 {
 391         if (!gPluginFactory)
 392         {
 393                 static PFactoryInfo factoryInfo =
 394                 {
 395                         "My Company Name",
 396                         "http://www.mywebpage.com",
 397                         "mailto:myemail@address.com",
 398                         PFactoryInfo::kNoFlags
 399                 };
 400
 401                 gPluginFactory = new CPluginFactory (factoryInfo);
 402
 403                 static PClassInfo componentClass =
 404                 {
 405                         INLINE_UID (0x00000000, 0x00000000, 0x00000000, 0x00000000), // replace by a valid uid
 406                         1,
 407                         "Service",    // category
 408                         "Name"
 409                 };
 410
 411                 gPluginFactory->registerClass (&componentClass, MyComponentClass::newInstance);
 412         }
 413         else
 414                 gPluginFactory->addRef ();
 415
 416         return gPluginFactory;
 417 }
 418 \endcode
 419 \see \ref loadPlugin
 420 */
 421 extern "C"
 422 {
 423         SMTG_EXPORT_SYMBOL Steinberg::IPluginFactory* PLUGIN_API GetPluginFactory ();
 424         typedef Steinberg::IPluginFactory* (PLUGIN_API *GetFactoryProc) ();
 425 }