| CRM64Pro GDK v0.19.0 A free cross-platform game development kit built on top of SDL 3.0

Loading...
Searching...
No Matches
CRM64Pro::Archivefinal
Core modules » Archive

Archive Object class. More...

## 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.

Parameters

  pUser | Opaque user data supplied to blockAddStream().
  pBuffer | Destination buffer valid only for the duration of the callback.
  iMaxBytes | Maximum number of bytes that may be copied to pBuffer.

Returns
  Number of bytes copied, 0 at 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).