//----------------------------------------------------------------------------- // Project : SDK Core // // Category : SDK Core Interfaces // Filename : pluginterfaces/base/ipersistent.h // Created by : Steinberg, 09/2004 // Description : Plug-In Storage Interfaces // //----------------------------------------------------------------------------- // This file is part of a Steinberg SDK. It is subject to the license terms // in the LICENSE file found in the top-level directory of this distribution // and at www.steinberg.net/sdklicenses. // No part of the SDK, including this file, may be copied, modified, propagated, // or distributed except according to the terms contained in the LICENSE file. //----------------------------------------------------------------------------- #pragma once #include "pluginterfaces/base/funknown.h" namespace Steinberg { class FVariant; class IAttributes; //------------------------------------------------------------------------ /** Persistent Object Interface. [plug imp] \n This interface is used to store/restore attributes of an object. An IPlugController can implement this interface to handle presets. The gui-xml for a preset control looks like this: \code .... .... \endcode The tag data="Preset" tells the host to create a preset controller that handles the 3 values named "preset control", "store preset", and "remove preset". */ class IPersistent: public FUnknown { public: //------------------------------------------------------------------------ /** The class ID must be a 16 bytes unique id that is used to create the object. This ID is also used to identify the preset list when used with presets. */ virtual tresult PLUGIN_API getClassID (char8* uid) = 0; /** Store all members/data in the passed IAttributes. */ virtual tresult PLUGIN_API saveAttributes (IAttributes* ) = 0; /** Restore all members/data from the passed IAttributes. */ virtual tresult PLUGIN_API loadAttributes (IAttributes* ) = 0; //------------------------------------------------------------------------ static const FUID iid; }; DECLARE_CLASS_IID (IPersistent, 0xBA1A4637, 0x3C9F46D0, 0xA65DBA0E, 0xB85DA829) /** \ingroup smtgtypedef */ /**@{*/ typedef FIDString IAttrID; /**@}*/ //------------------------------------------------------------------------ /** Object Data Archive Interface. - [host imp] - store data/objects/binary/subattributes in the archive - read stored data from the archive All data stored to the archive are identified by a string (IAttrID), which must be unique on each IAttribute level. The basic set/get methods make use of the FVariant class defined in 'funknown.h'. For a more convenient usage of this interface, you should use the functions defined in namespace PAttributes (public.sdk/source/common/pattributes.h+cpp) !! \ingroup frameworkHostClasses */ class IAttributes: public FUnknown { public: //------------------------------------------------------------------------ /*! \name Methods to write attributes ******************************************************************************************************** */ //@{ /** Store any data in the archive. It is even possible to store sub-attributes by creating * a new IAttributes instance via the IHostClasses interface and pass it to the parent in the * FVariant. In this case the archive must take the ownership of the newly created object, * which is true for all objects that have been created only for storing. You tell the archive * to take ownership by adding the FVariant::kOwner flag to the FVariant::type member (data.type * |= FVariant::kOwner). When using the PAttributes functions, this is done through a function * parameter.*/ virtual tresult PLUGIN_API set (IAttrID attrID /*in*/, const FVariant& data /*in*/) = 0; /** Store a list of data in the archive. Please note that the type of data is not mixable! So * you can only store a list of integers or a list of doubles/strings/etc. You can also store a * list of subattributes or other objects that implement the IPersistent interface.*/ virtual tresult PLUGIN_API queue (IAttrID listID /*in*/, const FVariant& data /*in*/) = 0; /** Store binary data in the archive. Parameter 'copyBytes' specifies if the passed data should * be copied. The archive cannot take the ownership of binary data. Either it just references a * buffer in order to write it to a file (copyBytes = false) or it copies the data to its own * buffers (copyBytes = true). When binary data should be stored in the default pool for * example, you must always copy it!*/ virtual tresult PLUGIN_API setBinaryData (IAttrID attrID /*in*/, void* data /*in*/, uint32 bytes /*in*/, bool copyBytes /*in*/) = 0; //@} /*! \name Methods to read attributes ******************************************************************************************************** */ //@{ /** Get data previously stored to the archive. */ virtual tresult PLUGIN_API get (IAttrID attrID /*in*/, FVariant& data /*out*/) = 0; /** Get list of data previously stored to the archive. As long as there are queue members the * method will return kResultTrue. When the queue is empty, the methods returns kResultFalse. * All lists except from object lists can be reset which means that the items can be read once * again. \see IAttributes::resetQueue */ virtual tresult PLUGIN_API unqueue (IAttrID listID /*in*/, FVariant& data /*out*/) = 0; /** Get the amount of items in a queue. */ virtual int32 PLUGIN_API getQueueItemCount (IAttrID attrId /*in*/) = 0; /** Reset a queue. If you need to restart reading a queue, you have to reset it. You can reset a * queue at any time.*/ virtual tresult PLUGIN_API resetQueue (IAttrID attrID /*in*/) = 0; /** Reset all queues in the archive.*/ virtual tresult PLUGIN_API resetAllQueues () = 0; /** Read binary data from the archive. The data is copied into the passed buffer. The size of * that buffer must fit the size of data stored in the archive which can be queried via * IAttributes::getBinaryDataSize */ virtual tresult PLUGIN_API getBinaryData (IAttrID attrID /*in*/, void* data /*inout*/, uint32 bytes /*in*/) = 0; /** Get the size in bytes of binary data in the archive. */ virtual uint32 PLUGIN_API getBinaryDataSize (IAttrID attrID /*in*/) = 0; //@} //------------------------------------------------------------------------ static const FUID iid; }; DECLARE_CLASS_IID (IAttributes, 0xFA1E32F9, 0xCA6D46F5, 0xA982F956, 0xB1191B58) //------------------------------------------------------------------------ /** Extended access to Attributes; supports Attribute retrieval via iteration. - [host imp] - [released] C7/N6 \ingroup frameworkHostClasses */ class IAttributes2 : public IAttributes { public: /** Returns the number of existing attributes. */ virtual int32 PLUGIN_API countAttributes () const = 0; /** Returns the attribute's ID for the given index. */ virtual IAttrID PLUGIN_API getAttributeID (int32 index /*in*/) const = 0; //------------------------------------------------------------------------ static const FUID iid; }; DECLARE_CLASS_IID (IAttributes2, 0x1382126A, 0xFECA4871, 0x97D52A45, 0xB042AE99) //------------------------------------------------------------------------ } // namespace Steinberg