API Reference | developer.brewmp.com API Reference | developer.brewmp.com

Developer

API Reference

AEECLSID_SETTINGSINIFACTORY

Brew Release
Brew MP 1.0.2
See Also
AEEISettingsStoreFactory.h AEEISettings.h AEESettingsReg.bid
Description
SettingsIniFactory is an implementation of ISettingsStoreFactory that provides an ISettings implementation (SettingsIniStore) that allows access to ini file-based settings stores.
Store Information string format:
The format of the store information string provided to SettingsIniFactory during an ISettingsStoreFactory_Create() call is defined as follows:
      "owner=[clsid],path=[filepath],enableEscapeChars=[enableEscapeChars]"

Characters before or after the string as shown above are ignored.
      [clsid]
         the class id in hex format (e.g. "0xdeadbeef") of the owner module.
   
      [filepath]
         the file system path, either relative to the owning module's directory
         or an absolute path (beginning with 'fs:/'), where the settings file is
         stored.

      [enableEscapeChars]
         Optional, defaults to "0". When set to "1", adds escape character
         support to settings values as follows:
           - During calls to ISettings_Get(), escape characters in the value
             read from the .ini file will be automatically decoded prior to
             being returned to the caller.
           - During calls to ISettings_Set(), the value will be automatically
             encoded with escape characters prior to being stored in the .ini
             file.
           - Valid escape sequences in the .ini file are:
               \\       Backslash (escaping the escape character)
               \EOL     Line continuation
               \;       Semicolon

If a relative path is provided, the "owner" parameter is used to construct the full path, e.g. "fs:/~[clsid]/[filepath]".
Standalone Usage: A SettingsIniStore may be created standalone using the ISettingsStoreFactory interface by providing the path to the .ini file in the ISettingsStoreFactory_Create() method. With the returned ISettings object, the caller may get, set, delete, reset, and enumerate the settings provided by the .ini file. However, a standalone SettingsIniStore does not support change notifications.
Native Settings Usage: Modules may create a .ini file-based native settings store by adding the following to the module's .cif file:
 
   local s = require 'SettingsCIFHelpers'
   s:RegisterIniFile {
      owner = 0xdeadbeef,
      key = "/myApp/myIniSettings",
      file = "myinifile.ini",
      args = { ... },         -- optional
      acls = { ... },         -- optional
   }


When the RegisterIniFile helper function is used, FS ACLs are automatically created for both the default and journal files to grant the NativeSettings service class read/write privilege. See the Privileges section below for more information about FS ACLs.
See AEESettingsReg.bid for more information on native settings.
Default Settings: SettingsIniStore supports default settings. The default setting .ini file is never modified by SettingsIniStore. Rather, changes to the defaults are reflected in a journal.
When SettingsIniStore retrieves a particular setting, it uses the URI to locate the actual setting store. SettingsIniStore first looks into the setting store journal for the requested setting. If the journal is present and the setting exists within it, the value from the journal is returned. If the journal does not exist or if the setting is not present within it, SettingsIniStore returns the value from the default setting store.
When SettingsIniStore modifies the value of a particular setting, it makes a copy of the setting in the journal and the new value is stored there. The next time the setting is accessed, the modified value located in the journal is returned.
Settings that are added are stored in the journal. Settings that are deleted are stored as special entries in the journal, indicating that they are deleted. The setting store default is never modified.
The fact that settings are stored in a default read-only file and a modifiable journal is transparent to the user of SettingsIniStore.
The journal file's name is identical to the defaults file but has an 'x' appended to the end of the file's extension (e.g. file.inix).
Default Interface Name