fwInstallation  8.4.1
Functions | Variables
fwInstallationProjParam.ctl File Reference

Functions

private string fwInstallationProjParam_getParamName (string key, string namespace=FW_INSTALLATION_PROJ_PARAM_DEFAULT_NAMESPACE)
 
private string fwInstallationProjParam_extractKeyFromParamName (string paramName)
 
int fwInstallationProjParam_keyExists (string key, bool &exists, string namespace=FW_INSTALLATION_PROJ_PARAM_DEFAULT_NAMESPACE)
 
int fwInstallationProjParam_registerKey (string key, string namespace=FW_INSTALLATION_PROJ_PARAM_DEFAULT_NAMESPACE, string dataType=FW_INSTALLATION_PROJ_PARAM_DEFAULT_KEY_TYPE, string description="", string family="")
 
int fwInstallationProjParam_removeKey (string key, string namespace=FW_INSTALLATION_PROJ_PARAM_DEFAULT_NAMESPACE)
 
int fwInstallationProjParam_valueExists (string key, bool &exists, string namespace=FW_INSTALLATION_PROJ_PARAM_DEFAULT_NAMESPACE, string project="", string host="")
 
int fwInstallationProjParam_registerKeyValue (string key, string value, string namespace=FW_INSTALLATION_PROJ_PARAM_DEFAULT_NAMESPACE, string dataType=FW_INSTALLATION_PROJ_PARAM_DEFAULT_KEY_TYPE, string description="", string family="", string project="", string host="")
 
int fwInstallationProjParam_setValue (string key, string value, string namespace=FW_INSTALLATION_PROJ_PARAM_DEFAULT_NAMESPACE, string project="", string host="")
 
int fwInstallationProjParam_getValue (string key, string &value, string namespace=FW_INSTALLATION_PROJ_PARAM_DEFAULT_NAMESPACE, string project="", string host="")
 
int fwInstallationProjParam_removeValue (string key, string namespace=FW_INSTALLATION_PROJ_PARAM_DEFAULT_NAMESPACE, string project="", string host="")
 
int fwInstallationProjParam_getKeyValueMapping (mapping &keyValMapping, string namespace=FW_INSTALLATION_PROJ_PARAM_DEFAULT_NAMESPACE, string project="", string host="")
 

Variables

const string csFwInstallationProjParamLibVersion = "8.4.1"
 
const string FW_INSTALLATION_PROJ_PARAM_DEFAULT_KEY_TYPE = "text/plain"
 type/storage-type, other examples: test/encrypted, password/encrypted, etc.
 

Detailed Description

This library contains functions to store and read project-specific parameters from DB (ConfigurationDBSystemInformation). Project parameter's value is stored under the specified namespace and key. Internally, inside the DB, "parameter name" is used which combines key and namespace into one identifier. Existence of namespaces is to allow same keynames to exists. For each project and parameter name (namespace-key pair) one project parameter value can exists.

User can register its own keys and namespaces. The key can be freely named although it is not recommended to use special characters (underscore and dash are allowed). The default namespace exists however it is advised to use the unique name to avoid repetitions of parameter name. It is suggested to use, as the namespace, the name of the component that uses this library to store its parameters. This guarantees the unique namespaces for each component and makes the the developer of the component responsible for keeping the unique key names only. For namespace name it is forbidden to use slash '/' as it is used as namespace-key separator. For other characters the same restrictions as for key name are applied.

Usage: Before first usage of the key it has to be registered. There are 2 functions that allow it: fwInstallationProjParam_registerKey() and fwInstallationProjParam_registerKeyValue(). The first one only registers the key with given properties in provided namespace with no value assigned. The second one allows also to register a value for specified project in one go. Both functions returns success if key is already registered (they do not change key's properties), so there is no need to check before if key is already registered.

int retVal = fwInstallationProjParam_registerKey("myKey", "fwInstallation", FW_INSTALLATION_PROJ_PARAM_DEFAULT_KEY_TYPE, "This is my dummy key"); or int retVal = fwInstallationProjParam_registerKeyValue("myKey", "myValue", "fwInstallation", FW_INSTALLATION_PROJ_PARAM_DEFAULT_KEY_TYPE, "This is my dummy key");

To register a value or to change already set value for a given key, namespace and project, a fwInstallationProjParam_setValue() function can be used.

// Assuming at this moment that key is already registered so it is not neccessary to check it, if this assumption // is wrong then error code is assigned to retVal int retVal = fwInstallationProjParam_setValue("myKey", "myValue", "fwInstallation");

To get value for a given key, namespace and project use fwInstallationProjParam_getValue(). In case a requested key doesn't exists - function will return an error (there's a function to check existence of a key).

bool exists = false; string value; int retVal1 = fwInstallationProjParam_valueExists("myKey", exists, "fwInstallation"); if(exists && !retVal1) int retVal2 = fwInstallationProjParam_getValue("myKey", value, "fwInstallation");

To get all registered key - value pairs for given namespace and project one can use fwInstallationProjParam_getKeyValueMapping() function. Registered key - value pairs are returned as a mapping.

mapping keyValMapping; int retVal = fwInstallationProjParam_getKeyValueMapping(keyValMapping, "fwInstallation");

Note: "fwInstallation" in examples above should be replaced by the name of component that uses these functions.

Function Documentation

private string fwInstallationProjParam_getParamName ( string  key,
string  namespace = FW_INSTALLATION_PROJ_PARAM_DEFAULT_NAMESPACE 
)

Returns the parameter name from provided key and namespace

Parameters
key(in) Name of the key
namespace(in) Name of the namespace
Returns
parameter name: "namespace/key"
private string fwInstallationProjParam_extractKeyFromParamName ( string  paramName)

Returns key extracted from parameter name

Parameters
paramName(in) Parameter name
Returns
Key name or empty string in case the paramName has wrong pattern
int fwInstallationProjParam_keyExists ( string  key,
bool &  exists,
string  namespace = FW_INSTALLATION_PROJ_PARAM_DEFAULT_NAMESPACE 
)

Checks if given parameter name (key - namespace pair) is already registered in DB.

Parameters
key(in) Key name
exists(out) Flag that indicates if a parameter exists in DB, note: this flag is changed only when success code is returned
namespace(in) Namespace, default value: '_default'
Returns
0 when checking was peformed succesfully, -1 if an error occured (failed to check if parameter is registered)
int fwInstallationProjParam_registerKey ( string  key,
string  namespace = FW_INSTALLATION_PROJ_PARAM_DEFAULT_NAMESPACE,
string  dataType = FW_INSTALLATION_PROJ_PARAM_DEFAULT_KEY_TYPE,
string  description = "",
string  family = "" 
)

This function allows to register new key for storing projects' parameter in DB. Note: This function must be called before first usage of the key. Note2: If key is already registered for given namespace then function does nothing and returns success code, thus it is possible to call this function multiple times, on different projects with the same result (success) so then user script can proceed without any errors.

Parameters
key(in) Key name
namespace(in) Namespace, default value: '_default' (user should define own namespace, it is recommended to use component name as the namespace, using default namespace causes risk of key name clash)
dataType(in) Type (description) of data stored under given key, default value: 'text/plain'. Note: It is not the data type in the sense of ctrl variable type (int, string, etc.) - in this sense stored data is always of type 'string'
description(in) Key description, optional, default value is empty
family(in) Family of key, optional, default value is empty
Returns
0 when key was registered succesfully or given key already exists in DB, -1 if errors occured (unable to register or verify if key is registered already)
int fwInstallationProjParam_removeKey ( string  key,
string  namespace = FW_INSTALLATION_PROJ_PARAM_DEFAULT_NAMESPACE 
)

: NOT IMPLEMENTED YET, DO NOT USE THIS FUNCTION Removes given parameter (key - namespace pair) from DB.

Note
Parameter removal affects all projects that store values under specified key and namespace. After removal all values stored under this parameter by different projects are no longer accessible.
Parameters
key(in) Key name
namespace(in) Namespace, default value: '_default'
Returns
0 when parameter was removed successfully, -1 if an error occured ()
int fwInstallationProjParam_valueExists ( string  key,
bool &  exists,
string  namespace = FW_INSTALLATION_PROJ_PARAM_DEFAULT_NAMESPACE,
string  project = "",
string  host = "" 
)

This function checks if for given key, namespace, project and host a value exists. Note: function will return error if a key doesn't exist (is not registered).

Parameters
key(in) Key name
exists(out) Flag that indicates if a value exists in DB for given key, namespace and project, Note: it is changed only when function returns success code
namespace(in) Namespace, default value: '_default'
project(in) Project name, default value is empty (current project)
host(in) Hostname, default value is empty (current host)
Returns
0 when checking was peformed succesfully, -1 if an error occured (failed to check if key in given namespace is registered or failed to check if value is registered)
int fwInstallationProjParam_registerKeyValue ( string  key,
string  value,
string  namespace = FW_INSTALLATION_PROJ_PARAM_DEFAULT_NAMESPACE,
string  dataType = FW_INSTALLATION_PROJ_PARAM_DEFAULT_KEY_TYPE,
string  description = "",
string  family = "",
string  project = "",
string  host = "" 
)

This function registers new key and assigns a value. Note: Either this function or fwInstallationProjParam_registerKey must be called before first usage of the key. Note2: If key already exists, for given namespace, registration is skipped and only value is set.

Parameters
key(in) Key name
namespace(in) Namespace, default value: '_default' (user should define own namespace, it is recommended to use component name as the namespace, using default namespace causes risk of key name clash)
dataType(in) Type (description) of data stored under given key, default value: 'text/plain'. Note: It is not the data type in the sense of ctrl variable type (int, string, etc.) - in this sense stored data is always of type 'string'
description(in) Key description, optional, default value is empty
family(in) Family of key, optional, default value is empty
project(in) Project name, default value is empty (current project)
host(in) Hostname, default value is empty (current host)
Returns
0 when key was registered succesfully or given key already exists in DB, -1 if errors occured (unable to register or verify if key is registered already)
int fwInstallationProjParam_setValue ( string  key,
string  value,
string  namespace = FW_INSTALLATION_PROJ_PARAM_DEFAULT_NAMESPACE,
string  project = "",
string  host = "" 
)

Sets the specified value under given key and namespace, for given project, by default the current one. Note: If value did not exist before in DB for specified key, the function registers it under given key and namespace and given project.

Parameters
key(in) Key name
value(in) Value to be set under given key and namespace, for given project
namespace(in) Namespace, default value: '_default' (user should define own namespace, it is recommended to use component name as the namespace, using default namespace causes risk of key name clash)
project(in) Project name, default value is empty (current project)
host(in) Hostname, default value is empty (current host)
Returns
0 when value was set successfully, -1 if an error occured (failed to set value or register it if it did not exist before)
int fwInstallationProjParam_getValue ( string  key,
string &  value,
string  namespace = FW_INSTALLATION_PROJ_PARAM_DEFAULT_NAMESPACE,
string  project = "",
string  host = "" 
)

This function gets the value of project parameter for given namespace, key and project (by default the current one)

Parameters
key(in) Key name
value(in) Value of project parameter
namespace(in) Namespace, default value: '_default'
project(in) Project name, default value is empty (current project)
host(in) Hostname, default value is empty (current host)
Returns
0 when value was got successfully, -1 if an error occured (failed to get project parameter as for example the value for given key, namespace and project is not registered in DB or given key is not registered)
int fwInstallationProjParam_removeValue ( string  key,
string  namespace = FW_INSTALLATION_PROJ_PARAM_DEFAULT_NAMESPACE,
string  project = "",
string  host = "" 
)

Removes from DB the value of project parameter for given namespace, key and project (by default the current one)

Parameters
key(in) Key name
namespace(in) Namespace, default value: '_default'
project(in) Project name, default value is empty (current project)
host(in) Hostname, default value is empty (current host)
Returns
0 when value was removed successfully, -1 if an error occured (given project parameter does not exist in DB, failed to remove project parameter)
int fwInstallationProjParam_getKeyValueMapping ( mapping &  keyValMapping,
string  namespace = FW_INSTALLATION_PROJ_PARAM_DEFAULT_NAMESPACE,
string  project = "",
string  host = "" 
)

Returns all available keys along with their values for given namespace and given project (by default the current one)

Parameters
keyValMapping(out) Mapping with project parameters (keys and their values) that exist in DB for given namespace and project
namespace(in) Namespace, default value: '_default'
project(in) Project name, default value is empty (current project)
host(in) Hostname, default value is empty (current host)
Returns
0 when value was got successfully, -1 if an error occured

Variable Documentation

const string csFwInstallationProjParamLibVersion = "8.4.1"

Version of this library. Used to determine the coherency of all libraries of the installation tool Please do not edit it manually