Open 3D Engine Archive Gem API Reference  24.09
O3DE is an open-source, fully-featured, high-fidelity, modular 3D engine for building games and simulations, available to every industry.
Classes | Public Types | Public Member Functions | Public Attributes | List of all members
Archive::IArchiveWriter Class Referenceabstract

#include <ArchiveWriterAPI.h>

Inherited by Archive::ArchiveWriter.

Classes

struct  ArchiveStreamDeleter
 

Public Types

using ArchiveStreamPtr = AZStd::unique_ptr< AZ::IO::GenericStream, ArchiveStreamDeleter >
 
using CommitResult = AZStd::expected< void, ResultString >
 

Public Member Functions

 AZ_TYPE_INFO_WITH_NAME_DECL (IArchiveWriter)
 
 AZ_RTTI_NO_TYPE_INFO_DECL ()
 
virtual bool MountArchive (AZ::IO::PathView archivePath)=0
 
virtual bool MountArchive (ArchiveStreamPtr archiveStream)=0
 
virtual void UnmountArchive ()=0
 
virtual bool IsMounted () const =0
 Returns if an open archive that is mounted.
 
virtual CommitResult Commit ()=0
 
virtual ArchiveAddFileResult AddFileToArchive (AZ::IO::GenericStream &inputStream, const ArchiveWriterFileSettings &fileSettings)=0
 
virtual ArchiveAddFileResult AddFileToArchive (AZStd::span< const AZStd::byte > inputSpan, const ArchiveWriterFileSettings &fileSettings)=0
 
virtual ArchiveFileToken FindFile (AZ::IO::PathView relativePath) const =0
 
virtual bool ContainsFile (AZ::IO::PathView relativePath) const =0
 
virtual ArchiveRemoveFileResult RemoveFileFromArchive (ArchiveFileToken filePathToken)=0
 
virtual ArchiveRemoveFileResult RemoveFileFromArchive (AZ::IO::PathView relativePath)=0
 
virtual bool DumpArchiveMetadata (AZ::IO::GenericStream &metadataStream, const ArchiveMetadataSettings &metadataSettings={}) const =0
 

Public Attributes

 AZ_CLASS_ALLOCATOR_DECL
 

Detailed Description

Interface for the ArchiveWriter of O3DE Archive format The caller is required to supply a ArchiveWriterSettings structure instance which contains the ArchiveHeader and ArchiveTableOfContents data to use when writing to the Archive file The class can be initialized with a user supplied AZ::IO::GenericStream class in which case the stream needs to be open with OpenMode::ModeUpdate The reason why is that to locate information about any content files in order to update an existing archive it read access is needed The recommend OpenMode value for opening a new archive or updating an existing archive are as follows constexpr OpenMode mode = OpenMode::Update | OpenMode::Append | OpenMode::Binary The Append option makes sure that the Archive is not truncated on open

Member Typedef Documentation

◆ CommitResult

using Archive::IArchiveWriter::CommitResult = AZStd::expected<void, ResultString>

Write the updated ArchiveHeader to the beginning of the stream and Table of Contents to end of the stream

If this call is successful, the archive TOC has been successfully written This function has been marked [[nodiscard]], to ensure the caller checks the return value

Returns
A successful expectation if the TOC has been written

Member Function Documentation

◆ AddFileToArchive() [1/2]

virtual ArchiveAddFileResult Archive::IArchiveWriter::AddFileToArchive ( AZ::IO::GenericStream &  inputStream,
const ArchiveWriterFileSettings &  fileSettings 
)
pure virtual

Adds the content from the stream to the relative path

Parameters
inputStreamstream class where data for the file is source from The entire stream is read into the memory and written into archive
fileSettingssettings used to configure the relative path to write to the archive for the given file data. It also allows users to configure the compression algorithm to use, and whether the AddFileToArchive logic fails if an existing file is being added
Returns
ArchiveAddFileResult containing the actual compression file path as saved to the Archive TOC, the compression algorithm used and an Archive File Token which can be used to remove the file if need be On failure, the result outcome contains any errors that have occurred

Implemented in Archive::ArchiveWriter.

◆ AddFileToArchive() [2/2]

virtual ArchiveAddFileResult Archive::IArchiveWriter::AddFileToArchive ( AZStd::span< const AZStd::byte >  inputSpan,
const ArchiveWriterFileSettings &  fileSettings 
)
pure virtual

Use the span contents to add the file to the archive

Parameters
inputSpanview of data which will be written to the archive at the relative path supplied in the @fileSettings parameter
fileSettingssettings used to configure the relative path to write to the archive for the given file data. It also allows users to configure the compression algorithm to use, and whether the AddFileToArchive logic fails if an existing file is being added
Returns
ArchiveAddFileResult containing the actual compression file path as saved to the Archive TOC, the compression algorithm used and an Archive File Token which can be used to remove the file if need be On failure, the result outcome contains any errors that have occurred

Implemented in Archive::ArchiveWriter.

◆ ContainsFile()

virtual bool Archive::IArchiveWriter::ContainsFile ( AZ::IO::PathView  relativePath) const
pure virtual

Returns if the archive contains a relative path

Parameters
relativePathRelative path within archive to search for
Returns
true if the relative path is contained with the Archive equivalent to return FindFile(relativePath) != InvalidArchiveFileToken;

Implemented in Archive::ArchiveWriter.

◆ DumpArchiveMetadata()

virtual bool Archive::IArchiveWriter::DumpArchiveMetadata ( AZ::IO::GenericStream &  metadataStream,
const ArchiveMetadataSettings &  metadataSettings = {} 
) const
pure virtual

Dump metadata for the archive to the supplied generic stream

Parameters
metadataStreamarchive file metadata will be written to the stream
metadataSettingssettings using which control the file metadata to write to the stream
Returns
true if metadata was successfully written

Implemented in Archive::ArchiveWriter.

◆ FindFile()

virtual ArchiveFileToken Archive::IArchiveWriter::FindFile ( AZ::IO::PathView  relativePath) const
pure virtual

Searches for a relative path within the archive

Parameters
relativePathRelative path within archive to search for
Returns
A token that identifies the Archive file if it exist if the with the specified path doesn't exist InvalidArchiveFileToken is returned

Implemented in Archive::ArchiveWriter.

◆ MountArchive()

virtual bool Archive::IArchiveWriter::MountArchive ( AZ::IO::PathView  archivePath)
pure virtual

Opens the archive path and returns true if successful Will unmount any previously mounted archive

Implemented in Archive::ArchiveWriter.

◆ RemoveFileFromArchive() [1/2]

virtual ArchiveRemoveFileResult Archive::IArchiveWriter::RemoveFileFromArchive ( ArchiveFileToken  filePathToken)
pure virtual

Removes the file from the archive using the ArchiveFileToken

Parameters
filePathTokenRelative path within archive to search for NOTE: The entry in the table of contents is not actually removed The index where the file is located using the filePathToken is just added to the removed file indices set
Returns
ArchiveRemoveResult with metadata about how the deleted file was stored in the Archive

Implemented in Archive::ArchiveWriter.

◆ RemoveFileFromArchive() [2/2]

virtual ArchiveRemoveFileResult Archive::IArchiveWriter::RemoveFileFromArchive ( AZ::IO::PathView  relativePath)
pure virtual

Removes the file from the archive using a relative path name

Parameters
relativePathRelative path within archive to search for
Returns
ArchiveRemoveResult with metadata about how the deleted file was stored in the Archive

Implemented in Archive::ArchiveWriter.

◆ UnmountArchive()

virtual void Archive::IArchiveWriter::UnmountArchive ( )
pure virtual

Closes the handle to the mounted archive stream This will invoke the Commit() function to write the archive TOC to the stream before closing the stream

Implemented in Archive::ArchiveWriter.

The documentation for this class was generated from the following files: