FileManager

Table of contents

• ModuleFileManager
• FilePathManager
  • Bundle file
  • Special folders
• CorePackage

ModuleFileManager

To use some static methods of ModuleFileManager, an include is necessary :

#include "ModuleFileManager.h"

A file content can be loaded in memory with static methods LoadFile or LoadFileAsCharString.

u64 flen;
// load file and add 0 at the end of content to make it a valid string 
CoreRawBuffer* txtfile = ModuleFileManager::LoadFileAsCharString(filename.c_str(), flen, sizeof(char));

The given file name can have a path or not. If no path is given, the file is searched using bundle, FilePathManager or CorePackage management mechanisms.

Some other utility static methods are available :

static	bool	SaveFile(const char *filename, u8* data, u64 length);
static	bool	RemoveFile(const char* filename);
static	bool	CoreCopyFile(const char *sourceFilename, const char *destFileName, int buffLen=2048);

fopen/fclose/fread/fwrite... like methods are available :

// global functions
extern SmartPointer<FileHandle> Platform_fopen(const char* name, const char* mode);

bool		Platform_fopen(FileHandle* handle, const char* mode);
long int	Platform_fread(void* ptr, long size, long count, FileHandle* handle);
long int	Platform_fwrite(const void* ptr, long size, long count, FileHandle* handle);
long int	Platform_ftell(FileHandle* handle);
int		Platform_fseek(FileHandle* handle, long int offset, int origin);
int		Platform_fflush(FileHandle* handle);
int		Platform_fclose(FileHandle* handle);
bool		Platform_remove(FileHandle* handle);

FilePathManager

To use FilePathManager, an include is necessary :

#include "FilePathManager.h"

When no special path is specified, files are accessed in assets folder by default. Search paths can be added per file extension of for all file extension :

// get FilePathManager singleton
SP<FilePathManager>& pathManager = KigsCore::Singleton<FilePathManager>();
// search xml in root directory
pathManager->AddToPath(".", "xml");
// and in Skin2 directory
pathManager->AddToPath("Skin2", "xml");
// ask pathManager to search files preferably in Level1 folder 
pathManager->AddToPath("Level2", "*");

Search paths can also be removed :

pathManager->RemoveFromPath("Level2","*");

To check if a file exist (can be found), the method FindFullName can be used :

// check that a file can be found
auto f=pathManager->FindFullName("FileNotFound.txt");
if (f->mStatus & FileHandle::Exist)
{
  // do something with file
}

It's also possible to give a path+file name to the methods if the path is known :

// this time the file will be found even if Skin3 is not added to pathes
auto f=pathManager->FindFullName("Skin3/FileNotFound.txt");

Bundle file

Using the tool BundleList (browse the code) it is possible to create an ASCII file containing all the files available in a given folder.

A bundle file looks like that :

AppInit.xml;
LaunchScreen.xml;
Logo.png;
Screen_Main.xml;Skin1/;Skin2/

Here AppInit.xml, LaunchScreen.xml, Logo.png files are in the root directory, and two files Screen_Main.xml are available in Skin1 and Skin2 folders.

For DataDrivenApplication application, a bundle file can be loaded automatically by giving it's name in AppInit.xml :

<Attr Type="string" N="BundleFileName" V="files.bundle" Dyn="true"/>

It's also possible to load it with the FilePathManager with method InitBundleList.

void	InitBundleList(const std::string& filename);

Once a bundle list is set-up, when giving a file name without a path, FilePathManager will use the bundle to search full path of the file. If several paths are found, then FilePathManager will check if a path is preferred (previously added with AddToPath).

Special folders

Depending on the platform, special folders are available. The enum giving the list of special folders is available in FilePathManager :

enum	DeviceID
{
	RESSOURCES				=	0,
	CARD_STORAGE				=	1,
	DEVICE_STORAGE				=	2,
	APPLICATION_STORAGE			=	3,
	RESERVED1				=	4,
	DOCUMENT_FOLDER				=	5,
	DB_STORAGE				=	6,
	DRIVEA					=	10,
	DISTANT_FOLDER1				=	20,
	DISTANT_FOLDER2				=	21,
	DISTANT_FOLDER3				=	22,
	DISTANT_FOLDER4				=	23,
	EXTERN_FOLDER1				=	30,
	EXTERN_FOLDER2				=	31,
	EXTERN_FOLDER3				=	32,
	EXTERN_FOLDER4				=	33,

};

RESSOURCES folder is the one used by default when accessing files with only a classic file name.

A path using a special folder can be construct using FilePathManager::DevicePath static method like that :

// open a file for write in document folder
file = Platform_fopen(FilePathManager::DevicePath("KigsTestFileManagerSave.txt", FilePathManager::DOCUMENT_FOLDER).c_str(), "wb");
if (file->mFile)
{
	std::string towrite = "write in the document directory";
	int readsize = Platform_fwrite(towrite.c_str(), 1, towrite.length(), file.get());

	Platform_fclose(file.get());
}

AddToPath and RemoveFromPath methods also have a optional DeviceID parameter.

The two main special folders (except RESSOURCES the default one) are APPLICATION_STORAGE and DOCUMENT_FOLDER.

CorePackage

To use CorePackage, an include is necessary :

#include "CorePackage.h"

It's possible to create file archives using the tool KigsPackager (browse the code). A package is a files and folders hierarchy all in a single file. KigsPackager does not compress files.

After loading a CorePackage with LoadPackage method :

if (pathManager->LoadPackage("someAssets.kpkg"))

Several packages can be loaded at the same time. All files in the packet can be accessed like if they where in the asset folder, and loading a CorePackage update automatically the bundle list, so that it's not necessary to give the full path of the file to access it.

Packages can also be unloaded :

pathManager->UnloadPackage("someAssets.kpkg");

Find all the sample code from this Wiki section in testFileManager project (browse the code)