This interface allows plug-ins to read and write archives with minimal memory impact. It also allows for displaying progress when archiving or unarchiving model graphs. Its functions may only be called during the archiving/unarchiving process.
Because of the potentially large size of the archives, ARA does not use simple monolithic memory blocks as known from many companion APIs. Instead, it establishes a stream-like archive format so that copying large blocks of memory can be avoided. Plug-ins that create large archives should use any mean of data reduction that is appropriate to reduce the archive size. For example, they may implement gzip compression. Since it has good knowledge of the characteristics of the data, it can configure the compression algorithms so that optimal results are achieved. Consequently, there's no point for host to try to compress the data any further with generic algorithms.
Hosts that support both 32 and 64 bit architectures shall be aware of the fact that ARA archive sizes are pointer-sized data types, so they will differ in bit width between these architectures. This must be taken into account when storing the archive size in the host's document structure. Also, when importing documents from 64 bit into 32 bit, the host must check whether the archive is small enough to be loaded at all (i.e. its size fits into 32 bits). If not, it shall refuse to load the archive and provide a proper error message. This may seem like a restriction, but the reasoning behind this is that if the archive already exceeds the available address space, the resulting unarchived graph will do so too.
There's no creation or destruction call for the archive readers/writers because they are provided by the host for the duration of the (un-)archiving process, so the lifetime is implicitly defined.
When using API generation 1 or older and loading an archive through the deprecated functions begin-/endRestoringDocumentFromArchive(), plug-ins may choose to access the associated archive reader upon either begin- or endRestoringDocumentFromArchive() or even upon both calls, as suitable for their implementation - hosts must be able to provide the requested data during the duration of both calls.
Host developer using C++ ARA Library can implement the ARA::Host::ArchivingControllerInterface. For plug-in developers this interface is wrapped by the ARA::PlugIn::HostArchivingController.
Classes | |
| struct | ARAArchivingControllerInterface |
| Host interface: archive controller. As with all host interfaces, the function pointers in this struct must remain valid until all document controllers on the plug-in side that use it have been destroyed. More... | |
Typedefs | |
| typedef struct ARAArchivingControllerHostRefMarkupType * | ARAArchivingControllerHostRef |
| Reference to the host side representation of an archiving controller (opaque to the plug-in). | |
| typedef struct ARAArchiveReaderHostRefMarkupType * | ARAArchiveReaderHostRef |
| Reference to the host side representation of an archive reader (opaque to the plug-in). | |
| typedef struct ARAArchiveWriterHostRefMarkupType * | ARAArchiveWriterHostRef |
| Reference to the host side representation of an archive writer (opaque to the plug-in). | |
| struct ARAArchivingControllerInterface |
Host interface: archive controller. As with all host interfaces, the function pointers in this struct must remain valid until all document controllers on the plug-in side that use it have been destroyed.
Size-based struct versioning | |
See Versioned structs. | |
| ARASize | structSize |
Reading Archives | |
| ARASize(* | getArchiveSize )(ARAArchivingControllerHostRef controllerHostRef, ARAArchiveReaderHostRef archiveReaderHostRef) |
| Query the size of the archive. This may only be called from ARADocumentControllerInterface::restoreObjectsFromArchive(), or if using API generation 1 from the deprecated begin-/endRestoringDocumentFromArchive() calls. Plug-ins must respect this size when reading the archive, reading beyond the end of the data is a programming error (and should thus be asserted by the host). | |
| ARABool(* | readBytesFromArchive )(ARAArchivingControllerHostRef controllerHostRef, ARAArchiveReaderHostRef archiveReaderHostRef, ARASize position, ARASize length, ARAByte buffer[]) |
| Read bytes. This may only be called from ARADocumentControllerInterface::restoreObjectsFromArchive(), or if using API generation 1 from the deprecated begin-/endRestoringDocumentFromArchive() calls. Result is kARATrue upon success, or kARAFalse when there is a critical, nonrecoverable I/O error, such as a network failure while the file is being read from a server. In case of failing in this call, the host must notify the user about the problem in some appropriate way. The archive will not be restored by the plug-in then, it'll fall back into some proper initial state for the affected objects. | |
| ARAPersistentID(* | getDocumentArchiveID )(ARAArchivingControllerHostRef controllerHostRef, ARAArchiveReaderHostRef archiveReaderHostRef) |
| Query the document archive ID that the plug-in's factory provided when saving the archive. This may only be called from ARADocumentControllerInterface::restoreObjectsFromArchive(). Plug-ins can use this information to optimize their unarchiving code in case different archive formats are used depending on document archive ID. The returned pointer is owned by the host and must remain valid until the archive reader is destroyed. All hosts that support kARAAPIGeneration_2_0_Final or newer must implement this call. | |
Writing Archives | |
| ARABool(* | writeBytesToArchive )(ARAArchivingControllerHostRef controllerHostRef, ARAArchiveWriterHostRef archiveWriterHostRef, ARASize position, ARASize length, const ARAByte buffer[]) |
| Write bytes. This may only be called from storeObjectsToArchive() or the deprecated storeDocumentToArchive(). Result is kARATrue upon success, or kARAFalse when there is a critical, nonrecoverable I/O error, such as a network failure while the file is being written to a server. In case of failing in this call, the host must notify the user about the problem in an appropriate way. Note that a plug-in should strive to write the data consecutively in a stream-like manner. Nevertheless, repositioning is needed to support chunk-style archives where the chunk length must be specified at the start of the chunk, but is not known until the chunk data has been fully created (and possibly compressed). In that case, the plug-in will need to "rewind" to the chunk size entry in the chunk header after writing the chunk and update it accordingly. As in most file APIs, any range of bytes that was skipped when writing should be filled with 0 by the host. | |
(Un-)Archiving Progress Information | |
| void(* | notifyDocumentArchivingProgress )(ARAArchivingControllerHostRef controllerHostRef, float value) |
| Message to the host signaling document save progress, value ranges from 0.0f to 1.0f. This may only be called from storeObjectsToArchive() or from the deprecated storeDocumentToArchive(). In order to keep CPU load low, plug-ins should try to keep the update rate for this call as low as about 1000 calls per archive, which equals increments of 0.1%. | |
| void(* | notifyDocumentUnarchivingProgress )(ARAArchivingControllerHostRef controllerHostRef, float value) |
| Message to the host signaling document save progress, value ranges from 0.0f to 1.0f. This may only be called from ARADocumentControllerInterface::restoreObjectsFromArchive(), or if using API generation 1 from the deprecated begin-/endRestoringDocumentFromArchive() and the associated model object creation/update calls guarded by them. In the deprecated form, the first call should be made from begin- and the last call from endRestoringDocumentFromArchive(). In order to keep CPU load low, plug-ins should try to keep the update rate for this call as low as about 1000 calls per archive, which equals increments of 0.1%. | |