Engine.DataStoreClient

/**
 * Creates and manages all globally accessible persistent data stores.
 * Copyright 1998-2008 Epic Games, Inc. All Rights Reserved.
 */
class DataStoreClient extends UIRoot
	native(inherit)
	Config(Engine);

/**
 * Represents a collection of data stores that are linked to a specific player.
 */
struct native transient PlayerDataStoreGroup
{
	/**
	 * the player that this group is associated with.
	 */
	var	const	transient	LocalPlayer			PlayerOwner;

	/**
	 * the list of data stores registered for this player.
	 */
	var	const	transient	array<UIDataStore>	DataStores;
};

/**
 * List of global data store class names to create when the data store client is created.
 */
var	config					array<string>				GlobalDataStoreClasses;

/**
 * The list of global persistent data stores.
 */
var const 					array<UIDataStore>			GlobalDataStores;

/**
 * List of data store class names that should be loaded at initialization time, but not created.  Instances of these data
 * stores will be created as they are needed (i.e. PlayerOwner, etc.)
 */
var	config					array<string>				PlayerDataStoreClassNames;

/**
 * Stores the list of dynamic player data store classes that were loaded from PlayerDataStoreClassNames.
 */
var	const private			array<class<UIDataStore> >	PlayerDataStoreClasses;

/**
 * the list of dynamic data stores that are created per-player.
 */
var	const					array<PlayerDataStoreGroup>	PlayerDataStores;

// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)
// (cpptext)

/**
 * Finds the data store indicated by DataStoreTag and returns a pointer to it.
 *
 * @param	DataStoreTag	A name corresponding to the 'Tag' property of a data store
 * @param	PlayerOwner		used for resolving the correct data stores in split-screen games.
 *
 * @return	a pointer to the data store that has a Tag corresponding to DataStoreTag, or NULL if no data
 *			were found with that tag.
 */
native final function UIDataStore FindDataStore( name DataStoreTag, optional LocalPlayer PlayerOwner );

/**
 * Creates and initializes an instance of the data store class specified.
 *
 * @param	DataStoreClass	the data store class to create an instance of.  DataStoreClass should be a child class
 *							of UUIDataStore
 *
 * @return	a pointer to an instance of the data store class specified.
 */
native final function coerce UIDataStore CreateDataStore( class<UIDataStore> DataStoreClass );

/**
 * Adds a new data store to the GlobalDataStores array.
 *
 * @param	DataStore	the data store to add
 * @param	PlayerOwner	if specified, the data store will be added to the list of PlayerDataStores, rather than the list of global data stores
 *
 * @return	TRUE if the data store was successfully added, or if the data store was already in the list.
 */
native final function bool RegisterDataStore( UIDataStore DataStore, optional LocalPlayer PlayerOwner );

/**
 * Removes a data store from the GlobalDataStores array.
 *
 * @param	DataStore	the data store to remove
 *
 * @return	TRUE if the data store was successfully removed, or if the data store wasn't in the list.
 */
native final function bool UnregisterDataStore( UIDataStore DataStore );

/**
 * Retrieve the list of currently available data stores, including any temporary data stores associated with the specified scene.
 *
 * @param	CurrentScene	the scene to use as the context for determining which data stores are available
 * @param	out_DataStores	will be filled with the list of data stores which are available from the context of the specified scene
 */
native final function GetAvailableDataStores( UIScene CurrentScene, out array<UIDataStore> out_DataStores ) const;

/**
 * Finds the index into the PlayerDataStores array for the data stores associated with the specified player.
 *
 * @param	PlayerOwner		the player to search for associated data stores for.
 */
native final function int FindPlayerDataStoreIndex( LocalPlayer PlayerOwner ) const;

/* === Unrealscript === */
/**
 * Searches the data store client's data store class arrays for a child of the specified meta class.
 *
 * @param	RequiredMetaClass	the data store base class to search for.
 *
 * @return	a pointer to a child class of RequiredMetaClass that was specified in the ini.
 */
final function class<UIDataStore> FindDataStoreClass( class<UIDataStore> RequiredMetaClass )
{
	local int i;
	local class<UIDataStore> Result;

	// first, search through the global data stores array
	for ( i = 0; i < GlobalDataStores.Length; i++ )
	{
		// if this global data store is an instance of the class we're searching for, stop here
		if ( GlobalDataStores[i].IsA(RequiredMetaClass.Name) )
		{
			Result = GlobalDataStores[i].Class;
			break;
		}
	}

	if ( Result == None )
	{
		// search through the player data store class arrays
		for ( i = 0; i < PlayerDataStoreClasses.Length; i++ )
		{
			if ( ClassIsChildOf(PlayerDataStoreClasses[i], RequiredMetaClass) )
			{
				Result = PlayerDataStoreClasses[i];
				break;
			}
		}
	}

	return Result;
}

/**
 * Called when the current map is being unloaded.  Cleans up any references which would prevent garbage collection.
 */
final event NotifyGameSessionEnded()
{
	local int i, DataStoreIndex;
	local array<UIDataStore> DataStoreArray;

	DataStoreArray = GlobalDataStores;

	// notify all global data stores
	for ( DataStoreIndex = 0; DataStoreIndex < DataStoreArray.Length; DataStoreIndex++ )
	{
		if ( DataStoreArray[DataStoreIndex].NotifyGameSessionEnded() )
		{
			UnregisterDataStore(DataStoreArray[DataStoreIndex]);
		}
	}

	// now notify all dynamic data stores
	for ( i = PlayerDataStores.Length - 1; i >= 0; i-- )
	{
		DataStoreArray = PlayerDataStores[i].DataStores;
		for ( DataStoreIndex = 0; DataStoreIndex < DataStoreArray.Length; DataStoreIndex++ )
		{
			DataStoreArray[DataStoreIndex].NotifyGameSessionEnded();
			UnregisterDataStore(DataStoreArray[DataStoreIndex]);
		}
	}
}


final function DebugDumpDataStoreInfo( bool bVerbose )
{

	local int DataStoreIndex, PlayerDataStoreIndex;
	local string PlayerName;

	local LocalPlayer PlayerOwner;
	local array<UIDataStore> PlayerGroupDataStores;

	// first, search through the global data stores array
	LogInternal("GlobalDataStores: " $ GlobalDataStores.Length,'DevDataStore');

	for ( DataStoreIndex = 0; DataStoreIndex < GlobalDataStores.Length; DataStoreIndex++ )
	{
		//@todo ronp - expose UUIDataStore::GetDataStoreId() as a native unrealscript function, rather than using the data store's tag directly
		LogInternal("	GlobalDataStore[" $ DataStoreIndex $ "]:" @ GlobalDataStores[DataStoreIndex].Tag @ "(" $ GlobalDataStores[DataStoreIndex] $ ")",'DevDataStore');

		//@todo ronp - call a function on the GlobalDataStore to allow it to log more detailed information
	}

	LogInternal("");
	LogInternal("Player data store groups:" $ PlayerDataStores.Length,'DevDataStore');
	for ( DataStoreIndex = 0; DataStoreIndex < PlayerDataStores.Length; DataStoreIndex++ )
	{
		PlayerOwner = PlayerDataStores[DataStoreIndex].PlayerOwner;
		PlayerGroupDataStores = PlayerDataStores[DataStoreIndex].DataStores;

		PlayerName = (PlayerOwner != None && PlayerOwner.Actor != None && PlayerOwner.Actor.PlayerReplicationInfo != None) ? PlayerOwner.Actor.PlayerReplicationInfo.PlayerName : "None";
		LogInternal("	PlayerDataStores for player " $ DataStoreIndex $ ":" @ PlayerGroupDataStores.Length @ "(" $ Playername @ "-" @ PlayerOwner $ ")",'DevDataStore');

		for ( PlayerDataStoreIndex = 0; PlayerDataStoreIndex < PlayerGroupDataStores.Length; PlayerDataStoreIndex++ )
		{
			//@todo ronp - expose UUIDataStore::GetDataStoreId() as a native unrealscript function, rather than using the data store's tag directly
			LogInternal("		PlayerDataStore[" $ PlayerDataStoreIndex $ "]:" @ PlayerGroupDataStores[PlayerDataStoreIndex].Tag @ "(" $ PlayerGroupDataStores[PlayerDataStoreIndex] $ ")",'DevDataStore');

			//@todo ronp - call a function on the GlobalDataStore to allow it to log more detailed information
		}
	}

}

defaultproperties
{
   GlobalDataStoreClasses(0)="Engine.UIDataStore_Strings"
   GlobalDataStoreClasses(1)="Engine.UIDataStore_Images"
   GlobalDataStoreClasses(2)="Engine.UIDataStore_GameResource"
   GlobalDataStoreClasses(3)="Engine.CurrentGameDataStore"
   GlobalDataStoreClasses(4)="Engine.UIDataStore_SessionSettings"
   GlobalDataStoreClasses(5)="Engine.UIDataStore_Fonts"
   GlobalDataStoreClasses(6)="Engine.UIDataStore_Color"
   GlobalDataStoreClasses(7)="Engine.UIDataStore_Gamma"
   GlobalDataStoreClasses(8)="Engine.UIDataStore_Registry"
   GlobalDataStoreClasses(9)="UTGame.UTUIDataStore_Options"
   GlobalDataStoreClasses(10)="UTGame.UTUIDataStore_MenuItems"
   GlobalDataStoreClasses(11)="UTGame.UTDataStore_GameSettingsDM"
   GlobalDataStoreClasses(12)="UTGame.UTDataStore_GameSearchDM"
   GlobalDataStoreClasses(13)="UTGame.UTUIDataStore_CustomChar"
   GlobalDataStoreClasses(14)="UTGame.UTUIDataStore_StringList"
   GlobalDataStoreClasses(15)="UTGame.UTDataStore_OnlineStats"
   GlobalDataStoreClasses(16)="UTGame.UTUIDataStore_StringAliasMap"
   GlobalDataStoreClasses(17)="UTGame.UTUIDataStore_Content"
   GlobalDataStoreClasses(18)="UTGame.UTUIDataStore_2DStringList"
   PlayerDataStoreClassNames(0)="Engine.PlayerOwnerDataStore"
   PlayerDataStoreClassNames(1)="Engine.UIDataStore_PlayerSettings"
   PlayerDataStoreClassNames(2)="Engine.UIDataStore_OnlinePlayerData"
   PlayerDataStoreClassNames(3)="UTGame.UTUIDataStore_StringAliasBindingsMap"
   Name="Default__DataStoreClient"
   ObjectArchetype=UIRoot'Engine.Default__UIRoot'
}