/**
 * @file	UplaySaveGame.h 
 * @brief	The Uplay PC Save Game API
 */
#ifndef UPLAY_SAVE_H
#define UPLAY_SAVE_H

#include "Uplay/UplayOverlapped.h"
#include "Uplay/UplayTypes.h"

#if _MSC_VER > 1000
#pragma once
#endif

#ifndef UPLAY_API
#ifdef _WIN32
#if defined EXPORTING_DLL
#define UPLAY_API __declspec(dllexport)
#elif defined IMPORTING_DLL
#define UPLAY_API __declspec(dllimport)
#else 
#define UPLAY_API
#endif
#endif // _Win32

#ifdef __APPLE__
#define UPLAY_API __attribute__((visibility("default")))
#define __cdecl
#endif // __APPLE__
#endif // UPLAY_API


#ifdef __cplusplus
extern "C"
{
#endif // __cplusplus	

/**
 * @defgroup	savegame	Save Game
 * @brief		Functions for the save game subsystem
 * @note		Save game ids starts from 1 (not 0).
 * 
 * @{
 */

	/** The size of the save game name buffer */
	static const UPLAY_uint32	UPLAY_SAVEGAME_NAME_BUFFER_LEN = 256;

	/************************************************************************************//**
	 * @enum	UPLAY_SAVE_Mode
	 * @brief	Values for open modes used in ::UPLAY_SAVE_Open()
	 */
	typedef enum 
	{
		/** Open the save game for reading */
		UPLAY_SAVE_Mode_Read,
		/** Open the save game for writing */
		UPLAY_SAVE_Mode_Write,
	} UPLAY_SAVE_Mode;

	/** Type definition of a save game handle */
	typedef UPLAY_uint32 UPLAY_SAVE_Handle;

#pragma pack(push, 8)

	/************************************************************************************//**
	 * @struct	UPLAY_SAVE_Game
	 * @brief	Struct containing information about a save game
	 * @note	\a id should be 1 or higher
	 */
	typedef struct UPLAY_SAVE_Game_t 
	{
		/** The ID of the save game */
		UPLAY_uint32				id;
		/** Null terminated UTF-8 string containing the name of the save game */
		const char*					nameUtf8;
		/** The size of the save game */
		UPLAY_uint32				size;
	} UPLAY_SAVE_Game;

	/************************************************************************************//**
	 * @struct	UPLAY_SAVE_GameList
	 * @brief	Struct representing a list of save games
	 */
	typedef struct UPLAY_SAVE_GameList_t
	{
		/** The number of elements in the list */
		UPLAY_uint32				count;
		/** The list of save games */
		const UPLAY_SAVE_Game**		list;
	} UPLAY_SAVE_GameList;

#pragma pack(pop)

	/************************************************************************************//**
	 * @fn		int UPLAY_SAVE_GetSavegames(UPLAY_SAVE_GameList**, UPLAY_Overlapped*)
	 * @brief	Retrieves a list of saved games for the current user and product.
	 *
	 * The following ::UPLAY_OverlappedResult values can be returned:
	 * 
	 *	Result                                 | Description
	 *	-------------------------------------- | -----------
	 *	UPLAY_OverlappedResult_Failed          | Unknown error
	 *	UPLAY_OverlappedResult_Ok              | Success
	 * 
	 * @note	More overlapped results can be added in future versions of the API.
	 * 
	 * @param	aOutGameList
	 *				The resulting list of save games will be stored here
	 * @param	aOverlapped
	 *				Overlapped struct
	 *
	 * @returns Non-zero on success
	 */
	int
	UPLAY_API		UPLAY_SAVE_GetSavegames(
						UPLAY_SAVE_GameList** 		aOutGameList,
						UPLAY_Overlapped* 			aOverlapped);	

	/************************************************************************************//**
	 * @fn		int UPLAY_SAVE_ReleaseGameList(UPLAY_SAVE_GameList* aGamesList)
	 * @brief	Release allocated memory from UPLAY_SAVE_GetSavegames 
	 * 
	 * @param	aImage
	 *				Pointer to the allocated UPLAY_SAVE_GetSavegames game list
	 *
	 * @returns Non-zero on success
	 */
	int
	UPLAY_API		UPLAY_SAVE_ReleaseGameList(
						UPLAY_SAVE_GameList* 		aGamesList);

	/************************************************************************************//**
	 * @fn		int UPLAY_SAVE_Open(UPLAY_uint32, UPLAY_uint32, UPLAY_SAVE_Handle*, UPLAY_Overlapped*)
	 * @brief	Open a saved game.
	 * 
	 * @note	Must call UPLAY_SAVE_Close after use.
	 *
	 * The following ::UPLAY_OverlappedResult values can be returned:
	 * 
	 *	Result										| Description
	 *	------------------------------------------- | -----------
	 *	UPLAY_OverlappedResult_InvalidArgument		| Not a valid save handle
	 *	UPLAY_OverlappedResult_SlotLocked			| Slot is already opened
	 *  UPLAY_OverlappedResult_OverwriteNotAllowed	| Slot is not writeable
	 *	UPLAY_OverlappedResult_Failed				| Unknown error
	 *	UPLAY_OverlappedResult_Ok					| Success
	 * 
	 * @note	More overlapped results can be added in future versions of the API.
	 *
	 * @param	aSlotId
	 *				Slot to open - must be 1 or higher
	 * @param	aMode
	 *				Mode to open the save game. See enum ::UPLAY_SAVE_Mode for valid values.
	 *				@note The save will be truncated if opened for writing.
	 * @param	aOutSaveHandle
	 *				A save handle. Must be available until the overlapped function has been completed
	 * @param	aOverlapped
	 *				Overlapped struct
	 *
	 * @returns Non-zero on success
	 */
	int 
	UPLAY_API		UPLAY_SAVE_Open(	
						UPLAY_uint32				aSlotId,
						UPLAY_uint32				aMode,
						UPLAY_SAVE_Handle*			aOutSaveHandle,
						UPLAY_Overlapped* 			aOverlapped);

	/************************************************************************************//**
	 * @fn		int UPLAY_SAVE_Close(UPLAY_SAVE_Handle)
	 * @brief	Close a save game.
	 *
	 * This function will release memory internally and must be called after a call to ::UPLAY_SAVE_Open()
	 * 
	 * @param	aSaveHandle
	 *				A save handle
	 *
	 * @returns Non-zero on success
	 */
	int 
	UPLAY_API		UPLAY_SAVE_Close(
						UPLAY_SAVE_Handle			aSaveHandle);

	/************************************************************************************//**
	 * @fn		int UPLAY_SAVE_Read(UPLAY_SAVE_Handle, UPLAY_uint32, UPLAY_uint32, UPLAY_DataBlob*, UPLAY_uint32*, UPLAY_Overlapped*)
	 * @brief	Read from a save game.
	 *
	 * The following ::UPLAY_OverlappedResult values can be returned:
	 * 
	 *	Result                                 | Description
	 *	-------------------------------------- | -----------
	 *	UPLAY_OverlappedResult_InvalidArgument | Some of the arguments are not valid
	 *	UPLAY_OverlappedResult_SlotLocked      | Slot is already opened for writing
	 *	UPLAY_OverlappedResult_Failed          | Unknown error
	 *	UPLAY_OverlappedResult_Ok              | Success
	 * 
	 * @note	More overlapped results can be added in future versions of the API.
	 * 
	 * @param	aSaveHandle
	 *				Save handle to read from
	 * @param	aNumOfBytesToRead
	 *				Number of bytes to read. Can't be larger than aOutBuffer's size
	 * @param	aOffset
	 *				Offset to start reading from
	 * @param	aOutBuffer
	 *				Buffer to store the read data in
	 * @param	aOutNumOfBytesRead
	 *				Number of bytes actually read
	 * @param	aOverlapped
	 *				Overlapped struct
	 *
	 * @returns Non-zero on success
	 */
	int 
	UPLAY_API		UPLAY_SAVE_Read(
						UPLAY_SAVE_Handle	 		aSaveHandle,
						UPLAY_uint32				aNumOfBytesToRead,
						UPLAY_uint32				aOffset,
						UPLAY_DataBlob*				aOutBuffer,
						UPLAY_uint32*				aOutNumOfBytesRead,
						UPLAY_Overlapped* 			aOverlapped);

	/************************************************************************************//**
	 * @fn		int UPLAY_SAVE_Write(UPLAY_SAVE_Handle, UPLAY_uint32, UPLAY_DataBlob*, UPLAY_Overlapped*)
	 * @brief	Write to a saved game.
	 *
	 * The following ::UPLAY_OverlappedResult values can be returned:
	 * 
	 *	Result                                 | Description
	 *	-------------------------------------- | -----------
	 *	UPLAY_OverlappedResult_InvalidArgument | Some of the arguments are not valid
	 *	UPLAY_OverlappedResult_SlotLocked      | Slot is already opened for reading
	 *	UPLAY_OverlappedResult_Failed          | Unknown error
	 *	UPLAY_OverlappedResult_Ok              | Success
	 * 
	 * @note	More overlapped results can be added in future versions of the API.
	 * 
	 * @param	aSaveHandle
	 *				Save handle to write
	 * @param	aNumOfBytesToWrite
	 *				Number of bytes to write
	 * @param	aBuffer
	 *				Buffer containing the data to write
	 * @param	aOverlapped
	 *				Overlapped struct
	 *
	 * @returns Non-zero on success
	 */
	int 
	UPLAY_API		UPLAY_SAVE_Write(
						UPLAY_SAVE_Handle			aSaveHandle,
						UPLAY_uint32				aNumOfBytesToWrite,
						UPLAY_DataBlob*				aBuffer,
						UPLAY_Overlapped* 			aOverlapped);

	/************************************************************************************//**
	 * @fn		int UPLAY_SAVE_SetName(UPLAY_SAVE_Handle, const char*)
	 * @brief	Set the name of a save game
	 * 
	 * @param	aSaveHandle
	 *				Save handle to set name of. Must be opened for writing.
	 * @param	aNameUtf8
	 *				Null terminated UTF-8 string containing the new name of the save game
	 *
	 * @returns Non-zero on success
	 */
	int 
	UPLAY_API		UPLAY_SAVE_SetName(
						UPLAY_SAVE_Handle			aSaveHandle,
						const char*					aNameUtf8);

	/************************************************************************************//**
	 * @fn		int UPLAY_SAVE_Remove(UPLAY_uint32, UPLAY_Overlapped*)
	 * @brief	Remove a save game
	 *
	 * The following ::UPLAY_OverlappedResult values can be returned:
	 * 
	 *	Result                                 | Description
	 *	-------------------------------------- | -----------
	 *	UPLAY_OverlappedResult_InvalidArgument | Some of the arguments are not valid
	 *	UPLAY_OverlappedResult_SlotLocked      | Slots can't be removed while open
	 *	UPLAY_OverlappedResult_NotFound        | No save in this slot
	 *	UPLAY_OverlappedResult_Failed          | Unknown error
	 *	UPLAY_OverlappedResult_Ok              | Success
	 * 
	 * @note	More overlapped results can be added in future versions of the API.
	 * 
	 * @param	aSlotId
	 *				ID of the save game slot to remove - must be 1 or higher
	 * @param	aOverlapped
	 *				Overlapped struct
	 *
	 * @returns Non-zero on success
	 */
	int 
	UPLAY_API		UPLAY_SAVE_Remove(
						UPLAY_uint32				aSlotId,
						UPLAY_Overlapped* 			aOverlapped);

/** @} */

#ifdef __cplusplus
}
#endif // __cplusplus

#endif // UPLAY_SAVE_H