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

   1 //-----------------------------------------------------------------------------
   2 // Project     : SDK Core
   3 //
   4 // Category    : SDK Core Interfaces
   5 // Filename    : pluginterfaces/base/ipersistent.h
   6 // Created by  : Steinberg, 09/2004
   7 // Description : Plug-In Storage 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 "pluginterfaces/base/funknown.h"
  20
  21 namespace Steinberg {
  22
  23 class FVariant;
  24 class IAttributes;
  25 //------------------------------------------------------------------------
  26 /**  Persistent Object Interface.
  27 [plug imp] \n
  28 This interface is used to store/restore attributes of an object.
  29 An IPlugController can implement this interface to handle presets.
  30 The gui-xml for a preset control looks like this:
  31 \code
  32 ....
  33 <view name="PresetView" data="Preset"/>
  34 ....
  35 <template name="PresetView">
  36         <view name="preset control" size="0, 0, 100, 20"/>
  37         <switch name="store preset" size="125,0,80,20" style="push|immediate" title="Store"  />
  38         <switch name="remove preset" size="220,0,80,20" style="push|immediate" title="Delete"  />
  39 </template>
  40 \endcode
  41 The tag data="Preset" tells the host to create a preset controller that handles the
  42 3 values named "preset control",  "store preset", and "remove preset".
  43 */
  44 class IPersistent: public FUnknown
  45 {
  46 public:
  47 //------------------------------------------------------------------------
  48         /** The class ID must be a 16 bytes unique id that is used to create the object.
  49         This ID is also used to identify the preset list when used with presets. */
  50         virtual tresult PLUGIN_API getClassID (char8* uid) = 0;
  51         /** Store all members/data in the passed IAttributes. */
  52         virtual tresult PLUGIN_API saveAttributes (IAttributes* ) = 0;
  53         /** Restore all members/data from the passed IAttributes. */
  54         virtual tresult PLUGIN_API loadAttributes (IAttributes* ) = 0;
  55 //------------------------------------------------------------------------
  56         static const FUID iid;
  57 };
  58
  59 DECLARE_CLASS_IID (IPersistent, 0xBA1A4637, 0x3C9F46D0, 0xA65DBA0E, 0xB85DA829)
  60
  61
  62 typedef FIDString IAttrID;
  63 //------------------------------------------------------------------------
  64 /**  Object Data Archive Interface.
  65 - [host imp]
  66
  67 - store data/objects/binary/subattributes in the archive
  68 - read stored data from the archive
  69
  70 All data stored to the archive are identified by a string (IAttrID), which must be unique on each
  71 IAttribute level.
  72
  73 The basic set/get methods make use of the FVariant class defined in 'funknown.h'.
  74 For a more convenient usage of this interface, you should use the functions defined
  75 in namespace PAttributes (public.sdk/source/common/pattributes.h+cpp) !!
  76
  77 \ingroup frameworkHostClasses
  78 */
  79 class IAttributes: public FUnknown
  80 {
  81 public:
  82 //------------------------------------------------------------------------
  83         /*! \name Methods to write attributes
  84         ******************************************************************************************************** */
  85         //@{
  86         /** Store any data in the archive. It is even possible to store sub-attributes by creating
  87             a new IAttributes instance via the IHostClasses interface and pass it to the parent in the
  88                 FVariant. In this case the archive must take the ownership of the newly created object, which
  89                 is true for all objects that have been created only for storing. You tell the archive to take
  90                 ownership by adding the FVariant::kOwner flag to the FVariant::type member (data.type |= FVariant::kOwner).
  91                 When using the PAttributes functions, this is done through a function parameter.*/
  92         virtual tresult PLUGIN_API set (IAttrID attrID, const FVariant& data) = 0;
  93
  94         /** Store a list of data in the archive. Please note that the type of data is not mixable! So
  95             you can only store a list of integers or a list of doubles/strings/etc. You can also store a list
  96                 of subattributes or other objects that implement the IPersistent interface.*/
  97         virtual tresult PLUGIN_API queue (IAttrID listID, const FVariant& data) = 0;
  98
  99         /** Store binary data in the archive. Parameter 'copyBytes' specifies if the passed data should be copied.
 100             The archive cannot take the ownership of binary data. Either it just references a buffer in order
 101                 to write it to a file (copyBytes = false) or it copies the data to its own buffers (copyBytes = true).
 102                 When binary data should be stored in the default pool for example, you must always copy it!*/
 103         virtual tresult PLUGIN_API setBinaryData (IAttrID attrID, void* data, uint32 bytes, bool copyBytes) = 0;
 104         //@}
 105
 106         /*! \name Methods to read attributes
 107         ******************************************************************************************************** */
 108         //@{
 109         /** Get data previously stored to the archive. */
 110         virtual tresult PLUGIN_API get (IAttrID attrID, FVariant& data) = 0;
 111
 112         /** Get list of data previously stored to the archive. As long as there are queue members the method
 113             will return kResultTrue. When the queue is empty, the methods returns kResultFalse. All lists except from
 114                 object lists can be reset which means that the items can be read once again. \see IAttributes::resetQueue */
 115         virtual tresult PLUGIN_API unqueue (IAttrID listID, FVariant& data) = 0;
 116
 117         /** Get the amount of items in a queue. */
 118         virtual int32 PLUGIN_API getQueueItemCount (IAttrID) = 0;
 119
 120         /** Reset a queue. If you need to restart reading a queue, you have to reset it. You can reset a queue at any time.*/
 121         virtual tresult PLUGIN_API resetQueue (IAttrID attrID) = 0;
 122
 123         /** Reset all queues in the archive.*/
 124         virtual tresult PLUGIN_API resetAllQueues () = 0;
 125
 126         /** Read binary data from the archive. The data is copied into the passed buffer. The size of that buffer
 127             must fit the size of data stored in the archive which can be queried via IAttributes::getBinaryDataSize  */
 128         virtual tresult PLUGIN_API getBinaryData (IAttrID attrID, void* data, uint32 bytes) = 0;
 129         /** Get the size in bytes of binary data in the archive. */
 130         virtual uint32 PLUGIN_API getBinaryDataSize (IAttrID attrID) = 0;
 131         //@}
 132
 133 //------------------------------------------------------------------------
 134         static const FUID iid;
 135 };
 136
 137 DECLARE_CLASS_IID (IAttributes, 0xFA1E32F9, 0xCA6D46F5, 0xA982F956, 0xB1191B58)
 138
 139 //------------------------------------------------------------------------
 140 /**  Extended access to Attributes; supports Attribute retrieval via iteration.
 141 - [host imp]
 142 - [released] C7/N6
 143
 144 \ingroup frameworkHostClasses
 145 */
 146 class IAttributes2 : public IAttributes
 147 {
 148 public:
 149         /** Returns the number of existing attributes. */
 150         virtual int32 PLUGIN_API countAttributes () const = 0;
 151         /** Returns the attribute's ID for the given index. */
 152         virtual IAttrID PLUGIN_API getAttributeID (int32 index) const = 0;
 153 //------------------------------------------------------------------------
 154         static const FUID iid;
 155 };
 156
 157 DECLARE_CLASS_IID (IAttributes2, 0x1382126A, 0xFECA4871, 0x97D52A45, 0xB042AE99)
 158
 159 //------------------------------------------------------------------------
 160 } // namespace Steinberg