CRM64Pro GDK  v0.94
A free cross-platform game development kit built on top of SDL 2.0
Classes | Macros | Functions
Archive

Classes

class  CRM64Pro::ArchiveObj
 
class  CRM64Pro::ArchiveMgr
 

Macros

#define CDCv1_sPARAM1   64
 
#define CDCv1_sPARAM2   16
 

Functions

Sint32 CRM64Pro::ArchiveObj::info (Sint32 iMode=0)
 
Sint32 CRM64Pro::ArchiveObj::getName (string &sName)
 
Uint32 CRM64Pro::ArchiveObj::getID ()
 
Sint32 CRM64Pro::ArchiveObj::blockAdd (Block &myBlock)
 
Sint32 CRM64Pro::ArchiveObj::blockAddFile (const string &sFile, eArchiveBlockStore eABS=ABS_COMPRESSED)
 
Sint32 CRM64Pro::ArchiveObj::blockDelete (Block &myBlock)
 
Sint32 CRM64Pro::ArchiveObj::blockUndelete (Uint32 iBlock, Block &myBlock)
 
Sint32 CRM64Pro::ArchiveObj::blockSearch (Block &myBlock)
 
Sint32 CRM64Pro::ArchiveObj::blockAt (Uint32 iBlock, Block &myBlock)
 
Sint32 CRM64Pro::ArchiveObj::blockLoad (Block &myBlock)
 
Sint32 CRM64Pro::ArchiveObj::blockLoadReleaseData (Block &myBlock)
 
Uint32 CRM64Pro::ArchiveObj::getUsedBlocks ()
 
Uint32 CRM64Pro::ArchiveObj::getMaxBlocks ()
 
float CRM64Pro::ArchiveObj::getFragmentation ()
 
Sint32 CRM64Pro::ArchiveObj::secure (const unsigned char *myKey, Uint32 iKeySize)
 
Sint32 CRM64Pro::ArchiveObj::unSecure ()
 
Sint32 CRM64Pro::ArchiveMgr::info (Sint32 iMode=0)
 
Sint32 CRM64Pro::ArchiveMgr::create (const string &sFile, Uint32 iNumBlocks=0)
 
Sint32 CRM64Pro::ArchiveMgr::close (Sint32 idCDC)
 
Sint32 CRM64Pro::ArchiveMgr::getNum ()
 
ArchiveObj * CRM64Pro::ArchiveMgr::get (Sint32 idCDC=0)
 
Sint32 CRM64Pro::ArchiveMgr::defrag (const string &sFile, Uint32 iNumBlocks=0)
 
Sint32 CRM64Pro::ArchiveMgr::load (const string &sFile, const unsigned char *myKey=nullptr, Uint32 iKeySize=0)
 

Detailed Description

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

Note
The Archive Manager is automatically released when Main::Terminate() is called.
At this time, if any resource is still loaded, it will be released avoding a resource leak.

Macro Definition Documentation

#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

Enumeration Type Documentation

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.

Function Documentation

Sint32 CRM64Pro::ArchiveObj::info ( Sint32  iMode = 0)

Request CDC object information.

For displaying the information, it uses the default log.

Parameters
iModeunused for the time being.
Returns
0 on success or a negative error code on failure.
Sint32 CRM64Pro::ArchiveObj::getName ( string &  sName)

Get the name.

Parameters
sNamea string containing the [directory] and the file name plus the .cdc extension.
Returns
0 on success or a negative error code on failure.
Uint32 CRM64Pro::ArchiveObj::getID ( )

Get the ID.

Returns
the object ID.
Sint32 CRM64Pro::ArchiveObj::blockAdd ( Block myBlock)

Add a data block.

Parameters
myBlockfilled Block struct, at least it needs pData and iSize.
Custom attributes depend on the CDC version.
Returns
0 on success or a negative error code on failure.
Note
The exact behaviour of this method depends on the CDC version.
Please check the CDC implementation description on ArchiveMgr Detailed Description.
Sint32 CRM64Pro::ArchiveObj::blockAddFile ( const string &  sFile,
eArchiveBlockStore  eABS = ABS_COMPRESSED 
)

Add a file.

Parameters
sFilestring containing the [directory]+filename+[extension] to be added.
Directory separators '\' and '/' are supported.
eABSCheck eArchiveBlockStore enum for further information.
By default is set to ABS_COMPRESSED.
Returns
0 on success or a negative error code on failure.
Note
The exact behaviour of this method depends on the CDC version.
Please check the CDC implementation description on ArchiveMgr Detailed Description.
Sint32 CRM64Pro::ArchiveObj::blockDelete ( Block myBlock)

Delete a data block.

Parameters
myBlockfilled Block struct with custom attributes depending on the CDC version.
Returns
0 on success or a negative error code on failure.
Note
The exact behaviour of this method depends on the CDC version.
Please check the CDC implementation description on ArchiveMgr Detailed Description.
Sint32 CRM64Pro::ArchiveObj::blockUndelete ( Uint32  iBlock,
Block myBlock 
)

Recover a deleted data block.

Parameters
iBlockblock index position from [0 to used_blocks - 1] which contains a deleted data block.
Use getUsedBlocks() for getting the used_blocks.
myBlockfilled 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.
Returns
0 on success or a negative error code on failure.
Note
The exact behaviour of this method depends on the CDC version.
Please check the CDC implementation description on ArchiveMgr Detailed Description.
Sint32 CRM64Pro::ArchiveObj::blockSearch ( Block myBlock)

Search for a given data block.

Parameters
myBlockfilled 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.
Returns
[0 to used_blocks - 1] on success indicating the block index position or a negative error code on failure.
Use getUsedBlocks() for getting the used_blocks.
Note
The exact behaviour of this method depends on the CDC version.
Please check the CDC implementation description on ArchiveMgr Detailed Description.
Sint32 CRM64Pro::ArchiveObj::blockAt ( Uint32  iBlock,
Block myBlock 
)

Access to the given data block position.

Parameters
iBlockblock index position from [0 to used_blocks - 1].
Use getUsedBlocks() for getting the used_blocks.
myBlockIn case the block index position is found, myBlock struct will contain all its attributes but pData.
Returns
0 on success or a negative error code on failure.
Note
The exact behaviour of this method depends on the CDC version.
Please check the CDC implementation description on ArchiveMgr Detailed Description.
Sint32 CRM64Pro::ArchiveObj::blockLoad ( Block myBlock)

Load a data block.

Parameters
myBlockfilled 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.
Returns
0 on success or a negative error code on failure.
Note
The exact behaviour of this method depends on the CDC version.
Please check the CDC implementation description on ArchiveMgr Detailed Description.
Sint32 CRM64Pro::ArchiveObj::blockLoadReleaseData ( Block myBlock)

Free a loaded data block.

Parameters
myBlockBlock struct with pData loaded by blockLoad() method.
Returns
always return 0.
Uint32 CRM64Pro::ArchiveObj::getUsedBlocks ( )

Get the number of used data blocks.

Returns
[0 to max_blocks] the number of used blocks(used_blocks).
Uint32 CRM64Pro::ArchiveObj::getMaxBlocks ( )

Get the number of maximum data blocks.

Returns
a positive value with the maximum number(max_blocks) of blocks.
float CRM64Pro::ArchiveObj::getFragmentation ( )

Get the fragmentation.

Returns
float value in [0-100] range expressed in percentage (the lower, the better as less fragmentation is present) or a negative error code on failure.
Note
Depending on the CDC version, the storing method can produce fragmentation when some blocks are deleted or not.
The exact behaviour of this method depends on the CDC version.
Please check the CDC implementation description on ArchiveMgr Detailed Description.
Sint32 CRM64Pro::ArchiveObj::secure ( const unsigned char *  myKey,
Uint32  iKeySize 
)

Secure the CDC.

Parameters
myKeyunsigned char array of iKeySize containing the key.
iKeySizethe key size on bytes. They key size range in bytes for a CDC v1.1 must be from 4 up to 32.
Returns
0 on success or a negative error code on failure.
Warning
Securing a CDC file and forgetting the key will cause the incapability to read its content.
Note
The exact behaviour of this method depends on the CDC version.
Please check the CDC implementation description on ArchiveMgr Detailed Description.
Sint32 CRM64Pro::ArchiveObj::unSecure ( )

Unsecure a CDC file.

Returns
0 on success or a negative error code on failure.
Note
The exact behaviour of this method depends on the CDC version. Please check the CDC implementation description on ArchiveMgr Detailed Description.
Sint32 CRM64Pro::ArchiveMgr::info ( Sint32  iMode = 0)

Request Archive Manager information.

For displaying the information, it uses the default log.

Parameters
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.
Returns
0 on success or a negative error code on failure.
Sint32 CRM64Pro::ArchiveMgr::create ( const string &  sFile,
Uint32  iNumBlocks = 0 
)

Create a new CDC file.

Parameters
sFilestring containing the [directory]+filename+[extension].
If it does not contain the extension .cdc, it is automatically added.
Directory separators '\' and '/' are supported.
iNumBlocksMaximum number of data blocks. The minimum is 256.
Returns
greater than 0 on success(the CDC id) or a negative error code on failure.
Note
If the provided file name already exists, it does nothing and return an error code.
Different CDC versions could be available but at creation time, we always use the newer one available although older ones can still be loaded.
Sint32 CRM64Pro::ArchiveMgr::close ( Sint32  idCDC)

Close and destroy a CDC.

Parameters
idCDC0 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.
Returns
0 on success or a negative error code on failure.
Note
If you forget to close a CDC file, it will be automatically closed once the GDK is terminated.
Sint32 CRM64Pro::ArchiveMgr::getNum ( )

Get number of loaded objects.

Returns
the number of CDC files.
ArchiveObj * CRM64Pro::ArchiveMgr::get ( Sint32  idCDC = 0)

Get a pointer to the CDC using its handler.

By default it returns the first CDC loaded.

Parameters
idCDCCDC id.
Returns
nullptr the CDC was not found.
A pointer to the CDC object.
Sint32 CRM64Pro::ArchiveMgr::defrag ( const string &  sFile,
Uint32  iNumBlocks = 0 
)

Defragment a CDC file.

Parameters
sFilestring containing the [directory]+filename+[extension].
Directory separators '\' and '/' are supported.
iNumBlocksMaximum 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.
Returns
0 on success or a negative error code on failure.
Note
Depending on the CDC version, the storing method can produce fragmentation when some blocks are deleted.
For defragmenting a CDC file, it must be closed and unsecured.
The exact behaviour of this method depends on the CDC version.
Please check the CDC implementation description on ArchiveMgr Detailed Description.
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.

Parameters
sFilestring containing the [directory]+filename+[extension].
Directory separators '\' and '/' are supported.
myKeyunsigned char array of iKeySize containing the key.
It is only used when the CDC to be loaded is secured. Default value set to nullptr.
iKeySizefrom 4 to 32. 0 for loading a CDC without key (default value).
Returns
greater than 0 on success(the CDC id) or a negative error code on failure.