![]() |
CRM64Pro GDK
v0.97
A free cross-platform game development kit built on top of SDL 2.0
|
Classes | |
class | CRM64Pro::Archive |
class | CRM64Pro::ArchiveMgr |
Macros | |
#define | CDCv1_sPARAM1 64 |
#define | CDCv1_sPARAM2 16 |
CDC format is an extensible and open data container definition based on data blocks. It was designed to be used with CRM64Pro GDK and is the successor of the old DPF format developed for CRM32Pro SDK.
The CDC only defines a minimum magic header(8 bytes) which contains the CDC implementation version and a set of methods that create the interface. These methods are shown on below table.
For the time being, there is only one implementation of the CDC format, it is called CDCv1.1 with the following features:
CDC interface definition | CDC v1.1 implementation details |
load() | At CDC loading time, it checks for IO data corruption. |
save() | Automatically called after a new data block is successfully added. |
blockAdd() | Add a new data block: - if an identical (same type, name and payload) data block exists, does nothing - or... if the block already exists (same type and name), before performing a "soft" deletion, it tries to overwrite the payload if fits - of... if it is a new block, just add it |
blockAddFile() | Add a file into a block. Follows the same rules as blockAdd(). The block name is the [directory]+filename+[extension] added and the block type is "C64_FILE". |
blockLoad() | Load the data block. Note that "soft" deleted data blocks are not loaded. |
blockSearch() | data block search is extremely fast due to the fixed index of the CDC. |
blockAt() | Accessing to a random data blocks is extremely fast due to the fixed index of the CDC. |
blockDelete() | Perform a "soft" deletion of the data block. It can not be loaded but physically is present. |
blockUndelete() | Recover a "soft" deleted data block. |
getNumberOfBlocks() | Get the number of data blocks. |
getFragmentation() | Due to the "soft" deletion of data blocks and block overwritten feature, the CDC can be fragmented. |
defrag() | Perform a physical deletion of the "soft" deleted data blocks and keep the file free of fragmentation.It also resizes the size of maximum data blocks. |
secure() | Encrypt the index using AES-256 algorithm to disallow the access to the data blocks. Key size must be from 4 up to 32 bytes. |
unSecure() | Decrypt the index using the valid password. It is very important to remember the password or there is no way to recover all data blocks. |
The Archive Manager encapsulates the CDC definition, CDCv1.1 implementation and some useful features for managing these files.
This is a sharing manager: it has the ability of sharing a CDC id to a group of owners when they request to open an already opened file based on the file path [directory]+file+[extension] as the key. When the last one of them closes the CDC id, it will be effectively closed.
Only a single instance of the Archive Manager exists which is created once Main is instantiated.
You can get a reference to this manager using Main::IArchiveMgr() method.
#define CDCv1_sPARAM1 64 |
CDC v1.x: size of custom char array attribute 1
#define CDCv1_sPARAM2 16 |
CDC v1.x: size of custom char array attribute 2
Archive block storing method.
Enumerator | |
---|---|
ABS_RAW | Block is stored in raw mode. |
ABS_COMPRESSED | Block is compressed and stored. |
ABS_CRYPTED | Block is crypted and stored. |
Sint32 CRM64Pro::Archive::info | ( | Sint32 | iMode = 0 | ) |
Request CDC object information.
For displaying the information, it uses the default log.
iMode | unused for the time being. |
Sint32 CRM64Pro::Archive::getName | ( | string & | sName | ) |
Get the name.
sName | a string containing the [directory] and the file name plus the .cdc extension. |
Uint32 CRM64Pro::Archive::getID | ( | ) |
Get the ID.
Sint32 CRM64Pro::Archive::blockAdd | ( | Block & | myBlock | ) |
Add a data block.
myBlock | filled Block struct, at least it needs pData and iSize. Custom attributes depend on the CDC version. |
Sint32 CRM64Pro::Archive::blockAddFile | ( | const string & | sFile, |
eArchiveBlockStore | eABS = ABS_COMPRESSED |
||
) |
Add a file.
sFile | string containing the [directory]+filename+[extension] to be added. Directory separators '\' and '/' are supported. |
eABS | Check eArchiveBlockStore enum for further information. By default is set to ABS_COMPRESSED. |
Sint32 CRM64Pro::Archive::blockDelete | ( | Block & | myBlock | ) |
Delete a data block.
myBlock | filled Block struct with custom attributes depending on the CDC version. |
Sint32 CRM64Pro::Archive::blockUndelete | ( | Uint32 | iBlock, |
Block & | myBlock | ||
) |
Recover a deleted data block.
iBlock | block index position from [0 to used_blocks - 1] which contains a deleted data block. Use getUsedBlocks() for getting the used_blocks. |
myBlock | filled Block struct with custom attributes depending on the CDC version. pData must be nullptr. In case the block is recovered, myBlock struct will contain all its attributes but pData. |
Sint32 CRM64Pro::Archive::blockSearch | ( | Block & | myBlock | ) |
Search for a given data block.
myBlock | filled Block struct with custom attributes depending on the CDC version. In case the block is found, myBlock struct will contain all its attributes but pData. |
Sint32 CRM64Pro::Archive::blockAt | ( | Uint32 | iBlock, |
Block & | myBlock | ||
) |
Access to the given data block position.
iBlock | block index position from [0 to used_blocks - 1]. Use getUsedBlocks() for getting the used_blocks. |
myBlock | In case the block index position is found, myBlock struct will contain all its attributes but pData. |
Sint32 CRM64Pro::Archive::blockLoad | ( | Block & | myBlock | ) |
Load a data block.
myBlock | filled Block struct with custom attributes depending on the CDC version. pData must be nullptr. In case the block is found, myBlock struct will contain all its attributes plus the pData loaded. |
Sint32 CRM64Pro::Archive::blockLoadReleaseData | ( | Block & | myBlock | ) |
Free a loaded data block.
myBlock | Block struct with pData loaded by blockLoad() method. |
Uint32 CRM64Pro::Archive::getUsedBlocks | ( | ) |
Get the number of used data blocks.
Uint32 CRM64Pro::Archive::getMaxBlocks | ( | ) |
Get the number of maximum data blocks.
float CRM64Pro::Archive::getFragmentation | ( | ) |
Get the fragmentation.
Sint32 CRM64Pro::Archive::secure | ( | const unsigned char * | myKey, |
Uint32 | iKeySize | ||
) |
Secure the CDC.
myKey | unsigned char array of iKeySize containing the key. |
iKeySize | the key size on bytes. They key size range in bytes for a CDC v1.1 must be from 4 up to 32. |
Sint32 CRM64Pro::Archive::unSecure | ( | ) |
Unsecure a CDC file.
Sint32 CRM64Pro::ArchiveMgr::info | ( | Sint32 | iMode = 0 | ) |
Request Archive Manager information.
For displaying the information, it uses the default log.
iMode | -1 for displaying only Manager information. 0 for displaying Manager and all Objects information. This is the default value. idCDC for displaying Manager and given CDC id information. |
Sint32 CRM64Pro::ArchiveMgr::create | ( | const string & | sFile, |
Uint32 | iNumBlocks = 0 |
||
) |
Create a new CDC file.
sFile | string containing the [directory]+filename+[extension]. If it does not contain the extension .cdc, it is automatically added. Directory separators '\' and '/' are supported. |
iNumBlocks | Maximum number of data blocks. The minimum is 256. |
Sint32 CRM64Pro::ArchiveMgr::close | ( | Sint32 | idCDC | ) |
Close and destroy a CDC.
idCDC | 0 for closing all CDC files or the CDC id. As the Archive Manager has the ability of sharing a CDC id, if the CDC file is shared, it will not be removed till the last owner call this method. |
Sint32 CRM64Pro::ArchiveMgr::getNum | ( | ) |
Get number of loaded objects.
Archive * CRM64Pro::ArchiveMgr::get | ( | Sint32 | idCDC = 0 | ) |
Get a pointer to the CDC using its handler.
By default it returns the first CDC loaded.
idCDC | CDC id. |
Sint32 CRM64Pro::ArchiveMgr::defrag | ( | const string & | sFile, |
Uint32 | iNumBlocks = 0 |
||
) |
Defragment a CDC file.
sFile | string containing the [directory]+filename+[extension]. Directory separators '\' and '/' are supported. |
iNumBlocks | Maximum number of data blocks. The minimum is 256 and by default, is set to 0 for keeping current max block number. It is used for resizing the maximum number of data blocks. |
Sint32 CRM64Pro::ArchiveMgr::load | ( | const string & | sFile, |
const unsigned char * | myKey = nullptr , |
||
Uint32 | iKeySize = 0 |
||
) |
Load a CDC file.
The Archive Manager has the ability of sharing ids based on the file path [directory]+file+[extension] as the key, so before trying to load a new one, it checks if it is already loaded for sharing it.
sFile | string containing the [directory]+filename+[extension]. Directory separators '\' and '/' are supported. |
myKey | unsigned char array of iKeySize containing the key. It is only used when the CDC to be loaded is secured. Default value set to nullptr. |
iKeySize | from 4 to 32. 0 for loading a CDC without key (default value). |