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 //------------------------------------------------------------------------ 45 class IPersistent: public FUnknown 46 { 47 public: 48 //------------------------------------------------------------------------ 49 /** The class ID must be a 16 bytes unique id that is used to create the object. 50 This ID is also used to identify the preset list when used with presets. */ 51 virtual tresult PLUGIN_API getClassID (char8* uid) = 0; 52 /** Store all members/data in the passed IAttributes. */ 53 virtual tresult PLUGIN_API saveAttributes (IAttributes* ) = 0; 54 /** Restore all members/data from the passed IAttributes. */ 55 virtual tresult PLUGIN_API loadAttributes (IAttributes* ) = 0; 56 //------------------------------------------------------------------------ 57 static const FUID iid; 58 }; 59 60 DECLARE_CLASS_IID (IPersistent, 0xBA1A4637, 0x3C9F46D0, 0xA65DBA0E, 0xB85DA829) 61 62 63 typedef FIDString IAttrID; 64 //------------------------------------------------------------------------ 65 /** Object Data Archive Interface. 66 [host imp] \n 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 //------------------------------------------------------------------------ 80 class IAttributes: public FUnknown 81 { 82 public: 83 //------------------------------------------------------------------------ 84 /*! \name Methods to write attributes 85 ******************************************************************************************************** */ 86 //@{ 87 /** Store any data in the archive. It is even possible to store sub-attributes by creating 88 a new IAttributes instance via the IHostClasses interface and pass it to the parent in the 89 FVariant. In this case the archive must take the ownership of the newly created object, which 90 is true for all objects that have been created only for storing. You tell the archive to take 91 ownership by adding the FVariant::kOwner flag to the FVariant::type member (data.type |= FVariant::kOwner). 92 When using the PAttributes functions, this is done through a function parameter.*/ 93 virtual tresult PLUGIN_API set (IAttrID attrID, const FVariant& data) = 0; 94 95 /** Store a list of data in the archive. Please note that the type of data is not mixable! So 96 you can only store a list of integers or a list of doubles/strings/etc. You can also store a list 97 of subattributes or other objects that implement the IPersistent interface.*/ 98 virtual tresult PLUGIN_API queue (IAttrID listID, const FVariant& data) = 0; 99 100 /** Store binary data in the archive. Parameter 'copyBytes' specifies if the passed data should be copied. 101 The archive cannot take the ownership of binary data. Either it just references a buffer in order 102 to write it to a file (copyBytes = false) or it copies the data to its own buffers (copyBytes = true). 103 When binary data should be stored in the default pool for example, you must always copy it!*/ 104 virtual tresult PLUGIN_API setBinaryData (IAttrID attrID, void* data, uint32 bytes, bool copyBytes) = 0; 105 //@} 106 107 /*! \name Methods to read attributes 108 ******************************************************************************************************** */ 109 //@{ 110 /** Get data previously stored to the archive. */ 111 virtual tresult PLUGIN_API get (IAttrID attrID, FVariant& data) = 0; 112 113 /** Get list of data previously stored to the archive. As long as there are queue members the method 114 will return kResultTrue. When the queue is empty, the methods returns kResultFalse. All lists except from 115 object lists can be reset which means that the items can be read once again. \see IAttributes::resetQueue */ 116 virtual tresult PLUGIN_API unqueue (IAttrID listID, FVariant& data) = 0; 117 118 /** Get the amount of items in a queue. */ 119 virtual int32 PLUGIN_API getQueueItemCount (IAttrID) = 0; 120 121 /** Reset a queue. If you need to restart reading a queue, you have to reset it. You can reset a queue at any time.*/ 122 virtual tresult PLUGIN_API resetQueue (IAttrID attrID) = 0; 123 124 /** Reset all queues in the archive.*/ 125 virtual tresult PLUGIN_API resetAllQueues () = 0; 126 127 /** Read binary data from the archive. The data is copied into the passed buffer. The size of that buffer 128 must fit the size of data stored in the archive which can be queried via IAttributes::getBinaryDataSize */ 129 virtual tresult PLUGIN_API getBinaryData (IAttrID attrID, void* data, uint32 bytes) = 0; 130 /** Get the size in bytes of binary data in the archive. */ 131 virtual uint32 PLUGIN_API getBinaryDataSize (IAttrID attrID) = 0; 132 //@} 133 134 //------------------------------------------------------------------------ 135 static const FUID iid; 136 }; 137 138 DECLARE_CLASS_IID (IAttributes, 0xFA1E32F9, 0xCA6D46F5, 0xA982F956, 0xB1191B58) 139 140 //------------------------------------------------------------------------ 141 /** Extended access to Attributes; supports Attribute retrieval via iteration. 142 [host imp] \n 143 [released] C7/N6 \n 144 \ingroup frameworkHostClasses 145 */ 146 //------------------------------------------------------------------------ 147 class IAttributes2 : public IAttributes 148 { 149 public: 150 /** Returns the number of existing attributes. */ 151 virtual int32 PLUGIN_API countAttributes () const = 0; 152 /** Returns the attribute's ID for the given index. */ 153 virtual IAttrID PLUGIN_API getAttributeID (int32 index) const = 0; 154 //------------------------------------------------------------------------ 155 static const FUID iid; 156 }; 157 158 DECLARE_CLASS_IID (IAttributes2, 0x1382126A, 0xFECA4871, 0x97D52A45, 0xB042AE99) 159 160 //------------------------------------------------------------------------ 161 } // namespace Steinberg 162