Class for file handling in Guiliani. More...
#include <GUIResourceFileHandler.h>
Public Types | |
| enum | BufferingStrategy_t { BUFFERING_OFF = 0, BUFFERING_ALWAYS, BUFFERING_DEFAULT } |
| Enumeration for the buffering strategy to use when opening a file. More... | |
| enum | FileOpenOrder_t { RESOURCE_FILE_FIRST, RESOURCE_FILE_LAST } |
| 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, const eC_Bool &bEmulateROMFile=false) |
| void | SetResourcePathPrefix (const eC_String &kResourcePrefix) |
| void | UnloadResourceFile () |
Static Public Member Functions | |
| static void | CreateInstance () |
| static void | DeleteInstance () |
Friends | |
| class | CGUIComponentManager |
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:
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.
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:
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.
Example:
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.
Guiliani Resource Compiler is a tool which allows you to create in one file all the information that will be needed for your application.
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.
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:
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.
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.
A resource header file is a C++ header which defines an array (eC_UByte GUIResourceFileData[]). See also CGUIResourceFileHandler::SetResourceData(eC_UByte* pubResourceData)
Finally, you choose one of these options and write the name of the output file.
| 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.
| kResourceName | the name of the resource which will be used when calling Open |
| uiResourceSize | the size of the resource in bytes |
| pubResourceLocation | byte-pointer to the actual memory |
| 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);
| file | pointer to eC_File, which should be closed (deleted) |
|
static |
Create Instance
| 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.
|
static |
Delete Instance
| 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.
| kPath | Path of file (will not be prefixed with ResourcePrefix) |
| uiFileSize | File size in byte in case of success. Undefined in case of failure. |
| ppubData | Pointer to first byte of file data in case of success, otherwise NULL. |
|
inline |
Returns the resource path prefix.
| 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.
| kPath | eC_String with path of file (will be automatically prefixed with current ResourcePathPrefix) |
| eBufferingStrategy | Specifies 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. |
| eC_Bool CGUIResourceFileHandler::RemoveMemoryResource | ( | const eC_String & | kResourceName) |
Removes a previously loaded memory-resource from internal lookup this does NOT free the attached memory!
| kResourceName | the name of the resource to remove |
| eC_Bool CGUIResourceFileHandler::RemoveResourceData | ( | const eC_UByte * | pubResourceData) |
Unload a previously loaded resource-header.
| pubResourceData | pointer to resource data. |
| eC_Bool CGUIResourceFileHandler::RemoveResourceFile | ( | const eC_String & | rkResourceFilePath) |
Unloads the given resource-file archive.
| rkResourceFilePath | Path name to resource file. (Will automatically be prefixed with ResourcePathPrefix) |
|
inline |
Set buffering strategy for loading files from disk.
| bBufferFileFromDisk | Specifies whether the resource file handler should try to buffer the file in memory. |
|
inline |
Sets the file open order.
| eFileOpenOrder | Which order for file opening: RESOURCE_FILE_FIRST, RESOURCE_FILE_LAST. |
|
inline |
Set buffering strategy for loading files from resourcefile-header.
| bBufferHeader | Specifies whether the resource file handler should try to buffer the data in RAM. |
| 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
| pubResourceData | pointer to resource data. |
| eC_Bool CGUIResourceFileHandler::SetResourceFile | ( | const eC_String & | rkResourceFilePath, |
| const eC_Bool & | bEmulateROMFile = false |
||
| ) |
Loads the given resource-file archive. All subsequent "open file"-operations will search for the files within this resource-file.
| rkResourceFilePath | Path name to resource file. (Will automatically be prefixed with ResourcePathPrefix) |
| bEmulateROMFile | if true the file is treated as if it were in static Flash-Memory |
| 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".
| kResourcePrefix | The new path prefix |
| 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(...).
|
friend |
1.8.4 
