Config

The config library supports Apps to store configuration options in a config database table. To access the config options from within a JavaScript App, the C++ config library communicates with the JavaScript config library using JSON messages. See the JS config library documentation for more informations.

The usage of the config library is straight forward and only needs a couple of steps:

• Create instance of ConfigContext.
• Register the config library to the JSON API framework by passing the created instance to RegisterJsonApi(configContextInstance).
• Create the database table used by the config lib by calling CreateInitTask(databaseObject) and exetuting the returned task (don't forget to free it, after the task is finished).
• Add ConfigItem members to your class and initialize them passing the ConfigContext instance (see the description of the ConfigItems classes below).

Now the appliction service and the JavaScript app only need to access the items or changed and save them (especially from the JavaScript side). ConfigContext and the JavaScript config library are handling all of the communication, so there is no need for an app to worry about that.

File information

Classes

class ConfigContext : public UTask, public UJsonApiContext, public UConfigContextApi {
protected:
    virtual void ConfigChanged() {}
    virtual void ConfigChangedUnmanaged() {}
    virtual bool CanReadConfig(IJsonApiConnection * const connection) { return true; }
    virtual bool CanWriteConfig(IJsonApiConnection * const connection) { return true; }
    class ITask * UpdateUnmanagedItems();
    class ITask * UpdateManagedItems();

public:
    ConfigContext(class IDatabase * database, class IInstanceLog * log);
    virtual ~ConfigContext();

    bool SwitchToFileMode(class IIoMux * iomux, const char * absoluteFileName, bool initFromDatabase = false);
    void SwitchToDatabaseMode();

    class ITask * CreateInitTask(class IDatabase * database = nullptr, bool readOnly = false);
    void ResetChangedFlag();
    class ITask * WriteItemValue(ConfigItem * item, const char * value, bool notify);
};

Overview

• name The name of the config item with a maximum length of 255 chars.
• value The vlaue of the config item. Each item is stored as string with an (in theory) unlimited length. But be aware that each item will stay resident in RAM, so take care to not hold values to big.
• unmanaged A boolean value to describe if the item is unmanaged or not.

Protected functions

Public functions

class ConfigItem : public istd::listElement {
private:
    char * name;

protected:
    friend class TaskWriteConfig;
    friend class TaskWriteConfigUnmanaged;
    friend class TaskInitConfig;
    friend class ConfigContext;

    class IInstanceLog * const log;
    bool changed;
    bool unmanaged;

    virtual void ReadValueFromDataset(class IDataSet * dataset) = 0;
    virtual void ReadValueFromJSON(class json_io * json, dword base, class IJsonApiConnection * connection) = 0;
    virtual void WriteValueToJSON(class json_io * json, dword base, char * & convBuf, class IJsonApiConnection * connection) = 0;
    virtual int WriteValueToString(char * dest) = 0;
    virtual void SetWriteValue(const char * value) = 0;
    virtual void WriteItemTypeToJSON(class json_io * json, dword base, char * & convBuf) = 0;

public:
    ConfigItem(ConfigContext * context, const char * name, bool unmanaged);
    virtual ~ConfigItem();

    const char * GetName() const { return this->name; }
    bool Changed() const { return this->changed; }
    virtual bool HasDefaultValue() = 0;
    virtual void Reset() = 0;
};

Overview

• 32bit integers (singed and unsigned)
• 64bit integers (singed and unsigned - but take care with 64bit integers because of the not-that-good support of them on JavaScript).
• bool.
• string (with unlimited length).
• password (which is a string with a flag given on initialization to define it as password. Passwords can only be received from the JSON API and only in an encrypted way. ConfigContext will not send passwords. Instead an empty string for that items will be send).
• choice (which is a combination of an integer as index and a array with available choices).

Remarks

Protected variables

Protected functions

Public functions

class ConfigChoice : public ConfigItem {
public:
    ConfigChoice(ConfigContext * context, const char * name, size_t defVal, const char ** options, bool unmanaged = false);
    virtual ~ConfigChoice();

    int ValueIdx() const { return this->valueIdx; }
    const char * Value() const { return (this->valueIdx < this->optionsCount ? this->choiceValues[this->valueIdx] : nullptr); }
    void SetValue(const char * option);
    void SetValueIdx(size_t valudIdx);
    bool HasDefaultValue() override;
    void Reset() override;
};

Overview

Public functions

class ConfigBool : public ConfigItem {
public:
    ConfigBool(ConfigContext * context, const char * name, bool defVal, bool unmanaged = false);
    virtual ~ConfigBool();

    bool Value() const { return this->value; }
    void SetValue(bool value);
    bool HasDefaultValue() override;
    void Reset() override;
};

Overview

Public functions

class ConfigInt: public ConfigItem {
public:
    ConfigInt(ConfigContext * context, const char * name, int defVal, bool unmanaged = false, int minVal = INT32_MIN, int maxVal = INT32_MAX);
    virtual ~ConfigInt();

    int Value() const { return this->value; }
    void SetValue(int value);
    bool HasDefaultValue() override;
    void Reset() override;
};

Overview

Public functions

class ConfigDword : public ConfigItem {
public:
    ConfigDword(ConfigContext * context, const char * name, dword defVal, bool unmanaged = false, dword minVal = 0, dword maxVal = UINT32_MAX);
    virtual ~ConfigDword();

    dword Value() const { return this->value; }
    void SetValue(dword value);
    bool HasDefaultValue() override;
    void Reset() override;
};

Overview

Public functions

class ConfigLong64 : public ConfigItem {
public:
    ConfigLong64(ConfigContext * context, const char * name, long64 defVal, bool unmanaged = false, long64 minVal = INT64_MIN, long64 maxVal = INT64_MAX);
    virtual ~ConfigLong64();

    long64 Value() const { return this->value; }
    void SetValue(long64 value);
    bool HasDefaultValue() override;
    void Reset() override;
};

Overview

Public functions

class ConfigUlong64 : public ConfigItem {
public:
    ConfigUlong64(ConfigContext * context, const char * name, ulong64 defVal, bool unmanaged = false, ulong64 minVal = 0, ulong64 maxVal = UINT64_MAX);
    virtual ~ConfigUlong64();

    ulong64 Value() const { return this->value; }
    void SetValue(ulong64 value);
    bool HasDefaultValue() override;
    void Reset() override;
};

Overview

Public functions

class ConfigString : public ConfigItem {
public:
    ConfigString(ConfigContext * context, const char * name, const char * defVal, bool unmanaged = false, bool isPassword = false);
    virtual ~ConfigString();

    const char * Value() const { return this->value; }
    void SetValue(const char * value);
    bool HasDefaultValue() override;
    void Reset() override;
    static void Encrypt(const char * seed, const char * password, char * out, size_t len);
    static void Decrypt(const char * seed, const char * password, char * out, size_t len);
};

Overview

Remarks

Public functions

JSON Messages

Overview

The Config protocol supports the AppWebsocket "src" mechanism.

{
    "api": "Config",
    "src": string,
    "mt": "ConfigMessage"
}

Send to ConfigContext

• GetConfigItems
• ReadConfig
• WriteConfig

Send from ConfigContext

• GetConfigItemsResult
• ReadConfigResult
• WriteConfigResult
• ConfigUpdate

{
    "api": "Config",
    "mt": "GetConfigItems"
}

Overview

{
    "api": "Config",
    "mt": "GetConfigItems",
    "result": "AccessDenied",
    "ConfigItems": [ConfigItemObject]
}

Overview

Fields

ConfigItemObject

{
    "name": "ConfigItemName",
    "type": "TypeOfItem",
    "minVal" : Number,
    "maxVal" : Number,
    "password" : true,
    "choices" : [ListOfChoices]
}

Example message

{
    "api": "Config",
    "mt": "GetConfigItemsResult",
    "ConfigItems": [{
        "name" : "maxPlayers",
        "type" : "DWORD",
        "minVal" : 1,
        "maxVal" : 10
    },
    {
        "name" : "teams",
        "type" : "CHOICE",
        "choices" : ["RedTeam", "BlueTeam", "InnoTeam"]
    },
    {
        "name" : "playerName",
        "type" : "STRING"
    }]
}

{
    "api": "Config",
    "mt": "ReadConfig"
}

Overview

{
    "api": "Config",
    "mt": "ReadConfigResult" / "ConfigUpdate"
    "ConfigItems" : {
        "ItemName" : number,
        "ItemName" : true / false,
        "ItemName" : "stringValue"
    }
}

Overview

Example message

{
    "api": "Config",
    "mt": "ReadConfigResult",
    "ConfigItems": {
        "maxPlayers" : 5,
        "teams" : 2,
        "playerName" : "Goldfish"
    }
}

{
    "api": "Config",
    "mt": "WriteConfig",
    "ConfigItems": {
        "ItemName": number,
        "ItemName": true / false,
        "ItemName": "StringValue",
        "ItemNamePassword": {
            "value": "EncodedValue",
            "key": "KeyToDecode"
        }
    }
}

Overview

{
    "api":"Config",
    "mt":"WriteConfigResult",
    "result":"ok"
}

Overview

Code examples

// A simple class derived from ConfigContext

static const char * team_names[] = { "ReadTeam", "BlueTeam", "InnoTeam", nullptr };

class MyConfig : public ConfigContext() {
private:
    class MyApp * myApp;
    ConfigInt maxPlayers;
    ConfigString playerName;
    ConfigChoice teams;

protected:
    virtual void ConfigChanged()
    {
        this->myApp->OnConfigChanged();
    }

public:
    // Let's assume, that MyApp is derived from JsonApiContext.
    MyConfig(class MyApp * userApp, class IDatabase * database, class IInstanceLog * log)
        : ConfigContext(database, log),
          maxPlayers(this, "maxPlayers", 5, false, 1, 10),
          playerName(this, "playerName", "Goldfish"),
          teams(this, "teams", 2, team_names)
    {
        this->myApp = userApp;
        this->myApp->RegisterJsonApi(this);
    }

    ConfigInt & MaxPlayers() { return this->maxPlayers; }
    ConfigString & PlayerName() { return this->playerName; }
    ConfigChoice & Teams() { return this->teams; }
};

// Let's assume, that MyApp is derived from JsonApiContext and UTask, already
// created and also has pointers to an already created and initialized IDatabase
// instance as well as valid IInstanceLog instance.

void MyApp::Init()
{
    this->config = new MyConfig(this, this->database, this->log);
    ITask * initConfigTask = this->config->CreateInitTask();
    initConfigTask->Start(this);
}

void MyApp::TaskComplete(ITask * task)
{
    delete task;
    debug->printf("Config database initialized");
}

void MyApp::OnConfigChanged()
{
    debug->printf("Config changed - new values:");
    debug->printf("    Max-Players   : %u", this->config->MaxPlayers().Value());
    debug->printf("    Player-Name   : %s", this->config->PlayerName().Value());
    debug->printf("    Selected Team : %s", this->config->Teams().Value());
}

To use config some preparations in your code needs to be done. The following steps appply when you use ConfigContext as base class to your instance class and do not use a separate class for the config. This is a good option in most cases.

Includes

Use config.h as include

#include "common/lib/config.h"

Definitions in the instance class

Use JsonApiContext and ConfigContext as base class

..., public JsonApiContext, public ConfigContext

Define a private function, as initialization complete handler

void ConfigInitComplete(class ITask * task);

Define a UTaskTemplate class so that this handler will be called

class UTaskTemplate<YourApp, class ITask> taskConfigInit;

Define public members for the config parameters, e.g

class ConfigString configParameter;

Instance Code

Initializations in the constructor of the instance class

ConfigContext(0, this),
taskConfigInit(this, &yourApp::ConfigInitComplete),
configParameter(this, "parameter", "")

Call RegisterJsonApi in the instance constructor, so that the Config lib is known as Api provider

RegisterJsonApi(this);

Start config initialization after database is connected. E.g. in the DatabaseConnectComplete function

    class ITask * task = CreateInitTask(database);
    task->Start(&taskConfigInit);

Continue initialization when config init is complete

void YourApp::ConfigInitComplete(class ITask * task)
{
    ... more init ...
}

Make sure the you instance class is passed as jsonApiContext in the AppWebsocket constructor

AppWebsocket(webserverPlugin, yourApp, yourApp)