How to read a simple string resource

The simplest use of a resource file involves reading string resources.

Resources are defined in terms of structs. In general, structs need to be defined, assuming that pre-defined structs are not being used. In the following code fragments, a struct of type STRING is defined that has a single member of type LTEXT.

The resource file can contain just the following text:

// define structures

STRUCT STRING
    {
    LTEXT text;
    }

// define resources

RESOURCE STRING hello
    {
    text=”Bonjour tout le monde!”;
    }

From this, the resource compiler generates two files:

• the .rsc file containing the resource data; this is the resource file that must be referred to at run-time by the RResourceFile class in the C++ code.

• the .rsg file is a generated header file that contains #define statements for each resource defined in the source file. In the resource file generated here, the only resource is called hello and the generated header file contains:

  #define HELLO 1

  Note that the name in the generated header file is converted to upper case.

The file containing the C++ code must #include the .rsg file in order to have access to the resource ids generated by the resource compiler. For example, for a project called ReadText, this might be:

#include “ReadText.rsg”

The C++ program initialises the RResourceFile object, specifying the filename of the resource file:

RResourceFile resourceFile;
    resourceFile.OpenL(fsSession,_L(“Z:\\system\\data\\ReadText.rsc”));

Because the resource file contains an RFile, it must use a session to the file server for its operations - this is the fsSession parameter to OpenL().

RResourceFile::AllocReadLC() is one of three functions that can be used to read a resource. It allocates a heap descriptor of sufficient length to contain the resource, reads in the binary data for the resource and pushes the heap descriptor’s address onto the cleanup stack. If a leave occurs while this heap descriptor is still on the cleanup stack, it is automatically popped off the cleanup stack and destroyed.

HBufC8* dataBuffer = resourceFile.AllocReadLC(HELLO);

The HELLO symbol is #defined to 1 by the statement in the #included .rsg file. This statement therefore reads resource number 1 from the .rsc file.

The resource data must be interpreted using a TResourceReader object. This provides access to the text string through a pointer descriptor, as the following code fragment shows:

TResourceReader theReader;
...
theReader.SetBuffer(datafBuffer);
TPtrC textdata = reader.ReadTPtrC();

In this example, once the resource data is no longer needed, the heap descriptor, dataBuffer, can be popped off the cleanup stack and destroyed:

CleanupStack::PopAndDestroy();

When all operations on the resource file are complete, the resource file can be closed:

resourceFile.Close();

Resource file format

Resource compilation