Guiliani  Version 2.4 revision 5970 (build 3)
CGUIResourceFileHandler Class Reference

Class for file handling in Guiliani. More...

#include <GUIResourceFileHandler.h>

Public Types

 Enumeration for the buffering strategy to use when opening a file. More...
 Enumeration for the order in which files are opened. More...

Public Member Functions

eC_Bool AddMemoryResource (const eC_String &kResourceName, const eC_UInt uiResourceSize, eC_UByte *pubResourceLocation)
eC_Bool Close (eC_File *file)
void DeInit ()
eC_Bool GetFileInformation (const eC_String &kPath, eC_UInt &uiFileSize, const eC_UByte **ppubData)
const eC_String & GetResourcePathPrefix () const
eC_File * Open (const eC_String &kPath, const BufferingStrategy_t eBufferingStrategy=BUFFERING_DEFAULT)
eC_Bool RemoveMemoryResource (const eC_String &kResourceName)
eC_Bool RemoveResourceData (const eC_UByte *pubResourceData)
eC_Bool RemoveResourceFile (const eC_String &rkResourceFilePath)
void SetDiskBuffering (eC_Bool bBufferFileFromDisk)
void SetFileOpenOrder (const FileOpenOrder_t eFileOpenOrder)
void SetHeaderBuffering (eC_Bool bBufferHeader)
eC_Bool SetResourceData (const eC_UByte *pubResourceData)
eC_Bool SetResourceFile (const eC_String &rkResourceFilePath)
void SetResourcePathPrefix (const eC_String &kResourcePrefix)
void UnloadResourceFile ()

Static Public Member Functions

static CGUIResourceFileHandlerGetInstance ()

Detailed Description

Class for file handling in Guiliani.

This class abstracts file access within Guiliani. Essentially you have four choices on how to store your application's resources:

  1. As independent files on a file-system
  2. As one big resource-file archive
  3. Compiled into the application's executable (as a header)
  4. Flashed to some fixed address on the target board

The GUIResourceFileHandler makes the handling of these different modes transparent to the application. In other words, the application can simply open a given file (read only) without needing to know whether it exists as a standalone file on the file system, whether it resides inside a resource-archive, or whether it was compiled directly into the executable.

Additionally, it is also possible to define the order in which the GUIResourceFileHandler will be searching for a resource. Suppose for example that you have all your resources in one big resource-file archive, but wish to exchange one single png-image. In this case you can simply copy the png-image onto the file system, and then call the SetFileOpenOrder interface with the parameter set to RESOURCE_FILE_LAST. This effectively tells the GUIResourceFileHandler to search for resources on disk first, and only afterwards search for them inside a resource-file archive or resource-header. Searching for files on disk first and after in resource-files is the default behavior.

The methods SetDiskBuffering and SetHeaderBuffering can be used to set a buffering strategy when loading files from disk or from a statically linked resource. This can be helpful when the resourcefile-header is located in slow flash and you want to optimise access speed. By default, buffering for opening files from disk is true and from resource-headers is false, to prevent unnecessary memory usage. It's possible to override the previously set buffering strategy by calling the Open-method with a BufferingStrategy_t parameter.

For creating resource-files or resource-headers please use the GUIResourceCompiler(see CGUIResourceCompiler) tool that comes with Guiliani. Please note that ResourceFiles will _always_ be in big endian. They need to have one common endianess across all possible targets to ensure exchangability of resource files between platforms.

Usage example

The following example code demonstrates how to use resource-files and resource-headers in your application. You will typically place these calls somewhere within your startup code:

// Use of unified resource file:
// Use resources which were compiled directly into the executable
// Use resources which are flashed to some fixed address (in this example 0xDEADBEEF)

Using resources directly from memory

In some applications the user has a memory location where a device, e.g. a camera, places image data which should be used within Guiliani. To achieve this the functions AddMemoryResource and RemoveMemoryResource can be used. This method of memory-usage does not interfere with using Resource-Files or Resource-Headers as shown previously, instead it enhances the existing possibilities within Guiliani.

AddMemoryResource takes a unique identifier-string, the size of the resource and the address of the memory where the data resides and adds it to an internal structure so Guiliani can handle it. Subsequent calls to AddMemoryResource with the same identifier replaces the resource previously loaded with this ID. RemoveMemoryResource removes the memory-resource with the given identifier.

Both functions do NOT allocate or free any memory related to the specified memory-location. So all memory-management has to be done by the user.


// somewhere a memory buffer was allocated and an image with 12345 bytes length was loaded
AddMemoryResource("DataFromCamera", 12345, MemoryLocationOfCameraData);
// bind an image-ID for use in Guilani to the memory-resource
ImageResource_t ImageIDofCameraData = GETRESMANAGER.RegisterDynamicImage("DataFromCamera");
// use the memory-resource for an image in the GUI
CGUIImage* image = new CGUIImage(parent, 0, 0, ImageIDofCameraData);

The ResourcePathPrefix

In most cases you will have your resources in some dedicated subfolder, or in a location relative to your executable file. To avoid having Pathnames hard-coded in all your filenames you should use the SetResourcePathPrefix interface. The prefix you supply there will then be added to the beginning of your filenames during all "file open"-calls. This also comes in handy if you are working on a system which requires all file operations to be using absolute paths.

// Setting a path prefix, which points to the location where resources are stored


Guiliani Resource Compiler is a tool which allows you to create in one file all the information that will be needed for your application.

Why use one file instead of the exact files that you need?

Some devices don't have a file system included. Therefore, you just need one file to load in the memory device instead of all the files.

How to use it?

This is just an example to show how to use this tool.

As you can see, the next picture below shows the different options:


In this case we will choose the second option, "add paths from the input file". Then you need to write the file where you have the paths of all files that you need. For example, "FilesNeeded.txt". Keep in mind that there can be only one path per line in the input file.


Then you write the name of the input file:


If everything is good the tool will tell you that the files were added.


To see the files you have already added you can use the option "show file list" and it will show the files like the next picture shows:


Perhaps you will realise that there are more files that need to be added. If you want to add some more files, you can again do it with "add paths from the input file". The new paths will add with the paths which you added before. Moreover, you can do it manually each file with the first option "add path to file list".


To see the new file included we again use the option "show file list"


When you are done with adding all the files, you can then create the output file. As you can see there are two different options to create the file:

  • "create resource file"
  • "create header file"

The main difference is the way how they have been created. The first one, the executable file will need the resource file with the information. In the second one the header file must be included and compiled into your project before and there will be no other files than the executable file.

Here are the pictures which show how is structure the information inside of the output file according to the option that you choose.

Resource File


On the top of the file there is the information about the files and then the content of them. See also CGUIResourceFileHandler::SetResourceData(eC_String & pkRCPath)


The paths of the input file have to be the same than the file name in the content.

Header File


A resource header file is a C++ header which defines an array (eC_UByte GUIResourceFileData[]). See also CGUIResourceFileHandler::SetResourceData(eC_UByte* pubResourceData)

This option is the same as if you generate a resource file. The input file paths have to be the same than the file name in the content.

Finally, you choose one of these options and write the name of the output file.


Member Enumeration Documentation

◆ BufferingStrategy_t

Enumeration for the buffering strategy to use when opening a file.


Do not use buffering.


Always use.


Use previously set buffering strategy.

◆ FileOpenOrder_t

Enumeration for the order in which files are opened.


First try opening from resource file.


First try opening from disk.

Member Function Documentation

◆ AddMemoryResource()

eC_Bool CGUIResourceFileHandler::AddMemoryResource ( const eC_String &  kResourceName,
const eC_UInt  uiResourceSize,
eC_UByte *  pubResourceLocation 

Add a new memory resource this inserts a memory location to the internal lookup, so a call to Open results in returning an eC_File pointing to this memory location. By using this interface GraphicsWrapper and other resource-users can also deal with previously loaded files or memory locations filled by other devices. If a memory-location was already added with the given name it will be overwritten.

kResourceNamethe name of the resource which will be used when calling Open
uiResourceSizethe size of the resource in bytes
pubResourceLocationbyte-pointer to the actual memory
true if successful otherwise false

◆ Close()

eC_Bool CGUIResourceFileHandler::Close ( eC_File *  file)

Close files which were opened with the handler. This function deletes buffers which are used in RESOURCE_FILE mode, and deletes the eC_File. The pointer to eC_File is invalid after closing, because it was deleted by ResourceFileHandler. To close a file in Guiliani use GETRESHANDLER.Close(pMyFile);

filepointer to eC_File, which should be closed (deleted)
True if file was closed(deleted), False if file was not opened with ResourceFileHandler.

◆ DeInit()

void CGUIResourceFileHandler::DeInit ( )

Should only be called by the destructor. As a workaround for memory leak detection ~CGUI() may call it too, but it is forbidden to be called by other code.

◆ GetFileInformation()

eC_Bool CGUIResourceFileHandler::GetFileInformation ( const eC_String &  kPath,
eC_UInt &  uiFileSize,
const eC_UByte **  ppubData 

Retrieves information about a file within a ResourceHeader. A ResourceHeader needs to be set via SetResourceData() prior to calling GetFileInformation(). The file with the given name will be searched within the ResourceHeader, and its size will be returned in uiFileSize.

kPathPath of file (will not be prefixed with ResourcePrefix)
uiFileSizeFile size in byte in case of success. Undefined in case of failure.
ppubDataPointer to first byte of file data in case of success, otherwise NULL.
True if the file was found within the ResourceHeader, False otherwise.

◆ GetInstance()

static CGUIResourceFileHandler& CGUIResourceFileHandler::GetInstance ( )
pointer to resource file handler instance

◆ GetResourcePathPrefix()

const eC_String& CGUIResourceFileHandler::GetResourcePathPrefix ( ) const

Returns the resource path prefix.

The path prefix that is used for all resources.

◆ Open()

eC_File * CGUIResourceFileHandler::Open ( const eC_String &  kPath,
const BufferingStrategy_t  eBufferingStrategy = BUFFERING_DEFAULT 

Opens a file. This will either load the file from disk, from a resource-file or from a resource-header. Please refer to SetFileOpenOrder() for details on how to specify the order in which to search for a file on disk, in a resource-file or a resource-header. All files will be opened in READ-ONLY mode. If you wish to open a file from disk with WRITE-ACCESS, use CGUIFileSysWrap instead. In your application use eC_File* pMyFile = GETRESHANDLER.Open(kPath); You must close the file using GETRESHANDLER.Close(pMyFile) after use.

kPatheC_String with path of file (will be automatically prefixed with current ResourcePathPrefix)
eBufferingStrategySpecifies the buffering strategy the resource file handler uses to open the file. BUFFERING_OFF, BUFFERING_ALWAYS or BUFFERING_DEFAULT When BUFFERING_DEFAULT is used the previously set buffering-strategy for loading from disk or header is used.
Pointer to eC_File if file was found and opened, NULL if not.

◆ RemoveMemoryResource()

eC_Bool CGUIResourceFileHandler::RemoveMemoryResource ( const eC_String &  kResourceName)

Removes a previously loaded memory-resource from internal lookup this does NOT free the attached memory!

kResourceNamethe name of the resource to remove
true if successful otherwise false

◆ RemoveResourceData()

eC_Bool CGUIResourceFileHandler::RemoveResourceData ( const eC_UByte *  pubResourceData)

Unload a previously loaded resource-header.

pubResourceDatapointer to resource data.
True if unload was successful, False if not

◆ RemoveResourceFile()

eC_Bool CGUIResourceFileHandler::RemoveResourceFile ( const eC_String &  rkResourceFilePath)

Unloads the given resource-file archive.

rkResourceFilePathPath name to resource file. (Will automatically be prefixed with ResourcePathPrefix)
True if unload was successful, False if not

◆ SetDiskBuffering()

void CGUIResourceFileHandler::SetDiskBuffering ( eC_Bool  bBufferFileFromDisk)

Set buffering strategy for loading files from disk.

bBufferFileFromDiskSpecifies whether the resource file handler should try to buffer the file in memory.

◆ SetFileOpenOrder()

void CGUIResourceFileHandler::SetFileOpenOrder ( const FileOpenOrder_t  eFileOpenOrder)

Sets the file open order.

eFileOpenOrderWhich order for file opening: RESOURCE_FILE_FIRST, RESOURCE_FILE_LAST.

◆ SetHeaderBuffering()

void CGUIResourceFileHandler::SetHeaderBuffering ( eC_Bool  bBufferHeader)

Set buffering strategy for loading files from resourcefile-header.

bBufferHeaderSpecifies whether the resource file handler should try to buffer the data in RAM.

◆ SetResourceData()

eC_Bool CGUIResourceFileHandler::SetResourceData ( const eC_UByte *  pubResourceData)

Orders the ResourceFileHander to use the given Resource-header. The Resource-header is essentially a resource-file residing in memory (e.g. linked into the executable) Multiple calls to this method will result in multiple memory regions being loaded

See also
pubResourceDatapointer to resource data.
True if loading successful, False if not

◆ SetResourceFile()

eC_Bool CGUIResourceFileHandler::SetResourceFile ( const eC_String &  rkResourceFilePath)

Loads the given resource-file archive. All subsequent "open file"-operations will search for the files within this resource-file.

See also
rkResourceFilePathPath name to resource file. (Will automatically be prefixed with ResourcePathPrefix)
True if loading successful, False if not

◆ SetResourcePathPrefix()

void CGUIResourceFileHandler::SetResourcePathPrefix ( const eC_String &  kResourcePrefix)

Sets a path which will used as a prefix during all subsequent calls to Open(). E.g. First supplying "C:/Data/" as a ResourcePathPrefix and then calling Open("MyFile.png") will effectively try to open a file "C:/Data/MyFile.png".

kResourcePrefixThe new path prefix

◆ UnloadResourceFile()

void CGUIResourceFileHandler::UnloadResourceFile ( )

Reset the ResourcefileHandler. Unloads ALL ResouceFileData (deletes open files and buffers and headerdata). After calling this function a new resourcefile can be set with SetResourceData(...).

The documentation for this class was generated from the following files: