Detailed Description

Archive Object class.

Classes
struct	Block
class	BlockStream
	Archive raw block stream. More...

Public Types
using	BlockReadCallback = Sint64()(void pUser, void* pBuffer, Uint64 iMaxBytes)

Public Member Functions
bool	info (Sint32 iMode=0) override
	Request CDC object information.
const string &	getName () const override
	Get the name.
Sint32	getID () const override
	Get the ID.
bool	isEncrypted () const
	Check if the CDC index is encrypted.
bool	isEncryptedBlocks () const
	Check if the CDC contains encrypted blocks.
bool	hasKey () const
	Check if a CDC confidentiality key is set in memory.
Sint32	blockAdd (Block &rBlock)
	Add a data block.
Sint32	blockAddStream (Block &rBlock, BlockReadCallback fnRead, void *pUser)
	Add a streamed data block.
Sint32	blockAddFile (const string &sFile, eArchiveBlockStore eABS=ABS_COMPRESSED)
	Add a file.
Sint32	blockDelete (Block &rBlock)
	Delete a data block.
Sint32	blockUndelete (Uint32 iBlock, const char *szName=nullptr)
	Recover a deleted data block.
Sint32	blockSearch (Block &rBlock)
	Search for a given data block.
Sint32	blockAt (Uint32 iBlock, Block &rBlock)
	Access to the given data block position.
Sint32	blockLoad (Block &rBlock)
	Load a data block.
Sint32	blockVerify (Block &rBlock)
	Verify a data block.
Sint32	blockFree (Block &rBlock)
	Free a loaded data block.
Sint32	blockOpenStream (Block &rBlock, BlockStream &rStream)
	Open a raw block stream.
Uint32	getBlockCount () const
	Get the number of active block entries.
Uint32	getIndexCount () const
	Get the number of used index entries.
Uint32	getBlockLimit () const
	Get the number of maximum data blocks.
float	getFragmentation () const
	Get the fragmentation.
string	getCreationDate () const
	Get the CDC creation date.
string	getModificationDate () const
	Get the CDC modification date.
Uint64	getCreationTime () const
	Get the CDC creation timestamp.
Uint64	getModificationTime () const
	Get the CDC modification timestamp.
Sint32	setKey (const Uint8 *pKey, Uint32 iKeySize)
	Set the CDC confidentiality key.
Sint32	clearKey ()
	Clear the in-memory CDC encryption key.
Sint32	encrypt ()
	Apply confidentiality to the CDC index.
Sint32	decrypt ()
	Remove confidentiality from the CDC index.

Member Typedef Documentation

◆ BlockReadCallback

using CRM64Pro::Archive::BlockReadCallback = Sint64(*)(void* pUser, void* pBuffer, Uint64 iMaxBytes)

Callback used by blockAddStream() to provide source bytes. Return the number of bytes copied into pBuffer, 0 for end of stream, or a negative error code on failure.

Member Function Documentation

◆ info()

bool CRM64Pro::Archive::info ( Sint32 iMode = 0 )

override

Request CDC object information.

Writes information to the default log.

Parameters

iMode Reserved for future use. Pass 0.

Returns: true on success, or false on failure.

◆ getName()

const string & CRM64Pro::Archive::getName ( ) const

override

Get the name.

Returns: The object name.

◆ getID()

Sint32 CRM64Pro::Archive::getID ( ) const

override

Get the ID.

Returns: Object ID.

◆ isEncrypted()

bool CRM64Pro::Archive::isEncrypted ( ) const

Check if the CDC index is encrypted.

Returns: true if the CDC index is encrypted, false otherwise.

◆ isEncryptedBlocks()

bool CRM64Pro::Archive::isEncryptedBlocks ( ) const

Check if the CDC contains encrypted blocks.

Returns: true if the CDC contains one or more active encrypted blocks, false otherwise.

◆ hasKey()

bool CRM64Pro::Archive::hasKey ( ) const

Check if a CDC confidentiality key is set in memory.

Returns: true if a key is currently set, false otherwise.

◆ blockAdd()

Sint32 CRM64Pro::Archive::blockAdd ( Block & rBlock )

Add a data block.

Parameters

rBlock filled Block struct, at least it needs pData, iSize, name and type.

Returns: 0 on success, or a negative error code on failure.

Note: Replacing or deleting a block appends new payload data and updates the index without overwriting old payload bytes.

◆ blockAddStream()

Sint32 CRM64Pro::Archive::blockAddStream	(	Block &	rBlock,
		BlockReadCallback	fnRead,
		void *	pUser )

Add a streamed data block.

Parameters

rBlock	filled Block struct with iSize, storage mode, name and type. pData is ignored.
fnRead	Callback used to provide block bytes.
pUser	User pointer passed to the callback.

Returns: 0 on success, or a negative error code on failure.

Note: The current implementation supports ABS_RAW only. The API is designed to support streamed encryption later.; Data is copied in 1 MiB chunks and the block index is updated only after the full stream has been written successfully.

◆ blockAddFile()

Sint32 CRM64Pro::Archive::blockAddFile	(	const string &	sFile,
		eArchiveBlockStore	eABS = ABS_COMPRESSED )

Add a file.

Parameters

sFile	string containing the [directory]+filename+[extension] to be added. Directory separators '\' and '/' are supported.
eABS	Check ::eArchiveBlockStore enum for details. Default is ABS_COMPRESSED.

Returns: 0 on success, or a negative error code on failure.

Note: blockAddFile() loads the whole file in memory and is limited to 1GB.

◆ blockDelete()

Sint32 CRM64Pro::Archive::blockDelete ( Block & rBlock )

Delete a data block.

Parameters

rBlock filled Block struct with block name and type.

Returns: 0 on success, or a negative error code on failure.

◆ blockUndelete()

Sint32 CRM64Pro::Archive::blockUndelete	(	Uint32	iBlock,
		const char *	szName = nullptr )

Recover a deleted data block.

Parameters

iBlock	block index position from [0 to used_index_entries - 1] which contains a deleted data block. Use getIndexCount() to get used_index_entries.
szName	optional new block name. Use nullptr or an empty string to restore the original deleted name. The original block type is always preserved.

Returns: 0 on success, or a negative error code on failure.

◆ blockSearch()

Sint32 CRM64Pro::Archive::blockSearch ( Block & rBlock )

Search for a given data block.

Parameters

rBlock filled Block struct with block name and type. If found, rBlock will contain all attributes except pData.

Returns: [0 to used_index_entries - 1] on success indicating the block index position, or a negative error code on failure. Use getIndexCount() for the used_index_entries value.

Note: Deleted blocks are not returned by this method. Use blockAt() and Block::bDeleted to enumerate deleted entries.

◆ blockAt()

Sint32 CRM64Pro::Archive::blockAt	(	Uint32	iBlock,
		Block &	rBlock )

Access to the given data block position.

Parameters

iBlock	block index position from [0 to used_index_entries - 1]. Use getIndexCount() for the used_index_entries value.
rBlock	if the block index position is found, rBlock will contain all attributes except pData.

Returns: 0 on success, or a negative error code on failure.

◆ blockLoad()

Sint32 CRM64Pro::Archive::blockLoad ( Block & rBlock )

Load a data block.

Parameters

rBlock filled Block struct with block name and type. pData must be nullptr. If found, rBlock will contain all attributes plus the pData loaded.

Returns: 0 on success, or a negative error code on failure.

Note: blockLoad() allocates decoded data into rBlock.pData. Release it with blockFree().; blockLoad() is limited to 1GB. Larger blocks must be raw, uncompressed and unencrypted, and read with blockOpenStream().

◆ blockVerify()

Sint32 CRM64Pro::Archive::blockVerify ( Block & rBlock )

Verify a data block.

Parameters

rBlock filled Block struct with block name and type. If verified, rBlock will contain all attributes except pData.

Returns: 0 on success, or a negative error code on failure.

Note: Raw, uncompressed and unencrypted blocks are verified in streaming chunks, so this method can verify blocks larger than the 1GB blockLoad() limit.

◆ blockFree()

Sint32 CRM64Pro::Archive::blockFree ( Block & rBlock )

Free a loaded data block.

Parameters

rBlock Block struct with pData previously loaded by blockLoad().

Returns: 0 on success, or a negative error code on failure.

Note: This method is safe to call when pData is already nullptr.

◆ blockOpenStream()

Sint32 CRM64Pro::Archive::blockOpenStream	(	Block &	rBlock,
		BlockStream &	rStream )

Open a raw block stream.

Parameters

rBlock	filled Block struct with block name and type. If opened, the block metadata is filled.
rStream	BlockStream object that receives the opened stream.

Returns: 0 on success, or a negative error code on failure.

Note: Only raw, uncompressed and unencrypted blocks can be streamed. Each opened stream owns an independent cursor and reads through the Archive SDL IO.; Streaming is fast raw access and does not verify block hashes while reading. Call blockVerify() when integrity verification is required.

◆ getBlockCount()

Uint32 CRM64Pro::Archive::getBlockCount ( ) const

Get the number of active block entries.

Returns: Number of active blocks, excluding deleted blocks.

◆ getIndexCount()

Uint32 CRM64Pro::Archive::getIndexCount ( ) const

Get the number of used index entries.

Returns: [0 to block_limit] the used index count, including active and deleted blocks.

Note: Use this value as the upper bound for blockAt() and blockUndelete() enumeration.

◆ getBlockLimit()

Uint32 CRM64Pro::Archive::getBlockLimit ( ) const

Get the number of maximum data blocks.

The archive grows this limit automatically when possible, and it can also be resized using defrag().

Returns: Positive maximum number (block_limit) of blocks.

◆ getFragmentation()

float CRM64Pro::Archive::getFragmentation ( ) const

Get the fragmentation.

Returns: Fragmentation percentage in the [0.0, 100.0] range. Lower values mean less fragmentation.

Note: Deleting or replacing blocks can fragment the store.

◆ getCreationDate()

string CRM64Pro::Archive::getCreationDate ( ) const

Get the CDC creation date.

Returns: Formatted UTC creation date stored in the CDC header.

◆ getModificationDate()

string CRM64Pro::Archive::getModificationDate ( ) const

Get the CDC modification date.

Returns: Formatted UTC modification date stored in the CDC header.

◆ getCreationTime()

Uint64 CRM64Pro::Archive::getCreationTime ( ) const

Get the CDC creation timestamp.

Returns: Raw creation timestamp stored in the CDC header.

◆ getModificationTime()

Uint64 CRM64Pro::Archive::getModificationTime ( ) const

Get the CDC modification timestamp.

Returns: Raw modification timestamp stored in the CDC header.

◆ setKey()

Sint32 CRM64Pro::Archive::setKey	(	const Uint8 *	pKey,
		Uint32	iKeySize )

Set the CDC confidentiality key.

Parameters

pKey	Uint8 array of iKeySize containing the key.
iKeySize	the key size in bytes. Values from 1 to 32 are accepted. The internal AES-256 key is derived from this key and the archive key salt.

Returns: 0 on success, or a negative error code on failure.

Warning: Forgetting the key will make encrypted blocks or an encrypted CDC index unreadable.

Note: Once an open archive contains an encrypted index or encrypted blocks, an already-set key cannot be replaced. Reapplying the same key is accepted.; CDCv2 uses lightweight confidentiality / non-authenticated AES-256-CTR encrypted storage and xxHash64 for fast non-cryptographic corruption checks. It does not provide authenticated encryption or tamper-proof storage.

◆ clearKey()

Sint32 CRM64Pro::Archive::clearKey ( )

Clear the in-memory CDC encryption key.

Returns: 0 on success, or a negative error code on failure.

◆ encrypt()

Sint32 CRM64Pro::Archive::encrypt ( )

Apply confidentiality to the CDC index.

The archive header and stored block payloads are left unchanged. Blocks keep their own storage mode: raw, compressed or encrypted. Index encryption provides lightweight confidentiality, not cryptographic authentication.

Returns: 0 on success, or a negative error code on failure.

Note: setKey() must be called before encrypt().

◆ decrypt()

Sint32 CRM64Pro::Archive::decrypt ( )

Remove confidentiality from the CDC index.

The archive header and stored block payloads are left unchanged.

Returns: 0 on success, or a negative error code on failure.

Note: setKey() must be called before decrypt(). Archives with encrypted indexes must be loaded with ArchiveMgr::load(file, key, keySize).

Detailed Description

Classes

Public Types

Public Member Functions

Member Typedef Documentation

◆ BlockReadCallback

Member Function Documentation

◆ info()

◆ getName()

◆ getID()

◆ isEncrypted()

◆ isEncryptedBlocks()

◆ hasKey()

◆ blockAdd()

◆ blockAddStream()

◆ blockAddFile()

◆ blockDelete()

◆ blockUndelete()

◆ blockSearch()

◆ blockAt()

◆ blockLoad()

◆ blockVerify()

◆ blockFree()

◆ blockOpenStream()

◆ getBlockCount()

◆ getIndexCount()

◆ getBlockLimit()

◆ getFragmentation()

◆ getCreationDate()

◆ getModificationDate()

◆ getCreationTime()

◆ getModificationTime()

◆ setKey()

◆ clearKey()

◆ encrypt()

◆ decrypt()