AlexaClientSDK  3.0.0
A cross-platform, modular SDK for interacting with the Alexa Voice Service
Public Member Functions | Static Public Member Functions | List of all members
alexaClientSDK::avsCommon::utils::configuration::ConfigurationNode Class Reference

#include <ConfigurationNode.h>

Public Member Functions

 ConfigurationNode ()
 
bool getBool (const std::string &key, bool *out=nullptr, bool defaultValue=false) const
 
bool getInt (const std::string &key, int *out=nullptr, int defaultValue=0) const
 
bool getUint32 (const std::string &key, uint32_t *out=nullptr, uint32_t defaultValue=0) const
 
bool getString (const std::string &key, std::string *out=nullptr, std::string defaultValue="") const
 
bool getStringValues (const std::string &key, std::set< std::string > *out=nullptr) const
 
template<typename InputType , typename OutputType , typename DefaultType >
bool getDuration (const std::string &key, OutputType *out=static_cast< std::chrono::seconds >(0), DefaultType defaultValue=std::chrono::seconds(0)) const
 
ConfigurationNode operator[] (const std::string &key) const
 
ConfigurationNode getChildNode (const char *key) const
 
 operator bool () const
 
template<typename Type >
bool getValue (const std::string &key, Type *out, Type defaultValue, bool(rapidjson::Value::*isType)() const, Type(rapidjson::Value::*getType)() const) const
 
std::string serialize () const
 
ConfigurationNode getArray (const std::string &key) const
 
std::size_t getArraySize () const
 
ConfigurationNode operator[] (const std::size_t index) const
 

Static Public Member Functions

static bool initialize (const std::vector< std::shared_ptr< std::istream >> &jsonStreams)
 
static void uninitialize ()
 
static std::shared_ptr< ConfigurationNodecreateRoot ()
 
static ConfigurationNode getRoot ()
 

Detailed Description

Class providing access to a global read-only configuration object. This object is a tree structure comprised of ConfigurationNode instances that contain key-value pairs (including ConfigurationNode values).

Methods to fetch a named value from a ConfigurationNode are of the form:

bool get<Type>(const char* key, <Type>* out = nullptr, <Type> defaultValue = simpleDefault)

This signature allows for fetching a value without the risk of an assertion or exception if the value is not present. It also allows for checking if a key is present, or combining the check and fetch operations in a single call.

Sub ConfigurationNodes are accessed via operator[], where the index is the name of the sub ConfigurationNode. If a key for a ConfigurationNode does not exist an empty ConfigurationNode is returned instead. This allows for simple and safe traversal of the configuration hierarchy. For example:

std::string tempString;
ConfigurationNode::getRoot()["someComponent"]["someSubComponent"].getString("someKey", &tempString);

The configuration is specified via JSON documents with a root object that corresponds to the root ConfigurationNode value returned by ConfigurationNode::getRoot(). ConfiguriatonNode Sub-nodes accessed by operator[<key>] correspond to JSON objects values with the of the name <key>. So, the code example above would return "someStringValue" if the configuration was initialized with the following JSON document:

{
"someComponent" : {
"someSubComponent" : {
"someKey" : "someStringValue",
"keyToSomeBooleanValue" : true,
"keyToSomeIntegerValue" : 123
}
}
}

Constructor & Destructor Documentation

◆ ConfigurationNode()

alexaClientSDK::avsCommon::utils::configuration::ConfigurationNode::ConfigurationNode ( )

Constructor.

Member Function Documentation

◆ createRoot()

static std::shared_ptr<ConfigurationNode> alexaClientSDK::avsCommon::utils::configuration::ConfigurationNode::createRoot ( )
static

Create a shared_ptr to the root configuration node.

Returns
A shared_ptr to the root configuration node.

◆ getArray()

ConfigurationNode alexaClientSDK::avsCommon::utils::configuration::ConfigurationNode::getArray ( const std::string &  key) const

Get the ConfigurationNode value that contains an array with key from this ConfigurationNode.

Parameters
keyThe key of the ConfigurationNode value to get.
Returns
The ConfigurationNode value, or an empty node if this ConfigurationNode does not have a ConfigurationNode value for key that contains an array.

◆ getArraySize()

std::size_t alexaClientSDK::avsCommon::utils::configuration::ConfigurationNode::getArraySize ( ) const

Get the size of the array from this ConfigurationNode.

Returns
0 if this ConfigurationNode is not an array. Else return the size of the array.

◆ getBool()

bool alexaClientSDK::avsCommon::utils::configuration::ConfigurationNode::getBool ( const std::string &  key,
bool *  out = nullptr,
bool  defaultValue = false 
) const

Get bool value for key from this ConfigurationNode.

Parameters
keyThe key of the bool value to get.
[out]outPointer to receive the returned value.
defaultValueDefault value to use if this ConfigurationNode does not have a bool value for key. false if not specified.
Returns
Whether this ConfigurationNode has a bool value for key.

◆ getChildNode()

ConfigurationNode alexaClientSDK::avsCommon::utils::configuration::ConfigurationNode::getChildNode ( const char *  key) const

Get ConfigurationNode value for key from this ConfigurationNode.

Parameters
keyThe key of the ConfigurationNode value to get.
Returns
The ConfigurationNode value, or an empty node if this ConfigurationNode does not have a ConfigurationNode value for key.

◆ getDuration()

template<typename InputType , typename OutputType , typename DefaultType >
bool alexaClientSDK::avsCommon::utils::configuration::ConfigurationNode::getDuration ( const std::string &  key,
OutputType *  out = static_cast<std::chrono::seconds>(0),
DefaultType  defaultValue = std::chrono::seconds(0) 
) const

Get a duration value derived from an integer value for key from this ConfigurationNode.

Template Parameters
InputTypestd::chrono::duration type whose unit specifies how the integer value in the JSON input stream is to be interpreted.
OutputTypestd::chrono::duration type specifying the type of the out parameter to this method.
DefaultTypestd::chrono::duration type specifying the type of the defaultValue to this method.
Parameters
keyThe key of of the integer value to fetch and convert to OutputType.
outPointer to receive the returned value.
defaultValueDefault value to use if this ConfigurationNode does not have an integer value value for key. Zero if not specified.
Returns
Whether this ConfigurationNode has an integer value for key.

◆ getInt()

bool alexaClientSDK::avsCommon::utils::configuration::ConfigurationNode::getInt ( const std::string &  key,
int *  out = nullptr,
int  defaultValue = 0 
) const

Get int value for key from this ConfigurationNode.

Parameters
keyThe key of the int value to get.
[out]outPointer to receive the returned value.
defaultValueDefault value to use if this ConfigurationNode does not have an int value for key. Zero if not specified.
Returns
Whether this ConfigurationNode has an int value for key.

◆ getRoot()

static ConfigurationNode alexaClientSDK::avsCommon::utils::configuration::ConfigurationNode::getRoot ( )
static

Get the root ConfigurationNode of the global configuration.

Returns
The root ConfigurationNode of the global configuration.

◆ getString()

bool alexaClientSDK::avsCommon::utils::configuration::ConfigurationNode::getString ( const std::string &  key,
std::string *  out = nullptr,
std::string  defaultValue = "" 
) const

Get the string value for key from this ConfigurationNode.

Parameters
keyThe key of the string value to get.
[out]outPointer to receive the returned value.
defaultValueDefault value to use if this ConfigurationNode does not have a string value for key. The empty string if not specified.
Returns
Whether this ConfigurationNode has a string value for key.

◆ getStringValues()

bool alexaClientSDK::avsCommon::utils::configuration::ConfigurationNode::getStringValues ( const std::string &  key,
std::set< std::string > *  out = nullptr 
) const

Get the string value for key from this ConfigurationNode.

Parameters
keyThe key of the string value to get.
[out]outPointer to receive the returned value.
Returns
Whether this ConfigurationNode has a string array value for key.

◆ getUint32()

bool alexaClientSDK::avsCommon::utils::configuration::ConfigurationNode::getUint32 ( const std::string &  key,
uint32_t *  out = nullptr,
uint32_t  defaultValue = 0 
) const

Get uint32_t value for key from this ConfigurationNode.

Parameters
keyThe key of the uint32_t value to get.
[out]outPointer to receive the returned value.
defaultValueDefault value to use if this ConfigurationNode does not have an uint32_t value for key. Zero if not specified.
Returns
Whether this ConfigurationNode has an uint32_t value for key.

◆ getValue()

template<typename Type >
bool alexaClientSDK::avsCommon::utils::configuration::ConfigurationNode::getValue ( const std::string &  key,
Type *  out,
Type  defaultValue,
bool(rapidjson::Value::*)() const  isType,
Type(rapidjson::Value::*)() const  getType 
) const

Common logic for getting a value of a specific type.

Template Parameters
TypeThe type to be gotten.
Parameters
keyThe key of the value to get.
outPointer to receive the value. May be nullptr to just test for the presence of the value.
defaultValueA default output value if no value of the desired type for key is present.
isTyperapidjson::Value member function to test for the desired type.
getTyperapidjson::Value member function to get the desired type.
Returns
Whether a value of the specified Type is present for key.

◆ initialize()

static bool alexaClientSDK::avsCommon::utils::configuration::ConfigurationNode::initialize ( const std::vector< std::shared_ptr< std::istream >> &  jsonStreams)
static

Initialize the global configuration.

Note
If initialize() has already been called since startup or the latest call to uninitialize(), this function will reject the request and return false.
Parameters
jsonStreamsVector of istreams containing JSON documents from which to parse configuration parameters. Streams are processed in the order they appear in the vector. When a value appears in more than one JSON stream the last processed stream's value overwrites the previous value (and a debug log entry will be created). This allows for specifying default settings (by providing them first) and specifying the configuration from multiple sources (e.g. a separate stream for each component). The resulting global configuration may be accessed from getRoot().
Returns
Whether the initialization was successful.

◆ operator bool()

alexaClientSDK::avsCommon::utils::configuration::ConfigurationNode::operator bool ( ) const

operator bool(). Indicates of the ConfigurationNode references a valid object.

Returns
Whether the ConfigurationNode references a valid object.

◆ operator[]() [1/2]

ConfigurationNode alexaClientSDK::avsCommon::utils::configuration::ConfigurationNode::operator[] ( const std::string &  key) const

operator[] to get ConfigurationNode value for key from this ConfigurationNode.

Parameters
keyThe key of the ConfigurationNode value to get.
Returns
The ConfigurationNode value, or an empty node if this ConfigurationNode does not have a ConfigurationNode value for key.

◆ operator[]() [2/2]

ConfigurationNode alexaClientSDK::avsCommon::utils::configuration::ConfigurationNode::operator[] ( const std::size_t  index) const

operator[] to get ConfigurationNode value from an array from index of this ConfigurationNode.

Parameters
indexThe index of the array of the ConfigurationNode to get.
Returns
The ConfigurationNode value, or an empty node if this ConfigurationNode is not an array or the the index is out of range.

◆ serialize()

std::string alexaClientSDK::avsCommon::utils::configuration::ConfigurationNode::serialize ( ) const

Serialize the object into a string

Returns
The serialized object.

◆ uninitialize()

static void alexaClientSDK::avsCommon::utils::configuration::ConfigurationNode::uninitialize ( )
static

Uninitialize the global configuration.

Note
Once this method has been called, all existing ConfigurationNode instances will become invalid.

The documentation for this class was generated from the following file:

AlexaClientSDK 3.0.0 - Copyright 2016-2022 Amazon.com, Inc. or its affiliates. All Rights Reserved. Licensed under the Apache License, Version 2.0