reader.h File Reference

Pack file reader. More...

#include "pack/common.h"

Typedefs
typedef struct PackReader_T	PackReader_T
	Pack reader structure.
typedef PackReader_T *	PackReader
	Pack reader instance.

Functions
PackResult	createFilePackReader (const char *filePath, bool isResourcesDirectory, uint32_t threadCount, PackReader *packReader)
	Creates a new file pack reader instance.
void	destroyPackReader (PackReader packReader)
	Destroys Pack reader instance.
uint64_t	getPackItemCount (PackReader packReader)
	Returns total Pack item count. (MT-Safe)
bool	getPackItemIndex (PackReader packReader, const char *path, uint64_t *index)
	Returns Pack item index if it is found. (MT-Safe)
uint32_t	getPackItemDataSize (PackReader packReader, uint64_t index)
	Returns Pack item uncompressed data size in bytes. (MT-Safe)
uint32_t	getPackItemZipSize (PackReader packReader, uint64_t index)
	Returns Pack item compressed data size in bytes. (MT-Safe)
PackResult	readPackItemData (PackReader packReader, uint64_t itemIndex, uint8_t *buffer, uint32_t threadIndex)
	Reads Pack item binary data. (MT-Safe)
uint64_t	getPackItemFileOffset (PackReader packReader, uint64_t index)
	Returns Pack item data offset in the archive file. (MT-Safe)
bool	isPackItemReference (PackReader packReader, uint64_t index)
	Returns true if pack item is a reference to a duplicate item. (MT-Safe)
const char *	getPackItemPath (PackReader packReader, uint64_t index)
	Returns Pack item path string. (MT-Safe)
void **const	getPackZstdContexts (PackReader packReader)
	Returns Pack ZSTD context array. (MT-Safe)
PackResult	unpackFiles (const char *filePath, bool printProgress)
	Unpacks files from the pack. (MT-Safe)

Detailed Description

Pack file reader.

Used to read Pack archives at runtime. When opening a file, only information about file names and their locations in the archive is loaded to save RAM and CPU time. After that, it's possible to selectively extract only the necessary files from the archive. Loading data from files can be done concurrently from multiple threads.

Function Documentation

createFilePackReader()

PackResult createFilePackReader	(	const char *	filePath,
		bool	isResourcesDirectory,
		uint32_t	threadCount,
		PackReader *	packReader )

Creates a new file pack reader instance.

The main function for opening Pack archives. It creates a new Pack reader instance and reads information about the location of packed files in the file. Subsequently, it organizes this information for quick searching and reading data from the archive file.

Note

You should destroy created Pack instance manually.

Parameters

[in]	filePath	target Pack file path string
	isResourcesDirectory	read from the resources directory (Android/iOS/macOS only)
	threadCount	max concurrent read thread count
[out]	packReader	pointer to the Pack reader instance

Returns

The PackResult code and writes reader instance on success.

Return values

SUCCESS_PACK_RESULT	on success
FAILED_TO_ALLOCATE_PACK_RESULT	if out of memory
FAILED_TO_GET_DIRECTORY_PACK_RESULT	if failed to get resources directory path
FAILED_TO_OPEN_FILE_PACK_RESULT	if file doesn't exist
FAILED_TO_CREATE_ZSTD_PACK_RESULT	if failed to create ZSTD contexts
FAILED_TO_READ_FILE_PACK_RESULT	if failed to read Pack file data
FAILED_TO_SEEK_FILE_PACK_RESULT	if failed to seek Pack file data
BAD_FILE_TYPE_PACK_RESULT	if file is not a Pack archive
BAD_FILE_VERSION_PACK_RESULT	if different Pack file version
BAD_FILE_ENDIANNESS_PACK_RESULT	if different Pack file data endianness
BAD_DATA_SIZE_PACK_RESULT	if bad Pack file data size

destroyPackReader()

void destroyPackReader

(

PackReader

packReader

)

Destroys Pack reader instance.

Parameters

packReader

pack reader instance or NULL

getPackItemCount()

uint64_t getPackItemCount

(

PackReader

packReader

)

Returns total Pack item count. (MT-Safe)

You can use the returned value to iterate over all Pack archive files.

Parameters

packReader

pack reader instance

Returns

The total number of the items inside Pack file.

Return values

Integer

between 1 and 18,446,744,073,709,551,615

getPackItemIndex()

bool getPackItemIndex	(	PackReader	packReader,
		const char *	path,
		uint64_t *	index )

Returns Pack item index if it is found. (MT-Safe)

You can use the returned item index to obtain it's complete information.

Parameters

	packReader	pack reader instance
[in]	path	item path string used to pack the file
[out]	index	pointer to the uint64_t item index

Returns

True if item is found and writes index value, otherwise false.

Return values

true	if the item has been found
false	if file doesn't exist in the Pack

getPackItemDataSize()

uint32_t getPackItemDataSize	(	PackReader	packReader,
		uint64_t	index )

Returns Pack item uncompressed data size in bytes. (MT-Safe)

Use the returned item binary size to allocate a memory block for data reading.

Parameters

packReader	pack reader instance
index	uint64_t item index

Returns

The data binary size.

Return values

Integer

between 1 and 4,294,967,295 (4GB)

getPackItemZipSize()

uint32_t getPackItemZipSize	(	PackReader	packReader,
		uint64_t	index )

Returns Pack item compressed data size in bytes. (MT-Safe)

You can use the returned item zipped binary size for statistics or to determine if it is compressed.

Parameters

packReader	pack reader instance
index	uint64_t item index

Returns

The data binary size, or 0 if item is not compressed.

Return values

Integer	between 1 and 4,294,967,295 if compressed. (4GB)
0	if item is not compressed

readPackItemData()

PackResult readPackItemData	(	PackReader	packReader,
		uint64_t	itemIndex,
		uint8_t *	buffer,
		uint32_t	threadIndex )

Reads Pack item binary data. (MT-Safe)

The main function for loading item data from a file into memory. Additionally, we can pass the index of the current thread and load the data asynchronously.

Parameters

	packReader	pack reader instance
	itemIndex	uint64_t item index
[out]	buffer	target buffer where to read the item data
	threadIndex	current thread index or 0

Returns

The PackResult code and writes reader instance on success.

Return values

SUCCESS_PACK_RESULT	- successful operation
FAILED_TO_ALLOCATE_PACK_RESULT	- out of memory
FAILED_TO_READ_FILE_PACK_RESULT	- failed to read Pack file data
FAILED_TO_SEEK_FILE_PACK_RESULT	- failed to seek Pack file data
FAILED_TO_DECOMPRESS_PACK_RESULT	- compressed file data is damaged

getPackItemFileOffset()

uint64_t getPackItemFileOffset	(	PackReader	packReader,
		uint64_t	index )

Returns Pack item data offset in the archive file. (MT-Safe)

Internally used to read an item data from the archive file.

Parameters

packReader	pack reader instance
index	uint64_t item index

Returns

The data offset in the file.

isPackItemReference()

bool isPackItemReference	(	PackReader	packReader,
		uint64_t	index )

Returns true if pack item is a reference to a duplicate item. (MT-Safe)

Internally Pack shares binary data block between the same items.

Parameters

packReader	pack reader instance
index	uint64_t item index

Returns

True if item is a reference, otherwise false.

getPackItemPath()

const char * getPackItemPath	(	PackReader	packReader,
		uint64_t	index )

Returns Pack item path string. (MT-Safe)

You can get the Pack item path when iterating over all items.

Warning

You should not free the returned string.

Parameters

packReader	pack reader instance
index	uint64_t item index

Returns

The Pack item path sting.

getPackZstdContexts()

void **const getPackZstdContexts

(

PackReader

packReader

)

Returns Pack ZSTD context array. (MT-Safe)

Can be used to share the ZSTD contexts in the program.

Parameters

packReader

pack reader instance

Returns

Array of the ZSTD_DCtx* contexts.

unpackFiles()

PackResult unpackFiles	(	const char *	filePath,
		bool	printProgress )

Unpacks files from the pack. (MT-Safe)

This function is useful when we need to create a unpacker for debugging a program.

Parameters

[in]	filePath	target Pack file path string
	printProgress	output unpacking progress to the stdout

Returns

The PackResult code.