DOOM-3-BFG/neo/sys/sys_savegame.h

/*
===========================================================================

Doom 3 BFG Edition GPL Source Code
Copyright (C) 1993-2012 id Software LLC, a ZeniMax Media company. 

This file is part of the Doom 3 BFG Edition GPL Source Code ("Doom 3 BFG Edition Source Code").  

Doom 3 BFG Edition Source Code is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

Doom 3 BFG Edition Source Code is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with Doom 3 BFG Edition Source Code.  If not, see <http://www.gnu.org/licenses/>.

In addition, the Doom 3 BFG Edition Source Code is also subject to certain additional terms. You should have received a copy of these additional terms immediately following the terms and conditions of the GNU General Public License which accompanied the Doom 3 BFG Edition Source Code.  If not, please request a copy in writing from id Software at the address below.

If you have questions concerning this license or the applicable additional terms, you may contact in writing id Software LLC, c/o ZeniMax Media Inc., Suite 120, Rockville, Maryland 20850 USA.

===========================================================================
*/
#ifndef __SYS_SAVEGAME_H__
#define __SYS_SAVEGAME_H__

#ifdef OUTPUT_FUNC
#undef OUTPUT_FUNC
#endif
#ifdef OUTPUT_FUNC_EXIT
#undef OUTPUT_FUNC_EXIT
#endif
#define OUTPUT_FUNC()				idLib::PrintfIf( saveGame_verbose.GetBool(), "[%s] Enter\n", __FUNCTION__ )
#define OUTPUT_FUNC_EXIT()			idLib::PrintfIf( saveGame_verbose.GetBool(), "[%s] Exit\n", __FUNCTION__ )


#define DEFINE_CLASS( x )					virtual const char * Name() const { return #x; }
#define MAX_SAVEGAMES						16
#define MAX_FILES_WITHIN_SAVEGAME			10
#define MIN_SAVEGAME_SIZE_BYTES				( 4 * 1024 * 1024 )
#define MAX_SAVEGAME_STRING_TABLE_SIZE		400 * 1024	// 400 kB max string table size


#define MAX_FILENAME_LENGTH					255
#define MAX_FILENAME_LENGTH_PATTERN			8
#define MAX_FOLDER_NAME_LENGTH				64
#define SAVEGAME_DETAILS_FILENAME			"game.details"

// PS3 restrictions:  The only characters that can be used are 0-9 (numbers), A-Z (uppercase alphabet), "_" (underscore), and "-" (hyphen)
#define SAVEGAME_AUTOSAVE_FOLDER			"AUTOSAVE"		// auto save slot

// common descriptors for savegame description fields
#define SAVEGAME_DETAIL_FIELD_EXPANSION		"expansion"
#define SAVEGAME_DETAIL_FIELD_MAP			"mapName"
#define SAVEGAME_DETAIL_FIELD_MAP_LOCATE	"mapLocation"
#define SAVEGAME_DETAIL_FIELD_DIFFICULTY	"difficulty"
#define SAVEGAME_DETAIL_FIELD_PLAYTIME		"playTime"
#define SAVEGAME_DETAIL_FIELD_LANGUAGE		"language"
#define	SAVEGAME_DETAIL_FIELD_SAVE_VERSION	"saveVersion"
#define	SAVEGAME_DETAIL_FIELD_CHECKSUM		"checksum"

#define SAVEGAME_GAME_DIRECTORY_PREFIX		"GAME-"
#define SAVEGAME_PROFILE_DIRECTORY_PREFIX	""
#define SAVEGAME_RAW_DIRECTORY_PREFIX		""


extern idCVar saveGame_verbose;
extern idCVar saveGame_enable;

class idGameSpawnInfo;
class idSession;
class idSessionLocal;
class idSaveGameManager;

// Specific savegame sub-system errors
enum saveGameError_t {
	SAVEGAME_E_NONE								= 0,
	SAVEGAME_E_CANCELLED						= BIT( 0 ),
	SAVEGAME_E_INSUFFICIENT_ROOM				= BIT( 1 ),
	SAVEGAME_E_CORRUPTED						= BIT( 2 ),
	SAVEGAME_E_UNABLE_TO_SELECT_STORAGE_DEVICE	= BIT( 3 ),
	SAVEGAME_E_UNKNOWN							= BIT( 4 ),
	SAVEGAME_E_INVALID_FILENAME					= BIT( 5 ),
	SAVEGAME_E_STEAM_ERROR						= BIT( 6 ),
	SAVEGAME_E_FOLDER_NOT_FOUND					= BIT( 7 ),
	SAVEGAME_E_FILE_NOT_FOUND					= BIT( 8 ),
	SAVEGAME_E_DLC_NOT_FOUND					= BIT( 9 ),
	SAVEGAME_E_INVALID_USER						= BIT( 10 ),
	SAVEGAME_E_PROFILE_TOO_BIG					= BIT( 11 ),
	SAVEGAME_E_DISC_SWAP						= BIT( 12 ),
	SAVEGAME_E_INCOMPATIBLE_NEWER_VERSION		= BIT( 13 ),

	SAVEGAME_E_BITS_USED						= 14,
	SAVEGAME_E_NUM								= SAVEGAME_E_BITS_USED + 1	// because we're counting "none"
};

// Modes to control behavior of savegame manager
enum saveGameModeBitfield_t {
	SAVEGAME_MBF_NONE				= 0,
	SAVEGAME_MBF_LOAD				= BIT( 0 ),		// standard file load (can be individual/multiple files described in parms)
	SAVEGAME_MBF_SAVE				= BIT( 1 ),		// standard file save (can be individual/multiple files described in parms)
	SAVEGAME_MBF_DELETE_FOLDER		= BIT( 2 ),		// standard package delete
	SAVEGAME_MBF_DELETE_ALL_FOLDERS	= BIT( 3 ),		// deletes all of the savegame folders (should only be used in testing)
	SAVEGAME_MBF_ENUMERATE			= BIT( 4 ),		// gets listing of all savegame folders, typically used with READ_DETAILS to read the description file
	SAVEGAME_MBF_NO_COMPRESS		= BIT( 5 ),		// tells the system the files aren't compressed, usually only needed when reading the descriptors file internally
	SAVEGAME_MBF_ENUMERATE_FILES	= BIT( 6 ),		// enumerates all the files within a particular savegame folder (can be individual/multiple files or pattern described in parms)
	SAVEGAME_MBF_DELETE_FILES		= BIT( 7 ),		// deletes individual files within a particular savegame folder (can be individual/multiple files or pattern described in parms)
	SAVEGAME_MBF_READ_DETAILS		= BIT( 8 ),		// reads the description file (if specified, parms.enumeratedEntry.name & parms.enumeratedEntry.type must be specified)
	SAVEGAME_MBF_KEEP_FOLDER		= BIT( 9 )		// don't delete the folder before saving
};

typedef interlockedInt_t saveGameHandle_t;

typedef int savegameUserId_t;		// [internal] hash of gamer tag for steam

/*
================================================
saveGameCheck_t
================================================
*/
struct saveGameCheck_t {
	saveGameCheck_t() { 
		exists = false;
		autosaveExists = false;
		autosaveFolder = NULL;
	}
	bool exists;
	bool autosaveExists;
	const char * autosaveFolder;
};

/*
================================================
idSaveGameDetails 
================================================
*/
class idSaveGameDetails {
public:
	idSaveGameDetails();
	~idSaveGameDetails() { Clear(); }

	void	Clear();
	bool	operator==( const idSaveGameDetails & other ) const { return ( idStr::Icmp( slotName, other.slotName ) == 0 ); }
	idSaveGameDetails &	operator=( const idSaveGameDetails &other ) {
		descriptors.Clear();
		descriptors = other.descriptors;
		damaged = other.damaged;
		date = other.date;
		slotName = other.slotName;
		return *this;
	}
	// for std::sort, sort newer (larger date) towards start of list
	bool	operator<( const idSaveGameDetails & other ) { return date > other.date; }

	idStr	GetMapName() const { return descriptors.GetString( SAVEGAME_DETAIL_FIELD_MAP, "" ); }
	idStr	GetLocation() const { return descriptors.GetString( SAVEGAME_DETAIL_FIELD_MAP_LOCATE, "" ); }
	idStr	GetLanguage() const { return descriptors.GetString( SAVEGAME_DETAIL_FIELD_LANGUAGE, "" ); }
	int		GetPlaytime() const { return descriptors.GetInt( SAVEGAME_DETAIL_FIELD_PLAYTIME, 0 ); }
	int		GetExpansion() const { return descriptors.GetInt( SAVEGAME_DETAIL_FIELD_EXPANSION, 0 ); }
	int		GetDifficulty() const { return descriptors.GetInt( SAVEGAME_DETAIL_FIELD_DIFFICULTY, -1 ); }
	int		GetSaveVersion() const { return descriptors.GetInt( SAVEGAME_DETAIL_FIELD_SAVE_VERSION, 0 ); }

public:
	idDict				descriptors;						// [in] Descriptors available to be shown on the save/load screen.  Each game can define their own, e.g. Difficulty, level, map, score, time.
	bool				damaged;							// [out]
	time_t				date;								// [out] read from the filesystem, not set by client
	idStrStatic< MAX_FOLDER_NAME_LENGTH >	slotName;		// [out] folder/slot name, e.g. AUTOSAVE
};

typedef idStaticList< idSaveGameDetails, MAX_SAVEGAMES > saveGameDetailsList_t;

// Making a auto_ptr to handle lifetime issues better
typedef idList< idFile_SaveGame *, TAG_SAVEGAMES > saveFileEntryList_t;

/*
================================================
idSaveLoadParms 
================================================
*/
class idSaveLoadParms {
public:
								idSaveLoadParms();
								~idSaveLoadParms();

	void						ResetCancelled();
	void						Init();
	void						SetDefaults( int inputDevice = -1 );	// doesn't clear out things that should be persistent across entire processor
	void						CancelSaveGameFilePipelines();
	void						AbortSaveGameFilePipeline();
	const int &					GetError() const { return errorCode; }
	const int &					GetHandledErrors() const { return handledErrorCodes; }
	const saveGameHandle_t &	GetHandle() const { return handle; }

public:
	idStrStatic< MAX_FOLDER_NAME_LENGTH >		directory;			// [in] real directory of the savegame package
	idStrStatic< MAX_FILENAME_LENGTH_PATTERN >	pattern;			// [in] pattern to use while enumerating/deleting files within a savegame folder
	idStrStatic< MAX_FILENAME_LENGTH_PATTERN >	postPattern;		// [in] pattern at the end of the file to use while enumerating/deleting files within a savegame folder

	int									mode;						// [in] SAVE, LOAD, ENUM, DELETE, etc.
	idSaveGameDetails					description;				// [in/out] in: description used to serialize into game.details file, out: if SAVEGAME_MBF_READ_DETAILS used with certain modes, item 0 contains the read details
	saveFileEntryList_t					files;						// [in/out] in: files to be saved, out: objects loaded, for SAVEGAME_MBF_ENUMERATE_FILES, it contains a listing of the filenames only
	saveGameDetailsList_t				detailList;					// [out] listing of the enumerated savegames used only with SAVEGAME_MBF_ENUMERATE

	int									errorCode;					// [out] combination of saveGameError_t bits
	int									handledErrorCodes;			// [out] combination of saveGameError_t bits
	int64								requiredSpaceInBytes;		// [out] when fails for insufficient space, this is populated with additional space required
	int									skipErrorDialogMask;

	// ----------------------
	// Internal vars
	// ----------------------
	idSysSignal							callbackSignal;				// [internal] used to signal savegame manager that the Process() call is completed (we still might have more Process() calls to make though...)
	volatile bool						cancelled;					// [internal] while processor is running, this can be set outside of the normal operation of the processor.  Each implementation should check this during operation to allow it to shutdown cleanly.
	savegameUserId_t					userId;						// [internal] to get the proper user during every step
	int									inputDeviceId;				// [internal] consoles will use this to segregate each player's files
	saveGameHandle_t					handle;

private:
	// Don't allow copies
						idSaveLoadParms( const idSaveLoadParms & s ) {}
	void				operator=( const idSaveLoadParms & s ) {}
};

// Using function pointers because:
// 1. CompletedCallback methods in processors weren't generic enough, we could use SaveFiles processors
//		for profiles/games, but there would be a single completed callback and we'd have to update
//		the callback to detect what type of call it was, store the type in the processor, etc.
// 2. Using a functor class would require us to define classes for each callback.  The definition of those
//		classes could be scattered and a little difficult to follow
// 3. With callback methods, we assign them when needed and know exactly where they are defined/declared.
//typedef void (*saveGameProcessorCallback_t)( idSaveLoadParms & parms );

/*
================================================
saveGameThreadArgs_t 
================================================
*/
struct saveGameThreadArgs_t {
	saveGameThreadArgs_t() :
		saveLoadParms( NULL ) {
	}
	

	idSaveLoadParms *		saveLoadParms;
};

/*
================================================
idSaveGameThread 
================================================
*/
class idSaveGameThread : public idSysThread {
public:
			idSaveGameThread() : cancel( false ) {}

	int		Run();
	void	CancelOperations() { cancel = true; }

private:
	int		Save();
	int		Load();
	int		Enumerate();
	int		Delete();
	int		DeleteAll();
	int		DeleteFiles();
	int		EnumerateFiles();

public:
	saveGameThreadArgs_t	data;
	volatile bool			cancel;
};

/*
================================================
idSaveGameProcessor 
================================================
*/
class idSaveGameProcessor {
	friend class idSaveGameManager;

public:
	DEFINE_CLASS( idSaveGameProcessor );
	static const int MAX_COMPLETED_CALLBACKS = 5;

							idSaveGameProcessor();
	virtual					~idSaveGameProcessor() { }

	//------------------------
	// Virtuals
	//------------------------
	// Basic init
	virtual bool			Init();

	// This method should returns true if the processor has additional sub-states to 
	// manage.  The saveGameManager will retain the current state and Process() will be called again. When this method
	// returns false Process() will not be called again. For example, during save, you might want to load other files
	// and save them somewhere else, return true until you are done with the entire state.
	virtual bool			Process() { return false; }

	// Gives each processor to validate an error returned from the previous process call.
	// This is useful when processors have a multi-stage Process() and expect some benign errors like
	// deleting a savegame folder before copying into it.
	virtual bool			ValidateLastError() { return false; }

	// Processors need to override this if they will eventually reset the map.
	// If it could possibly reset the map through any of its stages, including kicking off another processor in completed callback, return false.
	// We will force non-simple processors to execute last and won't block the map heap reset due if non-simple processors are still executing.
	virtual bool			IsSimpleProcessor() const { return true; }

	// This is a fail-safe to catch a timing issue on the PS3 where the nextmap processor could sometimes hang during a level transition
	virtual bool			ShouldTimeout() const { return false; }

	//------------------------
	// Commands
	//------------------------
	// Cancels this processor in whatever state it's currently in and sets an error code for SAVEGAME_E_CANCELLED
	void					Cancel() { parms.cancelled = true; parms.errorCode = SAVEGAME_E_CANCELLED; }

	//------------------------
	// Accessors
	//------------------------
	// Returns error status
	idSysSignal &			GetSignal() { return parms.callbackSignal; }

	// Returns error status
	const int &				GetError() const { return parms.errorCode; }

	// Returns the processor's save/load parms
	const idSaveLoadParms & GetParms() const { return parms; }

	// Returns the processor's save/load parms
	idSaveLoadParms &		GetParmsNonConst() { return parms; }

	// Returns if this processor is currently working
	bool					IsWorking() const { return working; }
	
	// This is a way to tell the processor which errors shouldn't be handled by the processor or system.
	void					SetSkipSystemErrorDialogMask( const int errorMask ) { parms.skipErrorDialogMask = errorMask; }
	int						GetSkipSystemErrorDialogMask() const { return parms.skipErrorDialogMask; }

	// Returns the handle given by execution
	saveGameHandle_t		GetHandle() const { return parms.GetHandle(); }

	// These can be overridden by game code, like the GUI, when the processor is done executing.
	// Game classes like the GUI can create a processor derived from a game's Save processor impl and simply use
	// this method to know when everything is done.  It eases the burden of constantly checking the working flag.
	// This will be called back within the game thread during SaveGameManager::Pump().
	void					AddCompletedCallback( const idCallback & callback );

private:
	// Returns whether or not the thread is finished operating, should only be called by the savegame manager
	bool					IsThreadFinished();

protected:
	idSaveLoadParms		parms;
	int					savegameLogicTestIterator;

private:
	bool				init;	
	bool				working;

	idStaticList< idCallback *, MAX_COMPLETED_CALLBACKS >	completedCallbacks;
};

/*
================================================
idSaveGameManager 

Why all the object-oriented nonsense?
- Savegames need to be processed asynchronously, saving/loading/deleting files should happen during the game frame
	so there is a common way to update the render device.
- When executing commands, if no "strategy"s are used, the pump() method would need to have a switch statement,
	extending the manager for other commands would mean modifying the manager itself for various commands.
	By making it a strategy, we are able to create custom commands and define the behavior within game code and keep
	the manager code in the engine static.
================================================
*/
class idSaveGameManager {
public:
	enum packageType_t {
		PACKAGE_PROFILE,
		PACKAGE_GAME,
		PACKAGE_RAW,
		PACKAGE_NUM
	};

	const static int MAX_SAVEGAME_DIRECTORY_DEPTH = 5;

	explicit				idSaveGameManager();
							~idSaveGameManager();

	// Called within main game thread
	void					Pump();

	// Has the storage device been selected yet?  This is only an issue on the 360, and primarily for development purposes
	bool					IsStorageAvailable() const { return storageAvailable; }
	void					SetStorageAvailable( const bool available ) { storageAvailable = available; }

	// Check to see if a processor is set within the manager
	bool					IsWorking() const;

	// Assign a processor to the manager.  The processor should belong in game-side code
	// This queues up processors and executes them serially
	// Returns whether or not the processor is immediately executed
	saveGameHandle_t		ExecuteProcessor( idSaveGameProcessor * processor );
	
	// Synchronous version, CompletedCallback is NOT called.
	saveGameHandle_t		ExecuteProcessorAndWait( idSaveGameProcessor * processor );

	// Lets the currently processing queue finish, but clears the processor queue
	void					Clear();

	void					WaitForAllProcessors( bool overrideSimpleProcessorCheck = false );

	const bool				IsCancelled() const { return cancel; }
	void					CancelAllProcessors( const bool forceCancelInFlightProcessor );

	void					CancelToTerminate();

	idSaveGameThread &		GetSaveGameThread() { return saveThread; }

	bool					IsSaveGameCompletedFromHandle( const saveGameHandle_t & handle ) const { return handle <= lastExecutedProcessorHandle || handle == 0; }	// last case should never be reached since it would be also be true in first case, this is just to show intent
	void					Set360RetrySaveAfterDeviceSelected( const char * folder, const int64 bytes );
	bool					DeviceSelectorWaitingOnSaveRetry();
	void					ShowRetySaveDialog( const char * folder, const int64 bytes );
	void					ShowRetySaveDialog();
	void					ClearRetryInfo();
	void					RetrySave();
	// This will cause the processor to cancel execution, the completion callback will be called 
	void					CancelWithHandle( const saveGameHandle_t & handle );

	const saveGameDetailsList_t & GetEnumeratedSavegames() const { return enumeratedSaveGames; }
	saveGameDetailsList_t & GetEnumeratedSavegamesNonConst() { return enumeratedSaveGames; }

private:
	// These are to make sure that all processors start and finish in the same way without a lot of code duplication.
	// We need to make sure that we adhere to PS3 system combination initialization issues.
	void					StartNextProcessor();
	void					FinishProcessor( idSaveGameProcessor * processor );

	// Calls start on the processor after it's been assigned
	void					Start();

private:
	idSaveGameProcessor *						processor;
	idStaticList< idSaveGameProcessor *, 4 >	processorQueue;
	bool										cancel;
	idSaveGameThread							saveThread;
	int											startTime;
	bool										continueProcessing;
	saveGameHandle_t							submittedProcessorHandle;
	saveGameHandle_t							executingProcessorHandle;
	saveGameHandle_t							lastExecutedProcessorHandle;
	saveGameDetailsList_t						enumeratedSaveGames;
	bool										storageAvailable;				// On 360, this is false by default, after the storage device is selected
																				// it becomes true.  This allows us to start the game without a storage device
																				// selected and pop the selector when necessary.
	const char *								retryFolder;
	int64										retryBytes;
	bool										retrySave;
	idSysSignal									deviceRequestedSignal;
};

// Bridge between the session's APIs and the savegame thread
void Sys_ExecuteSavegameCommandAsync( idSaveLoadParms * savegameParms );

// Folder prefix should be NULL for everything except PS3
// Synchronous check, just checks if any savegame exists for master local user and if one is an autosave
void Sys_SaveGameCheck( bool & exists, bool & autosaveExists );

const idStr & GetSaveFolder( idSaveGameManager::packageType_t type );
idStr AddSaveFolderPrefix( const char * folder, idSaveGameManager::packageType_t type );
idStr RemoveSaveFolderPrefix( const char * folder, idSaveGameManager::packageType_t type );

bool SavegameReadDetailsFromFile( idFile * file, idSaveGameDetails & details );

idStr GetSaveGameErrorString( int errorMask );

#endif // __SYS_SAVEGAME_H__