 |
VR-Forces 5.0.3 Developer's Guide
|
All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Properties Friends Macros Groups Pages
|
VR-Forces 5.0.3 Developer's Guide
|
DtVrfSettingsManager is a subclass of DtSettingsManager. The DtSettingsManager class lets you save run-time settings in an XML file. It is based on the boost::serialization library. (Boost is available from http://www.boost.org. The proper version of boost to use is listed in the VR-Forces Release Notes.) It can be used from any application.
DtVrfSettingsManager lets you remotely query and edit settings through custom messages that are supported by DtVrfRemoteController.
Related settings are grouped into a settings object derived from DtSettingsObject. For instance, a dead reckoning object would have the translation, rotation, and aggregate threshold values. If a class wants to register a single value without creating a settings object class, it can use DtBoolSetting, DtIntSetting, DtDoubleSetting, or DtStringSetting. The settings objects are there strictly for serialization - it is expected that the current values will be stored in a class that uses the Settings Manager to save them. When the current values for the settings objects are needed (to write out the settings file or to respond to a front-end request), the settings object is passed back to the client that is responsible for updating it. This means that the client does not have to ensure that the settings object is always up to date - it just needs to provide a function to do the updating. DtSettingsObjects are created by a DtSettingsObjectFactory.
The Settings Manager can save two types of settings - those that are owned by a client of the Settings Manager, and those that are maintained by the Settings Manager itself.
Any DtSettingsObject that will be produced by a client of the DtSettingsManager must be registered with the Settings Manager by the client. The client calls DtSettingsManager::registerProducer() with the type and the name of the setting and a DtSettingsProducerFcn and void* user pointer. The DtSettingsObject is not passed in; the client never transfers an actual object instance. The client just needs to tell the Settings Manager that it is responsible for the setting. The Settings Manager creates the object when necessary, and calls the DtSettingsProducerFcn any time it needs to access the value. For example, this happens when a call to DtSettingsManager::lookupSetting() or write() is made.
DtSettingsManager can also maintain settings on behalf of a client. In general this is only done when there is no central object that is responsible for the setting.
DtSettingsManager::lookupSetting() takes the name of the object the client is looking for. If the file fails to read, a null pointer is always returned to indicate that the value was not read in. If the name lookup in the settings map is successful, a const pointer to the requested member is returned.
Any object that wants to get a callback when a setting is changed can register itself as a consumer of that setting by calling DtSettingsManager::registerConsumer(). If the setting is designed to be changed remotely, the client registered as a producer must also register as a consumer so it can change itself when the setting is modified. The consumer function takes the name of the setting to be monitored, a DtSettingsConsumerFcn and a void* user pointer. These values are stored in a multi-map inside DtSettingsManager, which means that more than one DtSettingsConsumerFcn can be registered on a single setting. This makes it easier to support settings on an individual entity or component level, which do not have an intermediate manager class to deal them. The DtSettingsConsumerFcn returns a const DtSettingsObject and the void* user pointer to allow the client to update itself based on the new values.
DtVrfSettingsManager supports queries from DtVrfRemoteController based on string keys, and returns a copy of the same settings object being used in the back-end. This saves a lot of time because the custom messaging and callbacks required for the front-end to interrogate the back-ends are not necessary for each type of setting that needs to be transferred. The values returned are processed by the DtVrfBackendListener. The DtBackend class maintains a std::map() of DtSettingsObject for each back-end. DtBackend has a lookup method that takes the name of a settings object and returns a const pointer to the object, or 0 if it does not exist in the map.
DtVrfSettingsManager registers for the DtIfRequestSetting message, which allows retrieval of settings objects returned through the DtIfSetting message. DtIfRequestSetting contains a string that corresponds to a name of a setting registered in the manager. The DtIfSetting message contains a serialized copy of the settings object. When the DtVrfSettingsManager processes a DtIfRequestSetting message, the settings object is looked up through DtSettingsManager::lookupSetting() to insure that its DtSettingsProducerFcn gets called, so that the latest data from the settings producer is returned.
DtVrfRemoteController has a requestBackendSetting() method that takes a string that corresponds to the name of the DtSettingsObject, a DtSimulationAddress to address the query to, and a callback function, which will be called once the responses are received. In most cases, the address will be DtSimSendToAll, but it is also possible to pass in the address of a specific back-end. The DtVrfRemoteController passes the request to the DtVrfBackendListener. The DtVrfBackendListener receives the DtIfSettingResponse messages and stores the settings objects received in the corresponding DtBackends. It keeps track of each request made including the name of the setting requested, the back-ends that have not yet responded, and the callback function to call when the request is completed. Once the request is completed, the callback is called to indicate that all the responses have been received and it is now safe to iterate over the DtBackends and look up the setting by calling DtBackend::lookupSetting().
Remote VR-Forces applications can update the state of client objects by sending a DtIfModifySetting message. This message carries a serialized DtSettingsObject. The DtVrfSettingsManager listens for the modification messages, deserializes their payloads, and updates the existing object with the new one by calling DtSettingsManager::setSetting(). Objects that do not match any existing objects by name are ignored.
DtVrfRemoteController has a modifyBackEndSettingMethod() method, which takes a DtSettingsObject and a DtSimulationAddress. The object's name must correspond to a pre-existing back-end setting. The address defaults to DtSimSendToAll, but can also be targeted at specific back-ends. DtVrfRemoteController also has specialized methods to make the modify call on behalf of the user, for example setSpotReportsGloballyEnabled().
The settingsManager example demonstrates many techniques for working with the Settings Manager. The settingsManagerSim portion of the example is a back-end plug-in which demonstrates adding a new setting type, extending a built-in type, and creating a new instance of a Settings Manager which writes out its own file. The settingsManagerRemote portion of the example is a minimal front-end application which queries and modifies the Settings Managers in a back-end running with the settingsManagerSim plug-in. See the Settings Manager Extension Example for more details.
Public Member Functions | |
| DtVrfSettingsManager (DtVrfMessageInterface *msgIf, std::string simSettingsPath) | |
| DtVrfSettingsManager (DtVrfMessageInterface *msgIf) | |
| ~DtVrfSettingsManager () | |
| virtual void | init () |
| void | publishSetting (const std::string &settingName) |
 Public Member Functions inherited from DtSettingsManager | |
| DtSettingsManager (const std::string &filename) | |
| ~DtSettingsManager () | |
| virtual bool | read () |
| virtual bool | write () |
| virtual const DtSettingsObject * | lookupSetting (const std::string &name) |
| virtual bool | setSetting (const DtSettingsObject *settingsObject) |
| virtual std::list< std::string > | settingsMapKeys () |
| virtual void | registerProducer (const std::string &type, const std::string &name, DtSettingsProducerFcn producerFcn, void *usr=0) |
| virtual void | unregisterProducer (const std::string &type, const std::string &name, DtSettingsProducerFcn producerFcn, void *usr=0) |
| virtual void | registerConsumer (const std::string &name, DtSettingsConsumerFcn consumerFcn, void *usr=0) |
| virtual void | unregisterConsumer (const std::string &name, DtSettingsConsumerFcn consumerFcn, void *usr=0) |
| virtual void | addIndependentBool (const std::string &name, bool value) |
| virtual void | addIndependentInt (const std::string &name, int value) |
| virtual void | addIndependentDouble (const std::string &name, double value) |
| virtual void | addIndependentString (const std::string &name, const std::string &value) |
Static Public Member Functions | |
| static void | modifySettingCallback (DtSimMessage *msg, void *usr) |
| static void | requestSettingCallback (DtSimMessage *msg, void *usr) |
| Static Public Member Functions inherited from DtSettingsManager | |
| static DtSettingsObjectFactory * | factory () |
| static void | setFactory (DtSettingsObjectFactory *factory) |
Protected Attributes | |
| DtVrfMessageInterface * | myMessageInterface |
| Protected Attributes inherited from DtSettingsManager | |
| std::string | myFilename |
| DtSettingsMap | mySettingsMap |
| DtSettingsProducersMap | myProducersMap |
| DtSettingsConsumersMultiMap | myConsumersMultiMap |
| tbb::mutex | myConsumerMutex |
| tbb::recursive_mutex | myProducerMutex |
Additional Inherited Members | |
| Static Protected Attributes inherited from DtSettingsManager | |
| static DtSettingsObjectFactory * | theSettingsObjectFactory |
| DtVrfSettingsManager::DtVrfSettingsManager | ( | DtVrfMessageInterface * | msgIf, |
| std::string | simSettingsPath | ||
| ) |
Constructor.
| DtVrfSettingsManager::DtVrfSettingsManager | ( | DtVrfMessageInterface * | msgIf | ) |
Constructor.
| DtVrfSettingsManager::~DtVrfSettingsManager | ( | ) |
Destructor.
|
virtual |
Registers for DtIfModifySetting and DtIfRequestSetting. Calls down to DtSettingsManager::init().
Reimplemented from DtSettingsManager.
Reimplemented in DtVrfSimSettingsManager, and MySettingsManager.
|
static |
Registered for receipt of DtIfModifySetting messages.
|
static |
Registered for receipt of DtIfRequestSetting messages.
| void DtVrfSettingsManager::publishSetting | ( | const std::string & | settingName | ) |
Looks up (thereby implicitly updating) the DtSettingsObject corresponding to the given name and if is found, publishes it on the network in a DtIfSetting message.
|
protected |