CRM64Pro::ArchiveMgr

Archive Manager class. More...

Public Member Functions
bool	info (Sint32 iMode=0) override
	Request Archive Manager information.
Sint32	create (const string &sFile, Uint32 iNumBlocks=0) override
	Create a new CDC file.
Sint32	close (Sint32 idCDC) override
	Close and destroy a CDC object.
Sint32	getCount () const override
	Get number of loaded objects.
Sint32	setName (Sint32 idCDC, const string &sName) override
	Rename is not supported for ArchiveMgr objects.
Archive *	get (Sint32 idCDC)
	Get a pointer to the CDC using its handle.
Sint32	validate (Sint32 idCDC=0, bool bDeep=false)
	Validate a CDC file.
Sint32	defrag (const string &sFile, Uint32 iNumBlocks=0, const Uint8 *pKey=nullptr, Uint32 iKeySize=0)
	Defragment a CDC file.
Sint32	load (const string &sFile, eArchiveOpenMode eMode=AOM_READ_ONLY, const Uint8 *pKey=nullptr, Uint32 iKeySize=0)
	Load a CDC file.

Detailed Description

Archive Manager class.

Member Function Documentation

info()

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

override

Request Archive Manager information.

Writes manager information to the default log.

Parameters

iMode

-1 to display only manager information. 0 (default) to display manager and all objects. A specific object ID displays manager information and only that object.

Returns

true on success, or false on failure.

create()

Sint32 CRM64Pro::ArchiveMgr::create ( const string & sFile, Uint32 iNumBlocks = 0 )

override

Create a new CDC file.

Parameters

sFile	string containing [directory]+filename+[extension]. The .cdc extension is added automatically if missing. Directory separators '\' and '/' are supported.
iNumBlocks	Maximum number of data blocks. Values below the CDCv2 default capacity use the default capacity.

Returns

Greater than 0 on success (the CDC id), or a negative error code on failure.

Note

If the file already exists, returns an error. New CDCs use the CDCv2 format and remain open in AOM_READ_WRITE mode.

close()

Sint32 CRM64Pro::ArchiveMgr::close ( Sint32 idCDC )

override

Close and destroy a CDC object.

Parameters

idCDC

0 to force-close all loaded CDCs, or a specific CDC id.

Returns

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

Note

close(idCDC) is reference-counted for shared CDCs loaded more than once; it releases one shared reference before destroying the object. If CDC-backed videos or user-held BlockStream objects are still using the CDC, the Archive stays alive until those streams are closed.

close(0) follows the manager close-all convention and releases every loaded CDC owner reference. CDC-backed videos are closed first so their active block streams are released in order, which invalidates previously returned Video ids and pointers for those videos. Archives with user-held BlockStream objects remain alive until those streams are closed.

If you forget to close a CDC, it will be automatically closed once the GDK is terminated.

getCount()

Sint32 CRM64Pro::ArchiveMgr::getCount ( ) const

override

Get number of loaded objects.

Returns

the number of CDC files.

setName()

Sint32 CRM64Pro::ArchiveMgr::setName ( Sint32 idCDC, const string & sName )

override

Rename is not supported for ArchiveMgr objects.

Parameters

idCDC	Unused.
sName	Unused.

Returns

Always returns a negative error code because archive names are file-backed.

get()

Archive * CRM64Pro::ArchiveMgr::get

(

Sint32

idCDC

)

Get a pointer to the CDC using its handle.

Parameters

idCDC

CDC id. Passing 0 returns the first loaded CDC.

Returns

Borrowed pointer to the Archive object, or nullptr if not found.

Note

The returned pointer must not be deleted. It remains valid until the CDC is closed or ArchiveMgr is reset or terminated.

validate()

Sint32 CRM64Pro::ArchiveMgr::validate	(	Sint32	idCDC = 0,
		bool	bDeep = false )

Validate a CDC file.

Parameters

idCDC	0 for the first opened CDC or the CDC id.
bDeep	false for structural validation, true to also verify active stored payload hashes and plaintext hashes when possible.

Returns

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

defrag()

Sint32 CRM64Pro::ArchiveMgr::defrag	(	const string &	sFile,
		Uint32	iNumBlocks = 0,
		const Uint8 *	pKey = nullptr,
		Uint32	iKeySize = 0 )

Defragment a CDC file.

Parameters

sFile	string containing [directory]+filename+[extension]. Directory separators '\' and '/' are supported.
iNumBlocks	Maximum number of data blocks. Default 0 preserves the current block limit. Non-zero values can be used to resize the maximum number of data blocks.
pKey	key required when defragmenting a CDC with an encrypted index.
iKeySize	size in bytes of pKey. Values from 1 to 32 are accepted when pKey is provided.

Returns

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

Note

The storing method can produce fragmentation when blocks are deleted or replaced. The CDC file must be closed in this manager to defragment. The writer lock is held through the complete file replacement.

load()

Sint32 CRM64Pro::ArchiveMgr::load	(	const string &	sFile,
		eArchiveOpenMode	eMode = AOM_READ_ONLY,
		const Uint8 *	pKey = nullptr,
		Uint32	iKeySize = 0 )

Load a CDC file.

The Archive Manager shares ids by file path and opening mode. Read-only and writable opens use separate objects and indexes. If the CDC is already loaded, the supplied key must be compatible with the open CDC. Encrypted CDC files require the same key for every shared open. Unencrypted CDC files can be shared without a key, but a different key is rejected when the already opened CDC has a key attached.

Parameters

sFile	string containing [directory]+filename+[extension]. Directory separators '\' and '/' are supported.
eMode	AOM_READ_ONLY by default; use AOM_READ_WRITE for editors, settings and other save operations.
pKey	Uint8 array containing the key. Required when the CDC index is encrypted.
iKeySize	key size in bytes. Values from 1 to 32 are accepted when pKey is provided.

Returns

Greater than 0 on success (the CDC id), or a negative error code on failure.

Note

Read-only opens never request write access. Writable opens fail if write access or the writer lock cannot be obtained.

Each read-only object retains its loaded index until its final owner and stream release it. External changes are not detected or reloaded. A new open during a save can fail validation because the current format rewrites its index in place.

Writable filesystem archives use an exclusive archive.cdc.lock sidecar on Windows, macOS, Linux and Android. The lock remains until the writable object is destroyed. A crashed writer can leave a stale lock: remove it manually only after confirming no writer is active. Use one filesystem path per archive, symlink/hard-link aliases and network filesystems are outside this locking contract.

Android packaged assets and content URIs may be read through SDL. Writing requires a normal writable filesystem path, such as application storage, content URIs are not supported for writing.