|
STG (Settings) Library |
Top Previous Next |
The STG library offers a persistent, convenient storage for your device's settings (operational parameters). All you have to do is list all desired settings in a descriptor file included in your project (settings.txt by default). This file will define the names, types, value constraints, etc. of your device's settings and the STG library will automatically calculate memory addresses for storing settings, protect the settings with a checksum, verify the validity of their values, etc. You code will be able to store and retrieve setting values simply by calling setting by their names, like this: s=stg_get("IP",0) or stg_set("IP",0,"192.168.1.40").
The library keeps your settings in the non-volatile memory or RAM. The non-volatile memory used can be the EEPROM memory (stor.) or the flash disk (fd.). For RAM, you can choose to go with "regular" RAM (the one that stores variables), or "custom" RAM, for which you can create your own access routines.
Library Info
Supported platforms: |
Any platform. |
Files to include: |
settings.tbs, settings.tbh (from current_library_set\settings\trunk*). |
Dependencies: |
FILENUM library when STG_STORAGE_MEMORY is 1. |
API procedures: Use API procedures to interact with the library. |
stg_start() -- starts the STG library, parses the descriptor file, restores all volatile (RAM) settings to default values. stg_check_all() -- verifies each setting by reading its value. stg_get_def() -- returns the default value for the specified setting's member. stg_restore_multiple() -- initializes (sets the default values for) all or multiple settings. stg_restore_member() -- initializes (sets the default value for) the specified setting's member. stg_get_num_settings() -- returns the number of settings defined in your project. stg_get_num_members() -- returns the number of members for the specified setting. stg_find() -- returns the number of the specified setting or zero if the setting wasn't found. stg_stype_get() -- returns the type of the specified setting. stg_get() -- reads (gets) the value of the specified setting's member; reports errors through callback_stg_error(). stg_set() -- writes (sets) the value of the specified setting's member; reports errors through callback_stg_error(). stg_sg() -- writes (sets) or reads (gets) the specified setting's member; directly returns the execution result. stg_sg_ts() -- available when STG_TIMESTAMP is "1", reads or writes the modification timestamp of the setting. |
Event procedures: |
--- |
Callback procedures: Implement the bodies of callback procedures elsewhere in your project. |
callback_stg_error() -- informs of the error during the execution of stg_get() or set_set(). callback_stg_pre_get() -- informs that the setting member's value is being read through one of the STG library's procedures; allows to update the setting member's value before it is returned by the STG library. callback_stg_post_set() -- informs that the setting member's value is being written to through one of the STG library's procedures; allows to respond to the value change. callback_stg_vm_read() -- should implement necessary code for reading a byte of data from "custom" volatile memory. Needed only when STG_RAM_TYPE is 1. callback_stg_vm_write() -- should implement necessary code for writing a byte of data to "custom" volatile memory. Needed only when STG_RAM_TYPE is 1. |
Required buffer space: |
--- |
*Current library set can be selected in the New Project and Project Settings dialogs.