plArchiveUtils Namespace Reference

Utilities for working with plArchive files. More...

Classes
struct	TOCMeta

Typedefs
using	FileWriteProgressCallback = plDelegate<bool(plUInt64, plUInt64)>

Functions
PL_FOUNDATION_DLL plHybridArray< plString, 4, plStaticsAllocatorWrapper > &	GetAcceptedArchiveFileExtensions ()
	Returns a modifiable array of file extensions that the engine considers to be valid plArchive file extensions.
PL_FOUNDATION_DLL bool	IsAcceptedArchiveFileExtensions (plStringView sExtension)
	Checks case insensitive, whether the given extension is in the list of GetAcceptedArchiveFileExtensions().
PL_FOUNDATION_DLL plResult	WriteHeader (plStreamWriter &inout_stream)
	Writes the header that identifies the plArchive file and version to the stream.
PL_FOUNDATION_DLL plResult	ReadHeader (plStreamReader &inout_stream, plUInt8 &out_uiVersion)
	Reads the plArchive header. Returns success and the version, if the stream is a valid plArchive file.
PL_FOUNDATION_DLL plResult	AppendTOC (plStreamWriter &inout_stream, const plArchiveTOC &toc)
	Writes the archive TOC to the stream. This must be the last thing in the stream, if ExtractTOC() is supposed to work.
PL_FOUNDATION_DLL plResult	ExtractTOCMeta (plUInt64 uiArchiveEndingDataSize, const void *pArchiveEndingDataBuffer, TOCMeta &ref_tocMeta, plUInt8 uiArchiveVersion)
	Deserializes the TOC meta from archive ending. Assumes the TOC is the very last data in the file.
PL_FOUNDATION_DLL plResult	ExtractTOCMeta (const plMemoryMappedFile &memFile, TOCMeta &ref_tocMeta, plUInt8 uiArchiveVersion)
	Deserializes the TOC meta from the memory mapped file. Assumes the TOC is the very last data in the file.
PL_FOUNDATION_DLL plResult	ExtractTOC (plUInt64 uiArchiveEndingDataSize, const void *pArchiveEndingDataBuffer, plArchiveTOC &ref_toc, plUInt8 uiArchiveVersion)
	Deserializes the TOC from from archive ending. Assumes the TOC is the very last data in the file and reads it from the back.
PL_FOUNDATION_DLL plResult	ExtractTOC (const plMemoryMappedFile &memFile, plArchiveTOC &ref_toc, plUInt8 uiArchiveVersion)
	Deserializes the TOC from the memory mapped file. Assumes the TOC is the very last data in the file and reads it from the back.
PL_FOUNDATION_DLL plResult	WriteEntry (plStreamWriter &inout_stream, plStringView sAbsSourcePath, plUInt32 uiPathStringOffset, plArchiveCompressionMode compression, plInt32 iCompressionLevel, plArchiveEntry &ref_tocEntry, plUInt64 &inout_uiCurrentStreamPosition, FileWriteProgressCallback progress=FileWriteProgressCallback())
	Writes a single file entry to an plArchive stream with the given compression level.
PL_FOUNDATION_DLL plResult	WriteEntryPreprocessed (plStreamWriter &inout_stream, plConstByteArrayPtr entryData, plUInt32 uiPathStringOffset, plArchiveCompressionMode compression, plUInt32 uiUncompressedEntryDataSize, plArchiveEntry &ref_tocEntry, plUInt64 &inout_uiCurrentStreamPosition)
	Writes a single file entry to an plArchive stream with the given compression level.
PL_FOUNDATION_DLL plResult	WriteEntryOptimal (plStreamWriter &inout_stream, plStringView sAbsSourcePath, plUInt32 uiPathStringOffset, plArchiveCompressionMode compression, plInt32 iCompressionLevel, plArchiveEntry &ref_tocEntry, plUInt64 &inout_uiCurrentStreamPosition, FileWriteProgressCallback progress=FileWriteProgressCallback())
	Similar to WriteEntry, but if compression is enabled, checks that compression makes enough of a difference. If compression does not reduce file size enough, the file is stored uncompressed instead.
PL_FOUNDATION_DLL void	ConfigureRawMemoryStreamReader (const plArchiveEntry &entry, const void *pStartOfArchiveData, plRawMemoryStreamReader &ref_memReader)
	Configures memReader as a view into the data stored for entry in the archive file.
PL_FOUNDATION_DLL plUniquePtr< plStreamReader >	CreateEntryReader (const plArchiveEntry &entry, const void *pStartOfArchiveData)
	Creates a new stream reader which allows to read the uncompressed data for the given archive entry.
PL_FOUNDATION_DLL plResult	ReadZipHeader (plStreamReader &inout_stream, plUInt8 &out_uiVersion)
PL_FOUNDATION_DLL plResult	ExtractZipTOC (const plMemoryMappedFile &memFile, plArchiveTOC &ref_toc)

Variables
constexpr plUInt32	ArchiveHeaderSize = 16
constexpr plUInt32	ArchiveTOCMetaMaxFooterSize = 14 + 12

Detailed Description

Utilities for working with plArchive files.

Function Documentation

ConfigureRawMemoryStreamReader()

void plArchiveUtils::ConfigureRawMemoryStreamReader	(	const plArchiveEntry &	entry,
		const void *	pStartOfArchiveData,
		plRawMemoryStreamReader &	ref_memReader )

Configures memReader as a view into the data stored for entry in the archive file.

The raw memory stream may be compressed or uncompressed. This only creates a view for the stored data, it does not interpret it.

CreateEntryReader()

plUniquePtr< plStreamReader > plArchiveUtils::CreateEntryReader	(	const plArchiveEntry &	entry,
		const void *	pStartOfArchiveData )

Creates a new stream reader which allows to read the uncompressed data for the given archive entry.

Under the hood it may create different types of stream readers to uncompress or decode the data.

GetAcceptedArchiveFileExtensions()

plHybridArray< plString, 4, plStaticsAllocatorWrapper > & plArchiveUtils::GetAcceptedArchiveFileExtensions

(

)

Returns a modifiable array of file extensions that the engine considers to be valid plArchive file extensions.

By default it always contains 'plArchive'. Add or overwrite the values, if you want custom file extensions to be handled as plArchives.

WriteEntry()

plResult plArchiveUtils::WriteEntry	(	plStreamWriter &	inout_stream,
		plStringView	sAbsSourcePath,
		plUInt32	uiPathStringOffset,
		plArchiveCompressionMode	compression,
		plInt32	iCompressionLevel,
		plArchiveEntry &	ref_tocEntry,
		plUInt64 &	inout_uiCurrentStreamPosition,
		FileWriteProgressCallback	progress = FileWriteProgressCallback() )

Writes a single file entry to an plArchive stream with the given compression level.

Appends information to the TOC for finding the data in the stream. Reads and updates inout_uiCurrentStreamPosition with the data byte offset. The progress callback is executed for every couple of KB of data that were written.

WriteEntryPreprocessed()

plResult plArchiveUtils::WriteEntryPreprocessed	(	plStreamWriter &	inout_stream,
		plConstByteArrayPtr	entryData,
		plUInt32	uiPathStringOffset,
		plArchiveCompressionMode	compression,
		plUInt32	uiUncompressedEntryDataSize,
		plArchiveEntry &	ref_tocEntry,
		plUInt64 &	inout_uiCurrentStreamPosition )

Writes a single file entry to an plArchive stream with the given compression level.

Appends information to the TOC for finding the data in the stream. Reads and updates inout_uiCurrentStreamPosition with the data byte offset. Compression parameter indicate compression that the entry data already have applied.