Partial Document Persistency

Detailed Description


These optional filters allow to only store a subset of the document graph into an archive, or only restore a subset of an archive into the document graph.

Classes

struct  ARARestoreObjectsFilter
 Optional filter when restoring objects.
Allows the host to specify a subset of the persistent objects in the archive to restore in ARADocumentControllerInterface::restoreObjectsFromArchive().
The given IDs refer to objects in the archive, but can optionally be mapped to those used in the current document. This may be necessary to resolve potential conflicts between persistent IDs from different documents when importing parts of one document into another (since persistent IDs are only required to be unique within a document, not across documents).
The C++ ARA Library offers plug-in developers the ARA::PlugIn::RestoreObjectsFilter utility class to ease the implementation of partial persistency. More...
 
struct  ARAStoreObjectsFilter
 Optional filter when storing objects.
Allows the host to specify a subset of the objects in the model graph to be stored in ARADocumentControllerInterface::storeObjectsToArchive().
The C++ ARA Library offers plug-in developers the ARA::PlugIn::StoreObjectsFilter utility class to ease the implementation of partial persistency. More...
 

Class Documentation

◆ ARARestoreObjectsFilter

struct ARARestoreObjectsFilter

Optional filter when restoring objects.
Allows the host to specify a subset of the persistent objects in the archive to restore in ARADocumentControllerInterface::restoreObjectsFromArchive().
The given IDs refer to objects in the archive, but can optionally be mapped to those used in the current document. This may be necessary to resolve potential conflicts between persistent IDs from different documents when importing parts of one document into another (since persistent IDs are only required to be unique within a document, not across documents).
The C++ ARA Library offers plug-in developers the ARA::PlugIn::RestoreObjectsFilter utility class to ease the implementation of partial persistency.

Public Attributes

ARASize structSize
 Size-based struct versioning - see Versioned structs.
 
ARABool documentData
 Flag to indicate whether the plug-in should include its private, opaque document state in the archive - see ARAStoreObjectsFilter::documentData for details.
 
ARASize audioSourceIDsCount
 Length of audioSourceArchiveIDs and audioSourceCurrentIDs (if provided).
 
const ARAPersistentID * audioSourceArchiveIDs
 Variable-sized C array listing the persistent IDs of the archived audio sources to restore. The list may be empty, in which case count should be 0 and the pointer NULL.
 
const ARAPersistentID * audioSourceCurrentIDs
 Optional variable-sized C array mapping each of the persistent IDs provided in audioSourceArchiveIDs to a potentially different persistent ID currently used for the audio sources to be restore in the current graph. If no mapping is desired, i.e. all audio source persistent IDs to restore match those in the current graph, the pointer should be NULL.
 
ARASize audioModificationIDsCount
 Length of audioModificationArchiveIDs and audioModificationCurrentIDs (if provided).
 
const ARAPersistentID * audioModificationArchiveIDs
 Variable-sized C array listing the persistent IDs of the archived audio modifications to restore. The list may be empty, in which case count should be 0 and the pointer NULL.
 
const ARAPersistentID * audioModificationCurrentIDs
 Optional variable-sized C array mapping each of the persistent IDs provided in audioModificationArchiveIDs to a potentially different persistent ID currently used for the audio modifications to be restore in the current graph. If no mapping is desired, i.e. all audio modification persistent IDs to restore match those in the current graph, the pointer should be NULL.
 

◆ ARAStoreObjectsFilter

struct ARAStoreObjectsFilter

Optional filter when storing objects.
Allows the host to specify a subset of the objects in the model graph to be stored in ARADocumentControllerInterface::storeObjectsToArchive().
The C++ ARA Library offers plug-in developers the ARA::PlugIn::StoreObjectsFilter utility class to ease the implementation of partial persistency.

Public Attributes

ARASize structSize
 Size-based struct versioning - see Versioned structs.
 
ARABool documentData
 Flag to indicate whether the plug-in should include its private, opaque document state in the archive. A typical example of private data is a fallback implementation in the plug-in for data not provided by the host. For example, if the host does not implement a chord track, a plug-in may need to implement this in its own UI in order to be fully usable. Since the host is not aware of this, the data must be stored privately at document level. This flag should be set to kARAFalse if the archive is intended for copy/paste or other means of data import/export between documents, or kARATrue if a host uses partial persistency as a general technique to store ARA documents for performance reasons (e.g. to avoid re-saving data that hasn't been changed, or to minimize sync activity when implementing collaborative editing across the network - note that such optimizations rely on proper update notifications by the plug-in). If implementing the latter, hosts will typically split the document into a partial archive that contains only the document data, plus a set of archives that each contain a single audio source. In such a setup, the audio modifications are either stored in the same archive as their underlying audio source, or each audio modification is separated into an archive of its own. The only restriction for such archive splicing (in addition to respecting the general data dependency rules for partial persistency outlined in the documentation of ARADocumentControllerInterface::restoreObjectsFromArchive()) is that when restoring, the partial archive which was saved with documentData == kARATrue is restored as last archive in the restore cycle, where the graph has its final structure and all object states are available.
 
ARASize audioSourceRefsCount
 Length of audioSourceRefs.
 
const ARAAudioSourceRef * audioSourceRefs
 Variable-sized C array listing the audio sources to store. The list may be empty, in which case count should be 0 and the pointer NULL.
 
ARASize audioModificationRefsCount
 Length of audioModificationRefs.
 
const ARAAudioModificationRef * audioModificationRefs
 Variable-sized C array listing the audio modifications to store. The list may be empty, in which case count should be 0 and the pointer NULL.