The interface for cross-platform CloudStorage file management. More...

#include <ICloudStorage.h>

Public Types
enum	ReadPhase { CHECKSUM_CALCULATING , UPLOADING }
	The phase of reading data to be uploaded. More...

typedef int(*	WriteFunc) (void userParam, const char data, int size)
	Function used to write the downloaded data. More...

typedef int(*	ReadFunc) (void userParam, char data, int size)
	Function used to read the data to be uploaded. More...

typedef int(*	RewindFunc) (void *userParam, ReadPhase phase)
	Function used to restart read data process. More...

Public Member Functions
virtual void	GetFileList (const char container, ICloudStorageGetFileListListener listener)=0
	Function used to get a list of files stored in cloud storage. More...

virtual const char *	GetFileNameByIndex (uint32_t index) const =0
	Function used to get a file name from the retrieved list of files stored in cloud storage. More...

virtual uint32_t	GetFileSizeByIndex (uint32_t index) const =0
	Function used to get a file size from the retrieved list of files stored in cloud storage. More...

virtual uint32_t	GetFileTimestampByIndex (uint32_t index) const =0
	Function used to get a file timestamp from the retrieved list of files stored in cloud storage. More...

virtual const char *	GetFileHashByIndex (uint32_t index) const =0
	Function used to get a file hash from the retrieved list of files stored in cloud storage. More...

virtual void	GetFile (const char container, const char name, void userParam, WriteFunc writeFunc, ICloudStorageGetFileListener listener)=0
	Download a file from cloud storage. More...

virtual void	GetFile (const char container, const char name, void dataBuffer, uint32_t bufferLength, ICloudStorageGetFileListener listener)=0
	Download a file from cloud storage. More...

virtual void	GetFileMetadata (const char container, const char name, ICloudStorageGetFileListener *listener)=0
	Get a file metadata from cloud storage. More...

virtual void	PutFile (const char container, const char name, void userParam, ReadFunc readFunc, RewindFunc rewindFunc, ICloudStoragePutFileListener listener, SavegameType savegameType=SAVEGAME_TYPE_UNDEFINED, uint32_t timeStamp=0, const char *hash=NULL)=0
	Upload a file to the cloud storage. More...

virtual void	PutFile (const char container, const char name, const void buffer, uint32_t bufferLength, ICloudStoragePutFileListener listener, SavegameType savegameType=SAVEGAME_TYPE_UNDEFINED, uint32_t timeStamp=0, const char *hash=NULL)=0
	Upload a file to the cloud storage. More...

virtual void	CalculateHash (void userParam, ReadFunc readFunc, RewindFunc rewindFunc, char hashBuffer, uint32_t hashBufferSize)=0
	Calculate hash for the specified object. More...

virtual void	CalculateHash (const void buffer, uint32_t bufferLength, char hashBuffer, uint32_t hashBufferSize)=0
	Calculate hash for the specified object. More...

virtual void	DeleteFile (const char container, const char name, ICloudStorageDeleteFileListener listener, const char expectedHash=NULL)=0
	Delete a file from cloud storage. More...

virtual void	OpenSavegame ()=0
	Starts new savegame. More...

virtual void	CloseSavegame ()=0
	Closes savegame. More...

Static Public Attributes
static const uint32_t	MIN_HASH_BUFFER_SIZE = 33
	Minimum size of the hashBuffer in CalculateHash method.

Detailed Description

The interface for cross-platform CloudStorage file management.

Member Typedef Documentation

◆ ReadFunc

typedef int(* ReadFunc) (void *userParam, char *data, int size)

Function used to read the data to be uploaded.

Parameters

[in]	userParam	The parameter passed to the PutFile() method.
[in]	data	The buffer for the data read.
[in]	size	The size of the buffer for data.

Returns: Number of bytes read: 0 (for size > 0) means end-of-data (no more data to read); a negative value indicates an error.

◆ RewindFunc

typedef int(* RewindFunc) (void *userParam, ReadPhase phase)

Function used to restart read data process.

This function will be called at the beginning of the two read phases: checksum calculation and reading data upon uploading.

Parameters

[in]	userParam	The parameter passed to the PutFile() method.
[in]	phase	Reading phase.

Returns: Zero on success, non zero on error.

◆ WriteFunc

typedef int(* WriteFunc) (void *userParam, const char *data, int size)

Function used to write the downloaded data.

Parameters

[in]	userParam	The parameter passed to the GetFile() method.
[in]	data	The downloaded data to be written.
[in]	size	The size of the downloaded data to be written.

Returns: Number of bytes written; a negative value indicates an error.

Member Enumeration Documentation

◆ ReadPhase

enum ReadPhase

The phase of reading data to be uploaded.

Enumerator
CHECKSUM_CALCULATING	Checksum calculating phase.
UPLOADING	Uploading phase.

Member Function Documentation

◆ CalculateHash() [1/2]

virtual void CalculateHash	(	const void *	buffer,
		uint32_t	bufferLength,
		char *	hashBuffer,
		uint32_t	hashBufferSize
	)

pure virtual

Calculate hash for the specified object.

This call is synchronous and may be time consuming.

This version of the CalculateHash method uploads the data pointed by the buffer parameter, where bufferLength indicates the file length.

Parameters

[in]	buffer	The buffer for the data to be read.
[in]	bufferLength	The size of the buffer for the data.
[in,out]	hashBuffer	The buffer for the calculated hash. Should be at least MIN_HASH_BUFFER_SIZE long.
[in]	hashBufferSize	The size of the buffer for the calculated hash.

◆ CalculateHash() [2/2]

virtual void CalculateHash	(	void *	userParam,
		ReadFunc	readFunc,
		RewindFunc	rewindFunc,
		char *	hashBuffer,
		uint32_t	hashBufferSize
	)

pure virtual

Calculate hash for the specified object.

This call is synchronous and may be time consuming.

This version of the CalculateHash method uses (userParam, readFunc) parameters as an abstraction of a data source for the uploaded data. readFunc will be called with userParam passed to the method along with the buffer for the data to be read. rewindFunc will be called on start reading data phase and should set the read pointer at the begining of the data stream.

Parameters

[in]	userParam	The parameter passed to readFunc on every call.
[in]	readFunc	The function called to obtain data chunks for upload.
[in]	hashBuffer	The buffer for calculated hash. Should be at least MIN_HASH_BUFFER_SIZE long.
[in,out]	hashBufferSize	The size of buffer for calculated hash.
[in]	rewindFunc	The function called to rewind read pointer to the begining of the data stream.

◆ CloseSavegame()

virtual void CloseSavegame ( )

pure virtual

Closes savegame.

After this call all subsequently stored files will have a different unique savegame ID.

◆ DeleteFile()

virtual void DeleteFile	(	const char *	container,
		const char *	name,
		ICloudStorageDeleteFileListener *	listener,
		const char *	expectedHash = `NULL`
	)

pure virtual

Delete a file from cloud storage.

This call is asynchronous. Responses come to the ICloudStorageDeleteFileListener.

Optional parameter expectedHash enforces checking if the file has the same hash as expected. This prevents removing a file in case it was changed in the meantime.

Parameters

[in]	container	The name of the containter.
[in]	name	The name of the file in cloud storage.
[in]	listener	The listener for the specific operation.
[in]	expectedHash	The expected hash of a file to be deleted.

◆ GetFile() [1/2]

virtual void GetFile	(	const char *	container,
		const char *	name,
		void *	dataBuffer,
		uint32_t	bufferLength,
		ICloudStorageGetFileListener *	listener
	)

pure virtual

Download a file from cloud storage.

This call is asynchronous. Responses come to the ICloudStorageGetFileListener.

This version of the GetFile method uses the buffer and bufferLength parameters to store the downloaded data. The buffer should be big enough to fit the whole file. Required size can be obtained by GetFileList().

Caller is responsible for setting up a lifetime for the buffer: it should be accessible until the operation is finished (any of the listener methods is called).

Parameters

[in]	container	The name of the containter.
[in]	name	The name of the file in cloud storage.
[in]	dataBuffer	The buffer for the downloaded data.
[in]	bufferLength	The size of the buffer for the downloaded data.
[in]	listener	The listener for the specific operation.

◆ GetFile() [2/2]

virtual void GetFile	(	const char *	container,
		const char *	name,
		void *	userParam,
		WriteFunc	writeFunc,
		ICloudStorageGetFileListener *	listener
	)

pure virtual

Download a file from cloud storage.

This call is asynchronous. Responses come to the ICloudStorageGetFileListener.

This version of the GetFile method uses (userParam, writeFunc) parameters as an abstraction of a data sink for the downloaded data. writeFunc will be called with userParam passed to the method along with the data to be written.

Parameters

[in]	container	The name of the containter.
[in]	name	The name of the file in cloud storage.
[in]	userParam	The parameter passed to writeFunc on every call.
[in]	writeFunc	The function called for chunks of the downloaded data.
[in]	listener	The listener for specific operation.

◆ GetFileHashByIndex()

virtual const char* GetFileHashByIndex ( uint32_t index ) const

pure virtual

Function used to get a file hash from the retrieved list of files stored in cloud storage.

Call for this function is allowed inside ICloudStorageGetFileListListener::OnGetFileListSuccess() only.

Parameters

[in] index Index of the file on the list.

Returns: Hash of the file (as hexadecimal string).

◆ GetFileList()

virtual void GetFileList	(	const char *	container,
		ICloudStorageGetFileListListener *	listener
	)

pure virtual

Function used to get a list of files stored in cloud storage.

This call is asynchronous. Responses come to the ICloudStorageGetFileListListener.

Parameters

[in]	container	The name of the containter.
[in]	listener	The listener for specific operation.

◆ GetFileMetadata()

virtual void GetFileMetadata	(	const char *	container,
		const char *	name,
		ICloudStorageGetFileListener *	listener
	)

pure virtual

Get a file metadata from cloud storage.

This call is asynchronous. Responses come to the ICloudStorageGetFileListener.

This method gets metadata for specified file only.

Parameters

[in]	container	The name of the containter.
[in]	name	The name of the file in cloud storage.
[in]	listener	The listener for specific operation.

◆ GetFileNameByIndex()

virtual const char* GetFileNameByIndex ( uint32_t index ) const

pure virtual

Function used to get a file name from the retrieved list of files stored in cloud storage.

Call for this function is allowed inside ICloudStorageGetFileListListener::OnGetFileListSuccess() only.

Parameters

[in] index Index of the file on the list.

Returns: Name of the file. This pointer is valid inside ICloudStorageGetFileListListener::OnGetFileListSuccess() only.

◆ GetFileSizeByIndex()

virtual uint32_t GetFileSizeByIndex ( uint32_t index ) const

pure virtual

Function used to get a file size from the retrieved list of files stored in cloud storage.

Call for this function is allowed inside ICloudStorageGetFileListListener::OnGetFileListSuccess() only.

Parameters

[in] index Index of the file on the list.

Returns: Size of the file.

◆ GetFileTimestampByIndex()

virtual uint32_t GetFileTimestampByIndex ( uint32_t index ) const

pure virtual

Function used to get a file timestamp from the retrieved list of files stored in cloud storage.

Call for this function is allowed inside ICloudStorageGetFileListListener::OnGetFileListSuccess() only.

Parameters

[in] index Index of the file on the list.

Returns: Timestamp of the file (Unix timestamp).

◆ OpenSavegame()

virtual void OpenSavegame ( )

pure virtual

Starts new savegame.

After this call all subsequently stored files will have the same unique savegame ID.

◆ PutFile() [1/2]

virtual void PutFile	(	const char *	container,
		const char *	name,
		const void *	buffer,
		uint32_t	bufferLength,
		ICloudStoragePutFileListener *	listener,
		SavegameType	savegameType = `SAVEGAME_TYPE_UNDEFINED`,
		uint32_t	timeStamp = `0`,
		const char *	hash = `NULL`
	)

pure virtual

Upload a file to the cloud storage.

This call is asynchronous. Responses come to the ICloudStoragePutFileListener.

This version of the PutFile method uploads the data pointed by the buffer parameter, where bufferLength indicates the file length.

Caller is responsible for setting up a lifetime for the buffer: it should be accessible until the operation is finished (any of the listener methods is called).

Parameters

[in]	container	The name of the containter.
[in]	name	The name of the file in cloud storage.
[in]	buffer	The buffer for the data to be read.
[in]	bufferLength	The size of the buffer for the data.
[in]	listener	The listener for the specific operation.
[in]	savegameType	The type of the savegame.
[in]	timeStamp	The timestamp of the uploaded object. Current time will be set by default.
[in]	hash	The precalculated hash (see ICloudStorage::CalculateHash() method). Will be calculated internally if ommited (NULL or empty string).

◆ PutFile() [2/2]

virtual void PutFile	(	const char *	container,
		const char *	name,
		void *	userParam,
		ReadFunc	readFunc,
		RewindFunc	rewindFunc,
		ICloudStoragePutFileListener *	listener,
		SavegameType	savegameType = `SAVEGAME_TYPE_UNDEFINED`,
		uint32_t	timeStamp = `0`,
		const char *	hash = `NULL`
	)

pure virtual

Upload a file to the cloud storage.

This call is asynchronous. Responses come to the ICloudStoragePutFileListener.

This version of the PutFile method uses (userParam, readFunc) parameters as an abstraction of a data source for the uploaded data. readFunc will be called with userParam passed to the method along with the buffer for the data to be read. rewindFunc will be called on start reading data phase and should set the read pointer at the begining of the data stream.

Parameters

[in]	container	The name of the containter.
[in]	name	The name of the file in cloud storage.
[in]	userParam	The parameter passed to readFunc and rewindFunc on every call.
[in]	readFunc	The function called to obtain data chunks for upload.
[in]	rewindFunc	The function called to rewind read pointer to the begining of the data stream.
[in]	listener	The listener for the specific operation.
[in]	savegameType	The type of the savegame.
[in]	timeStamp	The timestamp of the uploaded object. Current time will be set by default.
[in]	hash	The precalculated hash (see ICloudStorage::CalculateHash() method). Will be calculated internally if ommited (NULL or empty string).

Public Types

Public Member Functions

Static Public Attributes

Detailed Description

Member Typedef Documentation

◆ ReadFunc

◆ RewindFunc

◆ WriteFunc

Member Enumeration Documentation

◆ ReadPhase

Member Function Documentation

◆ CalculateHash() [1/2]

◆ CalculateHash() [2/2]

◆ CloseSavegame()

◆ DeleteFile()

◆ GetFile() [1/2]

◆ GetFile() [2/2]

◆ GetFileHashByIndex()

◆ GetFileList()

◆ GetFileMetadata()

◆ GetFileNameByIndex()

◆ GetFileSizeByIndex()

◆ GetFileTimestampByIndex()

◆ OpenSavegame()

◆ PutFile() [1/2]

◆ PutFile() [2/2]