Simulation PSY Settings API

Purpose

Simulation PSY loads a data file which contains simulated position data. As an application developer, you can create your own data files containing simulated position data to test your applications.

The API described in this document allows you to set two properties:

• The name of the data file loaded by Simulation PSY.

  If you create your own data file, you must use this API to tell the PSY where to find it.

• The Data Set Mode used by Simulation PSY.

  The Data Set Modes are described in Simulation PSY User Guide.

The Simulation PSY Settings API uses the Central Repository API.

API specification

The Simulation PSY Settings API defines two Central Repository keys:

• KCRKeySimPSYSimulationFile defines the location of the simulation data file that Simulation PSY uses as its source of position data.

• KCRKeySimPSYCommonDataSet defines whether the PSY operates in Independent Data Set Mode or Common Data Set Mode.

  For more information see Simulation PSY User Guide.

The keys are defined in the header file SimulationPSYInternalCRKeys.h.

Using the Simulation PSY Settings API

Setting the data file

To change the data file that Simulation PSY uses as its source of position data, an application must set a fully qualified file name before opening its client subsession. Simulation PSY reads the data file name from the Central Repository when a subsession that uses the PSY is opened.

To set a file name, a client application must:

• Open a repository using the Central Repository UID KCRUidSimulationPSY.

• Write a fully qualified filename of type TDesC16 to the key KCRKeySimPSYSimulationFile.

• Close the repository

If a client does not set the data file name, Simulation PSY tries to use the default NMEA data file default.nme. If this default data file is missing, the PSY operates in Fixed Data Mode as described in Simulation PSY User Guide.

Setting the Data Set Mode

To set the Data Set mode, a client must:

• Open a repository using the Central Repository UID KCRUidSimulationPSY.

• Write a value to the key KCRKeySimPSYCommonDataSet.

  Set a value of 1 if the Common Data Set mode is required.

  Set a value of 0 if Independent Data Set mode is required. This is the default setting.

• Close the repository

In practice you will probably want to set the data file and the Data Set Mode as part of the same operation. An example is shown below.

#include <centralrepository.h>
#include <SimulationPSYInternalCRKeys.h>
...

// Declare a data file containing simulated movement data

_LIT(KSimulationFile, "c:\\system\\data\\simulationData.sps" );

// Open a repository
CRepository* repository = CRepository::NewLC(KCRUidSimulationPSY);

// Set the simulation file
User::LeaveIfError(repository->Set(KCRKeySimPSYSimulationFile, KSimulationFile));

// Set Common Data Set mode
User::LeaveIfError(repository->Set(KCrKeySimPSYCommonDataSet, 1);

// Close the repository
CleanupStack::PopAndDestroy(repository);

// ‘KSimulationFile’ is ready for use.

Note: Capability WriteDeviceData is required to write the Central Repository settings.

Code architecture

Figure 1. Figure 1: Files needed by a Simulation PSY Settings client

The centralrepository.lib file contains information needed at link time by the client. The centralrepository.dll file contains the run-time information.