The Paper - Page 11 - File Access Part 1

The Workflow of C++ Game-Development on a Series 60 Platform device

Andreas Jakl, Revision 1.0, July 2004

4.3 File access

On mobile devices, applications can not be sure they will be exited through the menu. For example it might be that the device switches off because of an empty battery. Therefore, frequently saving the game progress is very important, especially in an adventure game. Part 2 of the high score tutorial has been very helpful [4].

In The Journey, the game is saved automatically every time the player progresses in the game. This behavior has to have four key functions:

Drive path

Users should be able to install the applications on the memory card, as space on the device itself is limited. You have to make sure that the game is compatible with that, and that the drive letter is retrieved during runtime. Giving users a choice about the installation location is enabled by using a ! instead of the drive letter in the .pkg file.

File exists

To be able to decide whether to offer the additional option to continue the game or only to start a new game, a function has to check whether a progress file already exists.

Saving

In the case of The Journey, all game data has to be saved that is needed to put the game into exactly the same state as it had been when the user left the game.

Loading

When loading a previously saved game, everything must be back to the correct state again. For example, the timer might have to be restarted.

For the following examples the filename has been set globally using: _LIT(KFileStore, "Progress.dat");

4.3.1 Drive path

It is very convenient to have a function that adds the full system path of the application to a filename. To provide this functionality outside of the AppUi class, several header files have to be included.

    #include <eikenv.h>
    #include <bautils.h>
    #include <eikappui.h>
    #include <eikapp.h>

This function requires the filename as the first parameter and puts the resulting string consisting of the filename and its full path into the second parameter (pass by reference).

There is no direct function to retrieve the application path, so first it is necessary to get the full name and path of the application DLL. Based on this string, a useful utility function is able to extract only the drive letter and the path, removing the application name from the string. Finally, the filename can be appended to the path.

    const void AppendFullPath(const TDesC& aFilename,
                              TFileName& aFullName)   {
        TFileName appNamePath;

        // Get the full name and path of the application
        appNamePath = CEikonEnv::Static()->EikAppUi()->
                      Application()->AppFullName();
        // Gets the drive letter and path from a file name.
        aFullName   = BaflUtils::DriveAndPathFromFullName
                      (appNamePath);

        // Always use c drive letter for the emulator.
        #if defined(__WINS__)
        aFullName.Replace(0,1,_L("c"));
        #endif

        // Combine the path and the filename
        aFullName.Append(aFilename);
    }

4.3.2 File exists

One method to check if a file exists is to try to open it in read only mode and check for a file not found error code ( KErrNotFound ). Because of the client-server model of file access in Symbian, the file server session ( RFs iFileServerSession; ) does not have to be created like an object, it is just necessary to connect to it ( iFileServerSession.Connect(); ) and close the connection ( iFileServerSession.Close(); ) when it is no longer needed. This is done outside of the loading function.

    TBool GameProgressFileExists() {
        TBool returnVar = ETrue;
        TFileName fullName;
        AppendFullPath(KFileStore, fullName);

        // Try to open the file
        RFile checkFile;
        TInt errorCode = checkFile.Open(iFileServerSession,
                         fullName, EFileRead);
        // If the file is not found, return false.
        if (errorCode == KErrNotFound)
            returnVar = EFalse;

        // Close the handle to the file
        checkFile.Close();

        return returnVar;
    }