This is the manager of settings at the KernelAPI level. More...

Classes
struct	SEnumTypeElement
	Descriptor structure of an enum type element. More...
Typedefs
typedef struct RECSTSSTRUCT *	HSETTING
	Handle of a setting.
Enumerations
enum	STSTYPES { STS_UNDEFINED, STS_ENUM, STS_INT, STS_DOUBLE, STS_BOOL, STS_STRING, STS_USTRING, STS_ARRAY_INT, STS_ARRAY_DOUBLE, STS_ARRAY_ENUM, STS_ARRAY_BOOL, STS_SET, STS_REF }
	Type ID's of settings. More...
Functions
RECERR RSTSAPI	kRecSettingGetHandle (HSETTING root_of_query, const char symb_name, HSETTING ret_handle, INTBOOL *has_setting)
	Getting the handle of a node.
RECERR RSTSAPI	kRecSettingHasSetting (HSETTING node, INTBOOL *has_setting)
	Querying whether it is a setting.
RECERR RSTSAPI	kRecSettingGetType (HSETTING sett, STSTYPES *type)
	Querying the type.
RECERR RSTSAPI	kRecSettingIsFlagSet (HSETTING sett, unsigned int flgs, INTBOOL *is_set)
	Querying flags.
RECERR RSTSAPI	kRecSettingGetName (HSETTING node, const char **the_name)
	Querying the name.
RECERR RSTSAPI	kRecSettingIsDefault (int sid, HSETTING node, INTBOOL *is_default)
	Checking whether the setting is default or not.
RECERR RSTSAPI	kRecSettingGetNextChild (HSETTING the_parent, HSETTING prev_child, HSETTING *the_child)
	Enumerating children.
RECERR RSTSAPI	kRecSettingGetCloneOrigin (HSETTING clone_node, HSETTING *origin_node)
	Accessing the origin of the clone node.
RECERR RSTSAPI	kRecSettingGetInt (int sid, HSETTING sett, int *the_value)
	Accessing the current value of an STS_INT or STS_ENUM or STS_BOOL setting.
RECERR RSTSAPI	kRecSettingGetDouble (int sid, HSETTING sett, double *the_value)
	Accessing the current value of an STS_DOUBLE setting.
RECERR RSTSAPI	kRecSettingGetString (int sid, HSETTING sett, const char **the_value)
	Accessing the current value of an STS_STRING setting.
RECERR RSTSAPI	kRecSettingGetUString (int sid, HSETTING sett, const WCHAR **the_value)
	Accessing the current value of an STS_USTRING setting.
RECERR RSTSAPI	kRecSettingGetIntArray (int sid, HSETTING sett, const int **the_value)
	Accessing the current value of an STS_ARRAY_INT or STS_ARRAY_ENUM or STS_ARRAY_BOOL or STS_SET setting.
RECERR RSTSAPI	kRecSettingGetDoubleArray (int sid, HSETTING sett, const double **the_value)
	Accessing the current value of a STS_ARRAY_DOUBLE setting.
RECERR RSTSAPI	kRecSettingGetIntArrayAt (int sid, HSETTING sett, int index, int *the_value)
	Accessing an element of an STS_ARRAY_INT or STS_ARRAY_ENUM or STS_ARRAY_BOOL or STS_SET setting.
RECERR RSTSAPI	kRecSettingGetDoubleArrayAt (int sid, HSETTING sett, int index, double *the_value)
	Accessing an element of an STS_ARRAY_DOUBLE setting.
RECERR RSTSAPI	kRecSettingGetIntDefault (HSETTING sett, int *the_default)
	Accessing the default value of an STS_INT or STS_ENUM or STS_BOOL setting.
RECERR RSTSAPI	kRecSettingGetDoubleDefault (HSETTING sett, double *the_default)
	Accessing the default value of a STS_DOUBLE setting.
RECERR RSTSAPI	kRecSettingGetStringDefault (HSETTING sett, const char **the_default)
	Accessing the default value of an STS_STRING setting.
RECERR RSTSAPI	kRecSettingGetUStringDefault (HSETTING sett, const WCHAR **the_default)
	Accessing the default value of an STS_USTRING setting.
RECERR RSTSAPI	kRecSettingGetIntArrayDefault (HSETTING sett, const int **the_default)
	Accessing the default value of an STS_ARRAY_INT or STS_ARRAY_ENUM or STS_ARRAY_BOOL or STS_SET setting.
RECERR RSTSAPI	kRecSettingGetDoubleArrayDefault (HSETTING sett, const double **the_default)
	Accessing the default value of an STS_ARRAY_DOUBLE setting.
RECERR RSTSAPI	kRecSettingGetSymbolic (int sid, HSETTING sett, char the_value, unsigned int buffer_size)
	Getting value in a string format.
RECERR RSTSAPI	kRecSettingGetIntArrayDefaultAt (HSETTING sett, int index, int *the_default)
	Accessing an element of the default value of an STS_ARRAY_INT or STS_ARRAY_ENUM or STS_ARRAY_BOOL or STS_SET setting.
RECERR RSTSAPI	kRecSettingGetDoubleArrayDefaultAt (HSETTING sett, int index, double *the_default)
	Accessing an element of the default value of an STS_ARRAY_DOUBLE setting.
RECERR RSTSAPI	kRecSettingGetNumberOfEnumElements (HSETTING sett, int *num_of_values)
	Getting the number of enum elements.
RECERR RSTSAPI	kRecSettingGetEnumElement (HSETTING sett, int index, const char *str_value, int int_value)
	Getting an enum element.
RECERR RSTSAPI	kRecSettingSetInt (int sid, HSETTING sett, int new_value)
	Setting the value of an STS_INT or STS_ENUM or STS_BOOL setting.
RECERR RSTSAPI	kRecSettingSetDouble (int sid, HSETTING sett, double new_value)
	Setting the value of a STS_DOUBLE setting.
RECERR RSTSAPI	kRecSettingSetString (int sid, HSETTING sett, const char *new_value)
	Setting the value of an STS_STRING or STS_USTRING setting.
RECERR RSTSAPI	kRecSettingSetUString (int sid, HSETTING sett, const WCHAR *new_value)
	Setting the value of a STS_STRING or STS_USTRING setting.
RECERR RSTSAPI	kRecSettingSetIntArray (int sid, HSETTING sett, const int *new_values)
	Setting the value of an STS_ARRAY_INT or STS_ARRAY_ENUM or STS_ARRAY_BOOL or STS_SET setting.
RECERR RSTSAPI	kRecSettingSetDoubleArray (int sid, HSETTING sett, const double *new_values)
	Setting the value of an STS_ARRAY_DOUBLE setting.
RECERR RSTSAPI	kRecSettingSetIntArrayAt (int sid, HSETTING sett, int index, int new_value)
	Setting the value of an element of an STS_ARRAY_INT or STS_ARRAY_ENUM or STS_ARRAY_BOOL or STS_SET setting.
RECERR RSTSAPI	kRecSettingSetDoubleArrayAt (int sid, HSETTING sett, int index, double new_value)
	Setting an element of the value of an STS_ARRAY_DOUBLE setting.
RECERR RSTSAPI	kRecSettingSetToDefault (int sid, HSETTING sett, INTBOOL whole_subtree)
	Setting the value to default.
RECERR RSTSAPI	kRecSettingSetToDefaultPlusC (int sid, HSETTING sett, INTBOOL whole_subtree)
	Setting the value to default (also in cloned settings).
RECERR RSTSAPI	kRecSettingSetArrayToDefaultAt (int sid, HSETTING sett, int index)
	Setting the element of an array to default.
RECERR RSTSAPI	kRecSettingSetArrayToDefaultAtPlusC (int sid, HSETTING sett, int index)
	Setting the element of an array to default (also in cloned settings).
RECERR RSTSAPI	kRecSettingGetSizeOfArray (HSETTING sett, int *the_size)
	Getting the size of an array.
RECERR RSTSAPI	kRecSettingCreateInt (HSETTING created_setting, STSTYPES type, HSETTING root_of_creation, const char symb_name, unsigned int flags, int def_value, const SEnumTypeElement *enum_elements)
	Creating an int setting (STS_INT or STS_ENUM or STS_BOOL).
RECERR RSTSAPI	kRecSettingCreateDouble (HSETTING created_setting, HSETTING root_of_creation, const char symb_name, unsigned int flags, double def_value)
	Creating a double setting (STS_DOUBLE).
RECERR RSTSAPI	kRecSettingCreateString (HSETTING created_setting, HSETTING root_of_creation, const char symb_name, unsigned int flags, const char *def_value)
	Creating a string setting (STS_STRING).
RECERR RSTSAPI	kRecSettingCreateUString (HSETTING created_setting, HSETTING root_of_creation, const char symb_name, unsigned int flags, const WCHAR *def_value)
	Creating a unicode string setting (STS_USTRING).
RECERR RSTSAPI	kRecSettingCreateIntArray (HSETTING created_setting, STSTYPES type, HSETTING root_of_creation, const char symb_name, int size, unsigned int flags, const int def_values, const SEnumTypeElement enum_elements)
	Creating an int array setting (STS_ARRAY_INT or STS_ARRAY_ENUM or STS_ARRAY_BOOL or STS_SET).
RECERR RSTSAPI	kRecSettingCreateDoubleArray (HSETTING created_setting, HSETTING root_of_creation, const char symb_name, int size, unsigned int flags, const double *def_values)
	Creating a double array setting (STS_ARRAY_DOUBLE).
RECERR RSTSAPI	kRecSettingDelete (HSETTING node)
	Deleting a setting.
RECERR RSTSAPI	kRecSettingDeleteSubtree (HSETTING root_of_subtree)
	Deleting a subtree.
RECERR RSTSAPI	kRecSettingClone (HSETTING root_of_cloning, const char *new_symb_name)
	Creating a clone.
RECERR RSTSAPI	kRecSettingLoad (int sid, LPCTSTR filename)
	Loading settings.
RECERR RSTSAPI	kRecSettingSave (int sid, HSETTING root_of_subtree, LPCTSTR filename, INTBOOL save_all, INTBOOL append)
	Saving settings.
RECERR RSTSAPI	kRecSettingCopyValues (HSETTING node, int from_sid, int to_sid, INTBOOL whole_subtree)
	Copying the values between Settings Collections.
Flags of settings

#define	STSFLG_DEFAULT 0x00000000
	The default flag.
#define	STSFLG_HIDDEN 0x00000001
	It does not appear in the enumeration and its succedents also do not.
#define	STSFLG_INFO 0x00000002
	This setting returns some information from a previous process. Its value cannot be changed by the User.
#define	STSFLG_DONTSAVE 0x00000004
	It does not appear in any saved file.
#define	STSFLG_GLOBAL 0x00000008
	Its value is stored in a global place, not in the Settings Collection area, thus it has the same value in all the Settings Collections.
#define	STSFLG_ENCRYPT 0x00000010
	It requires encryption before getting its value symbolically, thus it is saved/loaded in an encrypted form.
#define	STSFLG_USER 0x00000020
	This is a user-defined setting (created through C API calls). This flag is set automatically! Only the user-defined settings can be deleted.
#define	STSFLG_BITFIELD 0x00000040
	This is a bitfield enum setting. It is only an information flag (i.e. bitfield and non-bitfield enums are handled in the same way), but it is unmasked from non-enum settings.
#define	STSFLG_STAYINPENDING 0x00000080
	Internal use only.
#define	STSFLG_CLONEDBIT 0x00000100
	This is a clone of another setting.
#define	STSFLG_DONTSETTODEFAULT 0x00000200
	When kRecSettingSetToDefault sets all the settings of a given subtree of the setting tree to their default values, the settings having this flag are not set.
#define	STSFLG_SLINK 0x00000400
	This is a symbolic link to a subtree of settings. See the description of symbolic links.
#define	STSFLG_CLONED (STSFLG_CLONEDBIT \| STSFLG_USER)
	All the clones have a user-flag for deletable property.
#define	STSFLG_RESERVED (STSFLG_USER\|STSFLG_STAYINPENDING\|STSFLG_CLONEDBIT\|0xFF000000)
	These flags cannot be set by the User, thus they will be unmasked in the API functions creating settings.

Detailed Description

This is the manager of settings at the KernelAPI level.

The settings are organized into a tree. Each node has a name that does not contain a point, which must be unique among the children of its parent node. It is not necessarily unique among all the nodes of the tree. Because of this, each node is identified by its symbolic name, which mirrors the path from the root of the tree to that node, thus it is globally unique. This symbolic name contains the names of the nodes separated by points in the order of their appearance in the path. The name of the root is an empty string. The name of each setting is case-insensitive.

For example on the 1st layer of the tree, there is a node named Kernel. This is the root of the subtree of the kernel settings. One of them is the Timeout, which is a child of the Kernel node, thus its symbolic name is Kernel.Timeout. Of course, the tree can have more than two layers (e.g. Kernel.Img.Deskew.Slope). See also the diagram below.

A setting handle (HSETTING) can be retrieved for each node by referring to its symbolic name. Any other operations can be done with this handle.

There are two types of nodes. One has a setting (e.g. Kernel.Decomp.Method), the other does not (e.g. Kernel.Decomp). The API gives an approach for handling settings, but there are some cases when a simple node can also be passed (e.g. saving a subtree into a file), thus a handle can be retrieved for both types. Of course, there can be more than one node having a setting in the same path.

Different types of settings can be defined: integer (including int, bool and enum), double, integer array (including int, bool, enum and set array), double array, string and Unicode string (see STSTYPES). Their value can be set or got by their types or it can be got symbolically (represented in a string format) for any type.

Every setting has a default value, which cannot be changed during the whole lifetime of that setting. It can be set only at creating. On the other hand, every setting has a current value, which can be different in different Settings Collections. Of course, the current value can be changed anytime in any collection.

For example, here are some paths and nodes relating to image deskewing and despeckling. Double-border boxes denote nodes with a setting; single border boxes denote settingless nodes. Two symbolic (path) names are shown as examples, for nodes with settings. Each setting can take only one value at a time, but different values can be stored in different Settings Collections, as the example shows for the deskew mode.

Every setting has flags for specializing its work, which cannot be changed during the whole lifetime of that setting. They can be set only at creating.

DevKit Users can create their own settings, store them in the same tree and maintain them in the same way. The name of a setting must not contain the following characters:

';' - it denotes comments in setting files,
':' - it is the separator of the origin name in setting files,
'=' - it is the separator of the value in setting files,
'*' - it denotes the root of a clone subtree in setting files.

The creation of an individual setting cannot redefine a previously created setting having the same name. In such a case, the previously defined one remains unchanged and the more recent definition is lost.

Since the definition of each setting is at runtime, there can be some cases when the setting has been created before its real definition (e.g. at loading its value from a file). In this case, a special pending setting is created, which does not have any type. It has only a name (thus it is inserted into the tree) and value-strings (in a symbolic string format) in the proper Settings Collection(s) (where it has been loaded). In this state, the value of such a setting cannot be changed except by loading. On the other hand, its value can be saved from the proper Settings Collection(s). At the real definition of such a setting these symbolic values are parsed into the type of the defined setting.

Any subtree can be cloned, i.e. it can be duplicated. The original subtree and its clone have the same parent node. If a new node is inserted into an original subtree, its clone will be inserted into all clones of the subtree as well.

IMPORTANT NOTE: it is not recommended to create a setting that is wanted to be created by a later cloning step.

Any subtree can be saved into a file, which can contain lines of the following form:

setting.name.with.full.path : origin.name.with.full.path = value_in_string_format

or

setting.name.with.full.path : origin.name.with.full.path *

The former is for a setting, the latter is for a settingless node (which is generally the root of a clone subtree). Of course, the origin name is written only at clone settings. The string format value is the same as the one that can be got symbolically, directly from StsMan (see kRecSettingGetSymbolic). The string format of int and double settings contains only the number, that of the enum and bool settings contain the identifier of the given enum elements (the value may be a combination of some elements, in this case the element ID's are separated by a '|', if the value does not have any ID, it is represented by the number itself). The symbolic value of strings and unicode strings may contain escape sequences and that of the arrays contains the elements of the array in the appropriate form (one of the above), separated with commas.

Of course, the setting files can be loaded. This operation changes only the value of the settings being in the file. Thus if a setting missing from the file was chagned before loading, its value is not affected by the loading operation. See notes of kRecSettingLoad for details. A setting file may be changed manually, but it is not recommended, because mistyping of a setting name or a value may be very complicated to be realized or tracked.

Symbolic links

The symbolic link is a special type of string setting. It points to a subtree of the setting tree by its value (i.e. its value must be the name of the root node of the indicated subtree). Symbolic links can be created by kRecSettingCreateString using the flag STSFLG_SLINK.

The settings of the referenced subtree can be accessed in the same way as if they were the settings of a subtree, whose root is the symbolic link setting. Under the symbolic link node, there are reference nodes for indicating the nodes of the linked subtree.

For example, there may be a symbolic link setting MyOMgr. Let its value be the string "Kernel.OcrMgr", which is an existing node in the tree. In this case, the default filling method can be accessed through the setting Kernel.OcrMgr.DefaultFillingMethod and also through the reference MyOMgr.DefaultFillingMethod.

The creation and working of references are automatic after adjusting the value of the symbolic link, thus settings should not be created under the symbolic link. Of course, the references can be used with their own HSETTING. If the value of a symbolic link is changed, a reference will point to an element of a new referenced subtree, but its HSETTING remains the same.

Note:

The HSETTING identifies a node in the setting tree. In general, it is unchanged from its creation during the further working of the Engine. But in the case of User-defined settings it cannot be guaranteed, because the integrating application can delete these settings at run time. Thus possible parallel storing and deleting of a HSETTING should be avoided.

There are some functions that retrieve a pointer allocated by StsMan and not by the User. Of course, these pointers may lose their validity according to their role. For example, the internal buffer of the current value of a string setting may be reallocated when the value of that string is changed, thus the formerly retrieved pointer of this buffer may become invalid. Therefore the use of some critical section may be a good practise. It is not required to call any releasing function for these retrieved internal pointers and of course freeing functions must not be called for them.

Saving the value of an enum setting writes the name of the enumerator or the pipe-separated names if the value is a combination of enumerators. A setting file can contain both enumerators or numeric values for an enum setting. However, it is recommended to put enumerator names into a manually created setting file (if it is possible), because the numeric value of a particular enumerator may be changed between versions. See the following code fragment, which put the following line into the setting file: MySettings.Enum = VENUM1|VENUM2+1, which means that the value of the setting cannot be combined exclusively with enumerators.

    ...
    typedef enum E_VENUM
    {
        VENUM1 = 2,
        VENUM2 = 4
    } E_VENUM;
    ...
    {
        ...
        HSETTING createds;
        int sid = 0;
        ...
        // Defining the enum type
        SEnumTypeElement enum_elements = new SEnumTypeElement[3];
        enum_elements[0].id = "VENUM1"; enum_elements[0].value = VENUM1;
        enum_elements[1].id = "VENUM2"; enum_elements[1].value = VENUM2;
        enum_elements[2].id = NULL;
        // Creating the setting
        kRecSettingCreateInt(&createds, STS_ENUM, NULL, "MySettings.Enum", STSFLG_DEFAULT, VENUM1, enum_elements);
        delete [] enum_elements;    // It can be deleted right after creation.
        ...
        // Changing the value
        kRecSettingSetInt(sid, createds, 5);
        ...
        // Saving the settings
        kRecSettingSave(sid, createds, "path/mysetting.sts", TRUE, FALSE);
        ...
    }

The function kRecQuit removes all the Settings Collections, pending and user settings, and sets the remaining settings to default, so the setting states are the same after every subsequent kRecQuit - kRecInit pair. In previous versions of CSDK the kRecQuit did not do these steps, thus after a subsequent kRecInit all the settings existed and had the same value as before the previous kRecQuit. This behaviour can be simulated in CSDK v16 or later doing a workaround: Before kRecQuit:

save the required setting values from the required Settings Collections,

After kRecInit:

create all the required user settings,
create the required Settings Collections,
load the proper setting files into the proper Settings Collections.

For C++-fan DevKit Users, we created a wrapper API (with its public sources in KrnStsCppApi.h) on KernelAPI, which is also a good sample for usage of StsMan through KernelApi calls.

See the list of all the RecAPI settings for more information.

The following sample code demonstrates the most important operations of the settings.

    int MySpecialInit ()
    {
        HSETTING hdtxt_outformat, hmy_output_name;
        RECERR err = REC_OK;
        DTXTOUTPUTFORMATS dtxt_outformat = DTXT_TXTS;
        int my_session = kRecCreateSettingsCollection(0);

        //Creating a string setting (the NULL root is equal to the root of the whole
        //tree). This setting will not be saved into a file (DONTSAVE flag).
        err = kRecSettingCreateString(&hmy_output_name, NULL, "MyIni.Output.Name",
            STSFLG_DONTSAVE, "path/out.txt");
        ...
        //Loading a setting file.
        err = kRecSettingLoad(my_session, "last_opt.sts");
        ...
        //Getting the handle of a setting. The passed name must be relative to the
        //root of the query, which is equal to the root of the whole tree here. The INTBOOL parameter
        //has_setting (here NULL) indicates whether the node has a setting or not.
        err = kRecSettingGetHandle(NULL, "Kernel.DTXT.DirectTxtFormat", &hdtxt_outformat, NULL);
        if (err == REC_OK)
            //Getting the value of an enum (int) setting.
            err = kRecSettingGetInt(my_session, hdtxt_outformat, (int *)&dtxt_outformat);
        ...
        //Setting the value of our own string setting created above.
        switch (dtxt_outformat)
        {
        case DTXT_TXTF:
            err = kRecSettingSetString(my_session, hmy_output_name, "path/rtf/out.txt");
            break;
        case DTXT_TXTCSV:
            err = kRecSettingSetString(my_session, hmy_output_name, "path/html/out.csv");
            break;
        case DTXT_PDFIOT:
            err = kRecSettingSetString(my_session, hmy_output_name, "path/pdf/out.pdf");
            break;
        case DTXT_XMLCOORD:
            err = kRecSettingSetString(my_session, hmy_output_name, "path/xml/out.xml");
        break;
        case DTXT_BINARY:
            err = kRecSettingSetString(my_session, hmy_output_name, "path/html/out.bin");
            break;
        default:
            //Setting the value to default. (FALSE is for indicating that only the given
            //setting must be set not the whole subtree, whose root is the given
            //setting.)
            err = kRecSettingSetToDefault(my_session, hmy_output_name, FALSE);
        }
        ...
        //Every initialisation step of this function is done in the session created
        //above. Thus it must be retrieved outside.
        return my_session;
    }

Typedef Documentation

typedef struct RECSTSSTRUCT* HSETTING

Handle of a setting.

This handle can be used for accessing the element of the settings tree. Thus, this handle can be a node with or without a setting. There are some functions that can be used for passing nodes without a setting. These functions generally work on a subtree of the settings tree. The handle of a node can be retrieved using the path of the node (kRecSettingGetHandle). See also notes of StsMan.

Enumeration Type Documentation

enum STSTYPES

Type ID's of settings.

Enumerator:

STS_UNDEFINED	This is a setting in a pending (pre-defined) state.
STS_ENUM	This is an enum setting, which is physically an integer.
STS_INT	This is an integer setting.
STS_DOUBLE	This is a double setting.
STS_BOOL	This is a boolean setting, which is physically an integer.
STS_STRING	This is a string setting.
STS_USTRING	This is a unicode (UTF-16) string setting, in which each character has a length of 2 bytes.
STS_ARRAY_INT	This is an array of integers.
STS_ARRAY_DOUBLE	This is an array of doubles.
STS_ARRAY_ENUM	This is an array of enums, which is physically an array of integers.
STS_ARRAY_BOOL	This is an array of booleans, which is physically an array of integers.
STS_SET	This is a set type, which can be indexed by elements of a given enum. The values of its elements can be boolean indicating whether the given element is in the set or not. It is physically an array of integers. Its size should be equal to the greatest element of the enum type + 1.
STS_REF	Internal used.

Function Documentation

RECERR RSTSAPI kRecSettingClone	(	HSETTING	root_of_cloning,
		const char *	new_symb_name
	)

Creating a clone.

It makes a clone from all the nodes of the specified subtree and puts the clone subtree into the tree as a child of the parent of the original subtree. The name and path of the root is "maybe.point.separated.section"."nonpointseparatedsection" , the names and paths of the nodes of the subtree are "maybe.point.separated.section"."nonpointseparatedsection"."maybe.point.separated.section.i" . The name and path of the clone of the root will be "maybe.point.separated.section".new_symb_name , the names and paths of the clones of the nodes of the subtree will be "maybe.point.separated.section".new_symb_name."maybe.point.separated.section.i" .

Parameters:

[in]	root_of_cloning	This is the handle of the root of the original subtree.
[in]	new_symb_name	This is the last section of the name (and path) of the clone of `root_of_cloning`. Of course, it must not contain any point.

Return values:

STSMN_HANDLE_ERR	`root_of_cloning` is invalid or `NULL`.
STSMN_PARAMETER_ERR	`new_symb_name` contains a '.'.
STSMN_OPNOTALLOWED_ERR	The operation is not allowed, because there already exists a node with the same name as the one specified for the clone node.
REC_OK	Successful.

Note:

The specification of this function in C# is:

 RECERR kRecSettingClone(IntPtr root_of_cloning, string new_symb_name);

RECERR RSTSAPI kRecSettingCopyValues	(	HSETTING	node,
		int	from_sid,
		int	to_sid,
		INTBOOL	whole_subtree
	)

Copying the values between Settings Collections.

It copies the value of setting(s) from a given Settings Collection to another one.

Parameters:

[in]	node	This is the node.
[in]	from_sid	This is the source Settings Collection.
[in]	to_sid	This is the destination Settings Collection.
[in]	whole_subtree	When it is `TRUE` the function copies the values of all the settings in the subtree. Otherwise, it copies only the given setting. In this latter case `node` must be a setting node.

Return values:

STSMN_HANDLE_ERR	`node` is invalid.
STSMN_PARAMETER_ERR	`whole_subtree` is FALSE, but `node` does not have any settings or one (or both) of the given Settings Collections is invalid.
REC_OK	Successful.

Note:

The specification of this function in C# is:

 RECERR kRecSettingCopyValues(IntPtr node, int from_sid, int to_sid, bool whole_subtree);

RECERR RSTSAPI kRecSettingCreateDouble	(	HSETTING *	created_setting,
		HSETTING	root_of_creation,
		const char *	symb_name,
		unsigned int	flags,
		double	def_value
	)

Creating a double setting (STS_DOUBLE).

It creates a double setting and inserts that into the settings tree.

Parameters:

[out]	created_setting	This is the handle of the created setting.
[in]	root_of_creation	See kRecSettingCreateInt.
[in]	symb_name	See kRecSettingCreateInt.
[in]	flags	See kRecSettingCreateInt.
[in]	def_value	See kRecSettingCreateInt.

Return values:

See	kRecSettingCreateInt.

Note:

The specification of this function in C# is:

 RECERR kRecSettingCreateDouble(out IntPtr created_setting, IntPtr root_of_creation, string symb_name, STSFLAGS flags, double def_value);

RECERR RSTSAPI kRecSettingCreateDoubleArray	(	HSETTING *	created_setting,
		HSETTING	root_of_creation,
		const char *	symb_name,
		int	size,
		unsigned int	flags,
		const double *	def_values
	)

Creating a double array setting (STS_ARRAY_DOUBLE).

It creates an array setting of double values and inserts that into the settings tree.

Parameters:

[out]	created_setting	This is the handle of the created setting.
[in]	root_of_creation	See kRecSettingCreateInt.
[in]	symb_name	See kRecSettingCreateInt.
[in]	size	This is the size of the created array.
[in]	flags	See kRecSettingCreateInt.
[in]	def_values	This is the default value of the setting. It cannot be changed in the whole lifetime of the setting. The content of the passed buffer is copied.

Return values:

See	kRecSettingCreateInt.

Note:

The specification of this function in C# is:

 RECERR kRecSettingCreateDoubleArray(out IntPtr created_setting, IntPtr root_of_creation, string symb_name, STSFLAGS flags, double[] def_value);

RECERR RSTSAPI kRecSettingCreateInt	(	HSETTING *	created_setting,
		STSTYPES	type,
		HSETTING	root_of_creation,
		const char *	symb_name,
		unsigned int	flags,
		int	def_value,
		const SEnumTypeElement *	enum_elements
	)

Creating an int setting (STS_INT or STS_ENUM or STS_BOOL).

It creates a physical integer setting of a given type and inserts that into the settings tree.

Parameters:

[out]	created_setting	This is the handle of the created setting.
[in]	type	It determines the type of the created setting. It can be `STS_INT`, `STS_BOOL` and `STS_ENUM`. See STSTYPES for details.
[in]	root_of_creation	This is the root of the subtree, in which the setting will be inserted. The real position of the created setting is determined by this root and the `symb_name` parameter. It can be `NULL`. In this case the root of the insertion is the root of the whole tree.
[in]	symb_name	This is a point-separated symbolic name. The sections separated by the points denote the individual nodes of the path from `root_of_creation` to the created setting; it does not contain the section of this creation root.
[in]	flags	This is a flag or a combination of flags. There are some flags that cannot be set/unset by the User. They are combined in STSFLG_RESERVED, they will be unmasked from `flags`. Of course, STSFLG_BITFIELD can be used but only with enum settings.
[in]	def_value	This is the default value of the setting. It cannot be changed in the whole lifetime of the setting.
[in]	enum_elements	Only at enum settings, it must be passed the elements of the enum type here. The field `id` of the i-th enum element is the enum identifier of the element, the field `value` is the value belonging to this ID (which maybe a member of a real enum type). The end of this list is indicated by a `NULL` `id`. The array and its elements can be deleted right after the function returns.

Return values:

STSMN_HANDLE_ERR	`root_of_creation` is invalid.
STSMN_PARAMETER_ERR	The symbolic name should not contain ','.
REC_OK	Successful.

Note:

The specification of this function in C# is:

    RECERR kRecSettingCreateInt(out IntPtr created_setting, STSTYPES type, IntPtr root_of_creation, string symb_name, STSFLAGS flags, int def_value, SEnumTypeElement[] enum_elements);
    // or when root_of_creation is NULL in C/C++
    RECERR kRecSettingCreateInt(out IntPtr created_setting, STSTYPES type, string symb_name, STSFLAGS flags, int def_value, SEnumTypeElement[] enum_elements);
    // or when enum_elements is NULL in C/C++
    RECERR kRecSettingCreateInt(out IntPtr created_setting, STSTYPES type, IntPtr root_of_creation, string symb_name, STSFLAGS flags, int def_value);
    // or when both are NULL
    RECERR kRecSettingCreateInt(out IntPtr created_setting, STSTYPES type, string symb_name, STSFLAGS flags, int def_value);

RECERR RSTSAPI kRecSettingCreateIntArray	(	HSETTING *	created_setting,
		STSTYPES	type,
		HSETTING	root_of_creation,
		const char *	symb_name,
		int	size,
		unsigned int	flags,
		const int *	def_values,
		const SEnumTypeElement *	enum_elements
	)

Creating an int array setting (STS_ARRAY_INT or STS_ARRAY_ENUM or STS_ARRAY_BOOL or STS_SET).

It creates an array setting of physically integer values and inserts that into the settings tree.

Parameters:

[out]	created_setting	This is the handle of the created setting.
[in]	type	It determines the type of the created setting. It can be `STS_ARRAY_INT`, `STS_ARRAY_BOOL`, `STS_ARRAY_ENUM` and `STS_SET`. See STSTYPES for details.
[in]	root_of_creation	See kRecSettingCreateInt.
[in]	symb_name	See kRecSettingCreateInt.
[in]	size	This is the size of the created array.
[in]	flags	See kRecSettingCreateInt.
[in]	def_values	This is the default value of the setting. It cannot be changed in the whole lifetime of the setting. The content of the passed buffer is copied.
[in]	enum_elements	See kRecSettingCreateInt.

Return values:

See	kRecSettingCreateInt.

Note:

The specification of this function in C# is:

 RECERR kRecSettingCreateIntArray(out IntPtr created_setting, STSTYPES type, IntPtr root_of_creation, string symb_name, STSFLAGS flags, int[] def_values, SEnumTypeElement[] enum_elements)

RECERR RSTSAPI kRecSettingCreateString	(	HSETTING *	created_setting,
		HSETTING	root_of_creation,
		const char *	symb_name,
		unsigned int	flags,
		const char *	def_value
	)

Creating a string setting (STS_STRING).

It creates a string setting and inserts that into the settings tree.

Parameters:

[out]	created_setting	This is the handle of the created setting.
[in]	root_of_creation	See kRecSettingCreateInt.
[in]	symb_name	See kRecSettingCreateInt.
[in]	flags	See kRecSettingCreateInt.
[in]	def_value	This is the default value of the setting. It cannot be changed in the whole lifetime of the setting. The content of the passed buffer is copied.

Return values:

See	kRecSettingCreateInt.

Note:

The specification of this function in C# is:

 RECERR kRecSettingCreateString(out IntPtr created_setting, IntPtr root_of_creation, string symb_name, STSFLAGS flags, string def_value);

RECERR RSTSAPI kRecSettingCreateUString	(	HSETTING *	created_setting,
		HSETTING	root_of_creation,
		const char *	symb_name,
		unsigned int	flags,
		const WCHAR *	def_value
	)

Creating a unicode string setting (STS_USTRING).

It creates a unicode string setting and inserts that into the settings tree. See kRecSettingCreateString.

Note:

The specification of this function in C# is:

 RECERR kRecSettingCreateUString(out IntPtr created_setting, IntPtr root_of_creation, string symb_name, STSFLAGS flags, string def_value);

RECERR RSTSAPI kRecSettingDelete ( HSETTING node )

Deleting a setting.

It deletes the setting of a node, if it is user defined. If the given node is a leaf node it also removes the node from the tree.

Parameters:

[in] node This is the node to be deleted.

Return values:

STSMN_HANDLE_ERR	`node` is invalid or `NULL`.
STSMN_OPNOTALLOWED_ERR	The operation is not allowed, because `node` is the root of the whole tree, or is not a User-defined setting.
REC_OK	Successful.

Note:

The specification of this function in C# is:

 RECERR kRecSettingDelete(IntPtr node);

RECERR RSTSAPI kRecSettingDeleteSubtree ( HSETTING root_of_subtree )

Deleting a subtree.

It deletes all the user-defined settings of the subtree whose root is given. All the nodes of the given subtree that do not have any setting (or it has just been deleted) and any child, are removed recursively.

Parameters:

[in] root_of_subtree This is the root of the subtree to be deleted. The root is also deleted (if this is allowed).

Return values:

STSMN_HANDLE_ERR	`root_of_subtree` is invalid or `NULL`.
STSMN_OPNOTALLOWED_ERR	The operation is not allowed, because `root_of_subtree` is the root of the whole tree.
REC_OK	Successful.

Note:

The specification of this function in C# is:

 RECERR kRecSettingDeleteSubtree(IntPtr root_of_subtree);

RECERR RSTSAPI kRecSettingGetCloneOrigin	(	HSETTING	clone_node,
		HSETTING *	origin_node
	)

Accessing the origin of the clone node.

It retrieves the origin of a clone node or NULL, if it is not a clone.

Parameters:

[in]	clone_node	This is the handle of the clone node.
[out]	origin_node	It gets the handle of the origin node (if any), otherwise it is `NULL`.

Return values:

STSMN_HANDLE_ERR	`prev_node` is invalid or `NULL`.
REC_OK	Successful.

Note:

The specification of this function in C# is:

 RECERR kRecSettingGetCloneOrigin(IntPtr clone_node, out IntPtr origin_node);

.

RECERR RSTSAPI kRecSettingGetDouble	(	int	sid,
		HSETTING	sett,
		double *	the_value
	)

Accessing the current value of an STS_DOUBLE setting.

See kRecSettingGetInt.

Note:

The specification of this function in C# is:

 RECERR kRecSettingGetDouble(int sid, IntPtr sett, out double the_value);

RECERR RSTSAPI kRecSettingGetDoubleArray	(	int	sid,
		HSETTING	sett,
		const double **	the_value
	)

Accessing the current value of a STS_ARRAY_DOUBLE setting.

See kRecSettingGetString.

Note:

The specification of this function in C# is:

 RECERR kRecSettingGetDoubleArray(int sid, IntPtr sett, out double[] the_value);

RECERR RSTSAPI kRecSettingGetDoubleArrayAt	(	int	sid,
		HSETTING	sett,
		int	index,
		double *	the_value
	)

Accessing an element of an STS_ARRAY_DOUBLE setting.

See kRecSettingGetIntArrayAt.

Note:

The specification of this function in C# is:

 RECERR kRecSettingGetDoubleArrayAt(int sid, IntPtr sett, int index, out double the_value);

RECERR RSTSAPI kRecSettingGetDoubleArrayDefault	(	HSETTING	sett,
		const double **	the_default
	)

Accessing the default value of an STS_ARRAY_DOUBLE setting.

See kRecSettingGetStringDefault.

Note:

The specification of this function in C# is:

 RECERR kRecSettingGetDoubleArrayDefault(IntPtr sett, out double[] the_value);

RECERR RSTSAPI kRecSettingGetDoubleArrayDefaultAt	(	HSETTING	sett,
		int	index,
		double *	the_default
	)

Accessing an element of the default value of an STS_ARRAY_DOUBLE setting.

See kRecSettingGetIntArrayDefaultAt.

Note:

The specification of this function in C# is:

 RECERR kRecSettingGetDoubleArrayDefaultAt(IntPtr sett, int index, out double the_default);

RECERR RSTSAPI kRecSettingGetDoubleDefault	(	HSETTING	sett,
		double *	the_default
	)

Accessing the default value of a STS_DOUBLE setting.

See kRecSettingGetIntDefault.

Note:

The specification of this function in C# is:

 RECERR kRecSettingGetDoubleDefault(IntPtr sett, out double the_default);

RECERR RSTSAPI kRecSettingGetEnumElement	(	HSETTING	sett,
		int	index,
		const char **	str_value,
		int *	int_value
	)

Getting an enum element.

It gets the given enum element of the type of the given setting.

Parameters:

[in]	sett	This is the handle of the setting.
[in]	index	This is the index of the required enum element. The number of enum elements can be retrieved by kRecSettingGetNumberOfEnumElements.
[out]	str_value	This is the name (identifier) of the given enum element. It can be `NULL` if the name of the element is not required. It points to an internal buffer of StsMan (see the notes of StsMan).
[out]	int_value	This is the value of the given enum element. It can be `NULL`, if the value of the element is not required.

Return values:

STSMN_HANDLE_ERR	`sett` is invalid or `NULL`.
STSMN_NOSETTING_ERR	The node does not have any setting.
STSMN_BADTYPE_ERR	The setting is not an enum type setting.
STSMN_PARAMETER_ERR	`index` is out of range.
REC_OK	Successful.

Note:

The specification of this function in C# is:

    RECERR kRecSettingGetEnumElement(IntPtr sett, int index, out string str_value, out int int_value);
    // or when str_value is NULL in C/C++
    RECERR kRecSettingGetEnumElement(IntPtr sett, int index, out int int_value);
    // or when int_value is NULL in C/C++
    RECERR kRecSettingGetEnumElement(IntPtr sett, int index, out string str_value);

RECERR RSTSAPI kRecSettingGetHandle	(	HSETTING	root_of_query,
		const char *	symb_name,
		HSETTING *	ret_handle,
		INTBOOL *	has_setting
	)

Getting the handle of a node.

This is how to get the handle of a node by its name.

Parameters:

[in]	root_of_query	This is the starting node of the searching. It can be `NULL`, which means the root of the whole tree.
[in]	symb_name	The symbolic name of the node. It must be relative to `root_of_query`.
[out]	ret_handle	This is the retrieved handle.
[out]	has_setting	If it is not `NULL` it retrieves whether the node given by the name has a setting or not.

Return values:

STSMN_HANDLE_ERR	`root_of_query` is invalid.
STSMN_NOTFOUND_ERR	The required node does not exist.
REC_OK	Successful.

Note:

The specification of this function in C# is:

    RECERR kRecSettingGetHandle(IntPtr root_of_query, string symb_name, out IntPtr ret_handle, out bool has_setting);
    // or when has_setting is NULL in C/C++
    RECERR kRecSettingGetHandle(IntPtr root_of_query, string symb_name, out IntPtr ret_handle);
    // or when root_of_query is NULL in C/C++
    RECERR kRecSettingGetHandle(string symb_name, out IntPtr ret_handle, out bool has_setting);
    // or when both are NULL
    RECERR kRecSettingGetHandle(string symb_name, out IntPtr ret_handle);

.

RECERR RSTSAPI kRecSettingGetInt	(	int	sid,
		HSETTING	sett,
		int *	the_value
	)

Accessing the current value of an STS_INT or STS_ENUM or STS_BOOL setting.

It gets the value of the given setting in the given Settings Collection.

Parameters:

[in]	sid	This is the Settings Collection ID.
[in]	sett	This is the handle of the setting.
[out]	the_value	It gets the value of the setting.

Return values:

STSMN_HANDLE_ERR	`sett` is invalid or `NULL`.
STSMN_NOSETTING_ERR	The node does not have any settings.
STSMN_BADTYPE_ERR	The setting type is not valid.
REC_OK	Successful.

Note:

The specification of this function in C# is:

 RECERR kRecSettingGetInt(int sid, IntPtr sett, out int the_value);

RECERR RSTSAPI kRecSettingGetIntArray	(	int	sid,
		HSETTING	sett,
		const int **	the_value
	)

Accessing the current value of an STS_ARRAY_INT or STS_ARRAY_ENUM or STS_ARRAY_BOOL or STS_SET setting.

See kRecSettingGetString.

Note:

The specification of this function in C# is:

 RECERR kRecSettingGetIntArray(int sid, IntPtr sett, out int[] the_value);

RECERR RSTSAPI kRecSettingGetIntArrayAt	(	int	sid,
		HSETTING	sett,
		int	index,
		int *	the_value
	)

Accessing an element of an STS_ARRAY_INT or STS_ARRAY_ENUM or STS_ARRAY_BOOL or STS_SET setting.

It gets the value of the given element of the array setting in the given Settings Collection.

Parameters:

[in]	sid	This is the ID of the Settings Collection.
[in]	sett	This is the handle of the setting.
[in]	index	This is the index of the required element.
[out]	the_value	It gets the retrieved value.

Return values:

STSMN_HANDLE_ERR	`sett` is invalid or `NULL`.
STSMN_NOSETTING_ERR	The node does not have any setting.
STSMN_BADTYPE_ERR	The setting type is not valid.
STSMN_PARAMETER_ERR	`index` is invalid.
REC_OK	Successful.

Note:

The specification of this function in C# is:

 RECERR kRecSettingGetIntArrayAt(int sid, IntPtr sett, int index, out int the_value);

.

RECERR RSTSAPI kRecSettingGetIntArrayDefault	(	HSETTING	sett,
		const int **	the_default
	)

Accessing the default value of an STS_ARRAY_INT or STS_ARRAY_ENUM or STS_ARRAY_BOOL or STS_SET setting.

See kRecSettingGetStringDefault.

Note:

The specification of this function in C# is:

 RECERR kRecSettingGetIntArrayDefault(IntPtr sett, out int[] the_value);

RECERR RSTSAPI kRecSettingGetIntArrayDefaultAt	(	HSETTING	sett,
		int	index,
		int *	the_default
	)

Accessing an element of the default value of an STS_ARRAY_INT or STS_ARRAY_ENUM or STS_ARRAY_BOOL or STS_SET setting.

It gets the given element of the default value of the array setting.

Parameters:

[in]	sett	This is the handle of the given array setting.
[in]	index	This is the index of the required element.
[out]	the_default	It gets the retrieved value.

Return values:

STSMN_HANDLE_ERR	`sett` is invalid or `NULL`.
STSMN_NOSETTING_ERR	The node does not have any setting.
STSMN_BADTYPE_ERR	The setting type is not valid.
STSMN_PARAMETER_ERR	`index` is invalid.
REC_OK	Successful.

Note:

The specification of this function in C# is:

 RECERR kRecSettingGetIntArrayDefaultAt(IntPtr sett, int index, out int the_default);

RECERR RSTSAPI kRecSettingGetIntDefault	(	HSETTING	sett,
		int *	the_default
	)

Accessing the default value of an STS_INT or STS_ENUM or STS_BOOL setting.

It gets the default value of the given setting.

Parameters:

[in]	sett	This is the handle of the setting.
[out]	the_default	It gets the default value.

Return values:

STSMN_HANDLE_ERR	`sett` is invalid or `NULL`.
STSMN_NOSETTING_ERR	The node does not have any setting.
STSMN_BADTYPE_ERR	The setting type is not valid.
REC_OK	Successful.

Note:

The specification of this function in C# is:

 RECERR kRecSettingGetIntDefault(IntPtr sett, out int the_default);

.

RECERR RSTSAPI kRecSettingGetName	(	HSETTING	node,
		const char **	the_name
	)

Querying the name.

It retrieves the symbolic name of the given node.

Parameters:

[in]	node	This is the handle of the node.
[out]	the_name	It gets a pointer of an internal buffer of StsMan (see the notes of StsMan), which contains the given symbolic name.

Return values:

STSMN_HANDLE_ERR	`node` is invalid or `NULL`.
REC_OK	Successful.

Note:

The specification of this function in C# is:

 RECERR kRecSettingGetName(IntPtr node, out string the_name);

.

RECERR RSTSAPI kRecSettingGetNextChild	(	HSETTING	the_parent,
		HSETTING	prev_child,
		HSETTING *	the_child
	)

Enumerating children.

It retrieves the next child of the given parent node.

Parameters:

[in]	the_parent	This is the handle of the parent node.
[in]	prev_child	This is the previous child in the enumeration. If it is `NULL` the function gives the first child.
[out]	the_child	It gets the handle of the next child (if any), otherwise it is `NULL`.

Return values:

STSMN_HANDLE_ERR	`the_parent` is invalid or `NULL`, or `prev_child` is invalid.
REC_OK	Successful.

Note:

The specification of this function in C# is:

    RECERR kRecSettingGetNextChild(IntPtr the_parent, IntPtr prev_child, out IntPtr the_child);
    // and only in C# CSDK has a function for getting the first child
    // this is completely equivalent to the calling of
    // kRecSettingGetNextChild(the_parent, 0, out the_child);
    RECERR kRecSettingGetFirstChild(IntPtr the_parent, out IntPtr the_child);

.

RECERR RSTSAPI kRecSettingGetNumberOfEnumElements	(	HSETTING	sett,
		int *	num_of_values
	)

Getting the number of enum elements.

It gets the number of enum elements of the type of the setting. The function kRecSettingGetEnumElement can be used for enumerating the elements.

Parameters:

[in]	sett	This is the handle of the setting.
[out]	num_of_values	It gets the number of the enum elements.

Return values:

STSMN_HANDLE_ERR	`sett` is invalid or `NULL`.
STSMN_NOSETTING_ERR	The node does not have any setting.
STSMN_BADTYPE_ERR	The setting is not an enum type setting.
REC_OK	Successful.

Note:

The specification of this function in C# is:

 RECERR kRecSettingGetNumberOfEnumElements(IntPtr sett, out int num_of_values);

RECERR RSTSAPI kRecSettingGetSizeOfArray	(	HSETTING	sett,
		int *	the_size
	)

Getting the size of an array.

It gets the size of the given array setting.

Parameters:

[in]	sett	This is the handle of the setting.
[out]	the_size	It gets the size of the array.

Return values:

STSMN_HANDLE_ERR	`sett` is invalid or `NULL`.
STSMN_NOSETTING_ERR	The node does not have any setting.
STSMN_BADTYPE_ERR	The given setting is not an array.
REC_OK	Successful.

Note:

The specification of this function in C# is:

 RECERR kRecSettingGetSizeOfArray(IntPtr sett, out int the_size);

RECERR RSTSAPI kRecSettingGetString	(	int	sid,
		HSETTING	sett,
		const char **	the_value
	)

Accessing the current value of an STS_STRING setting.

It gets the value of the given setting in the given Settings Collection.

Parameters:

[in]	sid	This is the Settings Collection ID.
[in]	sett	This is the handle of the setting.
[out]	the_value	It gets the value of the setting. It points to an internal buffer of StsMan (see the notes of StsMan), thus another thread running in parallel can modify its content or invalidate it. So for long-time usage it may be good practice to copy the string.

Return values:

See	kRecSettingGetInt.

Note:

This function accepts only STS_STRING settings (i.e. even STS_USTRING is not usable).

The specification of this function in C# is:

 RECERR kRecSettingGetString(int sid, IntPtr sett, out string the_value);

.

RECERR RSTSAPI kRecSettingGetStringDefault	(	HSETTING	sett,
		const char **	the_default
	)

Accessing the default value of an STS_STRING setting.

It gets the default value of the given setting.

Parameters:

[in]	sett	This is the handle of the setting.
[out]	the_default	It gets the default value. It points to an internal buffer of StsMan (see the notes of StsMan), thus another thread running in parallel can modify its content or invalidate it. (e.g. by deleting this setting). So for long-time usage it may be good practice to copy the string.

Return values:

See	kRecSettingGetIntDefault.

Note:

This function accepts only STS_STRING settings (i.e. even STS_USTRING is not usable).

The specification of this function in C# is:

 RECERR kRecSettingGetStringDefault(IntPtr sett, out string the_default);

RECERR RSTSAPI kRecSettingGetSymbolic	(	int	sid,
		HSETTING	sett,
		char *	the_value,
		unsigned int *	buffer_size
	)

Getting value in a string format.

It gets the value of the given setting in the given Settings Collection symbolically. The retrieved string contains the converted value of the setting. With enum types it gets the name of the element of the enum type, which represents the value (or it can be a combination of them as well). With arrays it gets a list of its successive elements separated with commas. With strings it gets a parsed string with C-like escape sequences. For settings with the flag STSFLG_ENCRYPTNEEDED it encrypts the string before return.

Parameters:

[in]	sid	This is the ID of the Settings Collection.
[in]	sett	This is the handle of the setting.
[out]	the_value	It gets the value. This is allocated by the User.
[in,out]	buffer_size	It must contain the size of the buffer. If this size is not enough, the function retrieves the required size in this parameter and returns with `STSMN_PARAMETER_ERR`. Otherwise, the value of this parameter is not changed.

Return values:

STSMN_HANDLE_ERR	`sett` is invalid or `NULL`.
STSMN_NOSETTING_ERR	The node does not have any setting.
STSMN_PARAMETER_ERR	The buffersize is not enough. The required size is in `buffer_size`.
STSMN_EMPTYPENDVAL_WARN	This is a pending setting with empty pending value. I.e. if it would not be pending, it would have its default value in this settings collection.
REC_OK	Successful.

Note:

The setting files contains the values of the settings in such string format.

The specification of this function in C# is:

 RECERR kRecSettingGetSymbolic(int sid, IntPtr sett, out string the_value);

RECERR RSTSAPI kRecSettingGetType	(	HSETTING	sett,
		STSTYPES *	type
	)

Querying the type.

It retrieves the type of the setting.

Parameters:

[in]	sett	This is the handle of the node.
[out]	type	It gets the retrieved type.

Return values:

STSMN_HANDLE_ERR	`sett` is invalid or `NULL`.
STSMN_NOSETTING_ERR	The node does not have any setting.
REC_OK	Successful.

Note:

The specification of this function in C# is:

 RECERR kRecSettingGetType(IntPtr sett, out STSTYPES type);

.

RECERR RSTSAPI kRecSettingGetUString	(	int	sid,
		HSETTING	sett,
		const WCHAR **	the_value
	)

Accessing the current value of an STS_USTRING setting.

See kRecSettingGetString.

Note:

This function accepts only STS_USTRING settings (i.e. even STS_STRING is not usable).

The specification of this function in C# is:

 RECERR kRecSettingGetUString(int sid, IntPtr sett, out string the_value);

RECERR RSTSAPI kRecSettingGetUStringDefault	(	HSETTING	sett,
		const WCHAR **	the_default
	)

Accessing the default value of an STS_USTRING setting.

See kRecSettingGetStringDefault.

Note:

This function accepts only STS_USTRING settings (i.e. even STS_STRING is not usable).

The specification of this function in C# is:

 RECERR kRecSettingGetUStringDefault(IntPtr sett, out string the_default);

RECERR RSTSAPI kRecSettingHasSetting	(	HSETTING	node,
		INTBOOL *	has_setting
	)

Querying whether it is a setting.

It retrieves whether the given handle is also a setting or only a node.

Parameters:

[in]	node	This is the handle of the node.
[out]	has_setting	It is TRUE when it is also a setting.

Return values:

STSMN_HANDLE_ERR	`node` is invalid or `NULL`.
REC_OK	Successful.

Note:

The specification of this function in C# is:

 RECERR kRecSettingHasSetting(IntPtr node, out bool has_setting);

.

RECERR RSTSAPI kRecSettingIsDefault	(	int	sid,
		HSETTING	node,
		INTBOOL *	is_default
	)

Checking whether the setting is default or not.

This function gives TRUE when the given node is a setting and it has its default value in the given Settings Collection.

Parameters:

[in]	sid	This is the Settings Collection ID.
[in]	node	This is the handle of the node.
[out]	is_default	It is `TRUE` when the given node is a setting and it has its default value.

Return values:

STSMN_HANDLE_ERR	`node` is invalid or `NULL`.
STSMN_NOSETTING_ERR	The node does not have any setting.
REC_OK	Successful.

Note:

The specification of this function in C# is:

 RECERR kRecSettingIsDefault(int sid, IntPtr node, out bool is_default);

.

RECERR RSTSAPI kRecSettingIsFlagSet	(	HSETTING	sett,
		unsigned int	flgs,
		INTBOOL *	is_set
	)

Querying flags.

It retrieves whether the given flag or flag combination is set or not in the given setting.

Parameters:

[in]	sett	This is the handle of the node.
[in]	flgs	This is the given flag or flag combination.
[out]	is_set	It is `TRUE` when the given flag (or combination) is set.

Return values:

STSMN_HANDLE_ERR	`sett` is invalid or `NULL`.
STSMN_NOSETTING_ERR	The node does not have any setting.
REC_OK	Successful.

Note:

The specification of this function in C# is:

 RECERR kRecSettingIsFlagSet(IntPtr sett, STSFLAGS flgs, out bool is_set);

.

RECERR RSTSAPI kRecSettingLoad	(	int	sid,
		LPCTSTR	filename
	)

Loading settings.

It loads the value of the settings from the given file into the given Settings Collection.

Parameters:

[in]	sid	This is the ID of the Settings Collection.
[in]	filename	This is the name of the file, from which the function loads the settings.

Return values:

STSMN_INVALIDFILE_ERR	The given file has invalid lines.
STSMN_FULLSAVEDTREE_WARN	It is only a warning. The loaded file comes from a saving where the parameter `save_all` was `TRUE`. See the note below.
REC_OK	Successful.
...	Error codes of the filehandling subsystem.

Note:

An STSMN_FULLSAVEDTREE_WARN situation may be unsafe at developing time. For example, if the default value of a setting is changed between two builds and its value should not be changed at runtime (e.g. an internal setting of the integrated application), but there is an automatic loading step for handling the user settings of the integrating application. In the previous build, it did not cause an error, because the file contains the previous default value of the given setting. But in the present build, the setting gets this previous default value; this is erroneous behavior, since the setting should not be changed, as we mentioned. Thus it is suggested to save only settings with non-default values.

A setting file loading changes only the value of the settings being in the file. Thus if a setting missing from the file was chagned before loading, its value is not affected by the loading operation. If the setting file was saved with a FALSE value in parameter save_all of kRecSettingSave, the setting status was being at saving can be fully reproduced by calling kRecSettingSetToDefault before kRecSettingLoad.

RECERR RSTSAPI kRecSettingSave	(	int	sid,
		HSETTING	root_of_subtree,
		LPCTSTR	filename,
		INTBOOL	save_all,
		INTBOOL	append
	)

STSMN_HANDLE_ERR	`root_of_subtree` is invalid.
REC_OK	Successful.
...	Error codes of the filehandling subsystem.

RECERR RSTSAPI kRecSettingSetArrayToDefaultAt	(	int	sid,
		HSETTING	sett,
		int	index
	)

RECERR RSTSAPI kRecSettingSetDouble	(	int	sid,
		HSETTING	sett,
		double	new_value
	)

RECERR RSTSAPI kRecSettingSetDoubleArray	(	int	sid,
		HSETTING	sett,
		const double *	new_values
	)

RECERR RSTSAPI kRecSettingSetInt	(	int	sid,
		HSETTING	sett,
		int	new_value
	)

RECERR RSTSAPI kRecSettingSetIntArray	(	int	sid,
		HSETTING	sett,
		const int *	new_values
	)

RECERR RSTSAPI kRecSettingSetIntArrayAt	(	int	sid,
		HSETTING	sett,
		int	index,
		int	new_value
	)

RECERR RSTSAPI kRecSettingSetString	(	int	sid,
		HSETTING	sett,
		const char *	new_value
	)

RECERR RSTSAPI kRecSettingSetToDefault	(	int	sid,
		HSETTING	sett,
		INTBOOL	whole_subtree
	)

STSMN_HANDLE_ERR	`sett` is invalid.
STSMN_NOSETTING_ERR	The node does not have any setting (when `whole_subtree` is `FALSE`).
REC_OK	Successful.

RECERR RSTSAPI kRecSettingSetToDefaultPlusC	(	int	sid,
		HSETTING	sett,
		INTBOOL	whole_subtree
	)

RECERR RSTSAPI kRecSettingSetUString	(	int	sid,
		HSETTING	sett,
		const WCHAR *	new_value
	)

Classes

Typedefs

Enumerations

Functions

Flags of settings

Detailed Description

Typedef Documentation

Enumeration Type Documentation

Function Documentation