typedef shared_ptr<AsyncTask<TClass, TResult> > Ptr;
typedef weak_ptr<AsyncTask<TClass, TResult> > WeakPtr;
+ /**
+ * A completion callback for an AsyncTask.
+ */
typedef function<void (const shared_ptr<TClass>&)> CompletionCallback;
/**
DynamicObject::Ptr GetConfig(void) const;
private:
- DynamicObject *m_Config;
+ DynamicObject *m_Config; /**< The configuration object for this
+ component. */
friend class Component;
};
static void AddSearchDir(const String& componentDirectory);
private:
- IComponent::Ptr m_Impl;
+ IComponent::Ptr m_Impl; /**< The implementation object for this
+ component. */
};
typedef IComponent *(*CreateComponentFunction)(void);
using namespace icinga;
/**
- * Compares the keys of dictionary keys using the less operator.
+ * Compares dictionary keys using the less operator.
*/
struct DictionaryKeyLessComparer
{
+ /**
+ * Compares two keys.
+ *
+ * @param a The first key.
+ * @param b The second key.
+ * @returns true if the first key is less than the second key, false
+ * otherwise
+ */
bool operator()(const pair<String, Value>& a, const char *b)
{
return a.first < b;
}
+ /**
+ * Compares two keys.
+ *
+ * @param a The first key.
+ * @param b The second key.
+ * @returns true if the first key is less than the second key, false
+ * otherwise
+ */
bool operator()(const char *a, const pair<String, Value>& b)
{
return a < b.first;
typedef shared_ptr<Dictionary> Ptr;
typedef weak_ptr<Dictionary> WeakPtr;
+ /**
+ * An iterator that can be used to iterate over dictionary elements.
+ */
typedef map<String, Value>::iterator Iterator;
Value Get(const char *key) const;
cJSON *ToJson(void) const;
private:
- map<String, Value> m_Data;
+ map<String, Value> m_Data; /**< The data for the dictionary. */
};
inline Dictionary::Iterator range_begin(Dictionary::Ptr x)
/**
* The type of an attribute for a DynamicObject.
+ *
+ * @ingroup base
*/
enum DynamicAttributeType
{
/**
* An attribute for a DynamicObject.
+ *
+ * @ingroup base
*/
struct DynamicAttribute
{
}
};
+/**
+ * Factory function for DynamicObject-based classes.
+ *
+ * @ingroup base
+ */
template<typename T>
shared_ptr<T> DynamicObjectFactory(const Dictionary::Ptr& serializedUpdate)
{
#ifdef _WIN32
/**
* A Win32 error encapsulated in an exception.
+ *
+ * @ingroup base
*/
class Win32Exception : public Exception
{
/**
* A Posix error encapsulated in an exception.
+ *
+ * @ingroup base
*/
class PosixException : public Exception
{
/**
* An OpenSSL error encapsulated in an exception.
+ *
+ * @ingroup base
*/
class OpenSSLException : public Exception
{
{
/**
- * Helper functions for reading/writing messages in the netString format.
+ * Helper functions for reading/writing messages in the netstring format.
*
- * @see http://cr.yp.to/proto/netStrings.txt
+ * @see http://cr.yp.to/proto/netstrings.txt
*
* @ingroup base
*/
/**
* Holds a shared pointer and provides support for implicit upcasts.
+ *
+ * @ingroup base
*/
class SharedPtrHolder
{
public:
+ /**
+ * Constructor for the SharedPtrHolder class.
+ *
+ * @param object The shared pointer that should be used to
+ * construct this shared pointer holder.
+ */
explicit SharedPtrHolder(const Object::Ptr& object)
: m_Object(object)
{ }
+ /**
+ * Retrieves a shared pointer for the object that is associated
+ * this holder instance.
+ *
+ * @returns A shared pointer.
+ */
template<typename T>
operator shared_ptr<T>(void) const
{
return other;
}
+ /**
+ * Retrieves a weak pointer for the object that is associated
+ * with this holder instance.
+ *
+ * @returns A weak pointer.
+ */
template<typename T>
operator weak_ptr<T>(void) const
{
}
private:
- Object::Ptr m_Object;
+ Object::Ptr m_Object; /**< The object that belongs to this
+ holder instance */
};
SharedPtrHolder GetSelf(void);
Object(const Object& other);
Object& operator=(const Object& rhs);
- static boost::mutex m_Mutex;
- static vector<Object::Ptr> m_HeldObjects;
+ static boost::mutex m_Mutex; /**< Mutex which protects static members
+ of the Object class. */
+ static vector<Object::Ptr> m_HeldObjects; /**< Currently held
+ objects. */
#ifdef _DEBUG
- static set<Object *> m_AliveObjects;
+ static set<Object *> m_AliveObjects; /**< Currently alive objects -
+ for debugging purposes. */
#endif /* _DEBUG */
};
/**
* Compares a weak pointer with a raw pointer.
+ *
+ * @ingroup base
*/
template<class T>
struct WeakPtrEqual
{
private:
- const void *m_Ref;
+ const void *m_Ref; /**< The object. */
public:
+ /**
+ * Constructor for the WeakPtrEqual class.
+ *
+ * @param ref The object that should be compared with the weak pointer.
+ */
WeakPtrEqual(const void *ref) : m_Ref(ref) { }
/**
using namespace icinga;
-ConfigCompiler::ConfigCompiler(const String& path, istream *input, HandleIncludeFunc includeHandler)
+/**
+ * Constructor for the ConfigCompiler class.
+ *
+ * @param path The path of the configuration file (or another name that
+ * identifies the source of the configuration text).
+ * @param input Input stream for the configuration file.
+ * @param includeHandler Handler function for #include directives.
+ */
+ConfigCompiler::ConfigCompiler(const String& path, istream *input,
+ HandleIncludeFunc includeHandler)
: m_Path(path), m_Input(input), m_HandleInclude(includeHandler)
{
InitializeScanner();
}
+/**
+ * Destructor for the ConfigCompiler class.
+ */
ConfigCompiler::~ConfigCompiler(void)
{
DestroyScanner();
}
+/**
+ * Reads data from the input stream. Used internally by the lexer.
+ *
+ * @param buffer Where to store data.
+ * @param max_size The maximum number of bytes to read from the stream.
+ * @returns The actual number of bytes read.
+ */
size_t ConfigCompiler::ReadInput(char *buffer, size_t max_size)
{
m_Input->read(buffer, max_size);
return static_cast<size_t>(m_Input->gcount());
}
+/**
+ * Retrieves the scanner object.
+ *
+ * @returns The scanner object.
+ */
void *ConfigCompiler::GetScanner(void) const
{
return m_Scanner;
}
+/**
+ * Retrieves the result from the compiler.
+ *
+ * @returns A list of configuration items.
+ */
vector<ConfigItem::Ptr> ConfigCompiler::GetResult(void) const
{
return m_Result;
}
+/**
+ * Retrieves the path for the input file.
+ *
+ * @returns The path.
+ */
String ConfigCompiler::GetPath(void) const
{
return m_Path;
}
+/**
+ * Handles an include directive by calling the include handler callback
+ * function.
+ *
+ * @param include The path from the include directive.
+ */
void ConfigCompiler::HandleInclude(const String& include)
{
String path = Utility::DirName(GetPath()) + "/" + include;
std::copy(items.begin(), items.end(), back_inserter(m_Result));
}
-vector<ConfigItem::Ptr> ConfigCompiler::CompileStream(const String& path, istream *stream)
+/**
+ * Compiles a stream.
+ *
+ * @param path A name identifying the stream.
+ * @param stream The input stream.
+ * @returns Configuration items.
+ */
+vector<ConfigItem::Ptr> ConfigCompiler::CompileStream(const String& path,
+ istream *stream)
{
ConfigCompiler ctx(path, stream);
ctx.Compile();
return ctx.GetResult();
}
+/**
+ * Compiles a file.
+ *
+ * @param path The path.
+ * @returns Configuration items.
+ */
vector<ConfigItem::Ptr> ConfigCompiler::CompileFile(const String& path)
{
ifstream stream;
return CompileStream(path, &stream);
}
-vector<ConfigItem::Ptr> ConfigCompiler::CompileText(const String& path, const String& text)
+/**
+ * Compiles a snippet of text.
+ *
+ * @param path A name identifying the text.
+ * @param text The text.
+ * @returns Configuration items.
+ */
+vector<ConfigItem::Ptr> ConfigCompiler::CompileText(const String& path,
+ const String& text)
{
stringstream stream(text);
return CompileStream(path, &stream);
}
+/**
+ * Default include handler. Includes the file and returns a list of
+ * configuration items.
+ *
+ * @param include The path from the include directive.
+ * @returns A list of configuration objects.
+ */
vector<ConfigItem::Ptr> ConfigCompiler::HandleFileInclude(const String& include)
{
/* TODO: implement wildcard includes */
return CompileFile(include);
}
+/**
+ * Adds an object to the result.
+ *
+ * @param object The configuration item.
+ */
+ *
void ConfigCompiler::AddObject(const ConfigItem::Ptr& object)
{
m_Result.push_back(object);
/**
* The configuration compiler can be used to compile a configuration file
- * into a number of configuration objects.
+ * into a number of configuration items.
*
* @ingroup config
*/
void Compile(void);
- static vector<ConfigItem::Ptr> CompileStream(const String& path, istream *stream);
+ static vector<ConfigItem::Ptr> CompileStream(const String& path,
+ istream *stream);
static vector<ConfigItem::Ptr> CompileFile(const String& path);
- static vector<ConfigItem::Ptr> CompileText(const String& path, const String& text);
+ static vector<ConfigItem::Ptr> CompileText(const String& path,
+ const String& text);
static vector<ConfigItem::Ptr> HandleFileInclude(const String& include);
boost::signal<void (const ConfigItem::Ptr&)> ConfigItem::OnCommitted;
boost::signal<void (const ConfigItem::Ptr&)> ConfigItem::OnRemoved;
+/**
+ * Constructor for the ConfigItem class.
+ *
+ * @param type The object type.
+ * @param name The name of the item.
+ * @param exprl Expression list for the item.
+ * @param parents Parent objects for the item.
+ * @param debuginfo Debug information.
+ */
ConfigItem::ConfigItem(const String& type, const String& name,
const ExpressionList::Ptr& exprl, const vector<String>& parents,
const DebugInfo& debuginfo)
{
}
+/**
+ * Retrieves the type of the configuration item.
+ *
+ * @returns The type.
+ */
String ConfigItem::GetType(void) const
{
return m_Type;
}
+/**
+ * Retrieves the name of the configuration item.
+ *
+ * @returns The name.
+ */
String ConfigItem::GetName(void) const
{
return m_Name;
}
+/**
+ * Retrieves the debug information for the configuration item.
+ *
+ * @returns The debug information.
+ */
DebugInfo ConfigItem::GetDebugInfo(void) const
{
return m_DebugInfo;
}
+/**
+ * Retrieves the expression list for the configuration item.
+ *
+ * @returns The expression list.
+ */
ExpressionList::Ptr ConfigItem::GetExpressionList(void) const
{
return m_ExpressionList;
}
+/**
+ * Retrieves the list of parents for the configuration item.
+ *
+ * @returns The list of parents.
+ */
vector<String> ConfigItem::GetParents(void) const
{
return m_Parents;
}
+/**
+ * Calculates the object's properties based on parent objects and the object's
+ * expression list.
+ *
+ * @param dictionary The dictionary that should be used to store the
+ * properties.
+ */
void ConfigItem::CalculateProperties(const Dictionary::Ptr& dictionary) const
{
BOOST_FOREACH(const String& name, m_Parents) {
if (!parent) {
stringstream message;
- message << "Parent object '" << name << "' does not exist (" << m_DebugInfo << ")";
+ message << "Parent object '" << name << "' does not"
+ " exist (" << m_DebugInfo << ")";
throw_exception(domain_error(message.str()));
}
m_ExpressionList->Execute(dictionary);
}
+/**
+ * Commits the configuration item by creating or updating a DynamicObject
+ * object.
+ *
+ * @returns The DynamicObject that was created/updated.
+ */
DynamicObject::Ptr ConfigItem::Commit(void)
{
DynamicObject::Ptr dobj = m_DynamicObject.lock();
return dobj;
}
+/**
+ * Unregisters the configuration item.
+ */
void ConfigItem::Unregister(void)
{
DynamicObject::Ptr dobj = m_DynamicObject.lock();
OnRemoved(GetSelf());
}
+/**
+ * Retrieves the DynamicObject that belongs to the configuration item.
+ *
+ * @returns The DynamicObject.
+ */
DynamicObject::Ptr ConfigItem::GetDynamicObject(void) const
{
return m_DynamicObject.lock();
}
+/**
+ * Retrieves a configuration item by type and name.
+ *
+ * @param type The type of the ConfigItem that is to be looked up.
+ * @param name The name of the ConfigItem that is to be looked up.
+ * @returns The configuration item.
+ */
ConfigItem::Ptr ConfigItem::GetObject(const String& type, const String& name)
{
ConfigItem::ItemMap::iterator it;
{
/**
- * A configuration item. Can be used to create a configuration object at
- * runtime.
+ * A configuration item. Non-abstract configuration items can be used to
+ * create configuration objects at runtime.
*
* @ingroup config
*/
DebugInfo GetDebugInfo(void) const;
- static ConfigItem::Ptr GetObject(const String& type, const String& name);
+ static ConfigItem::Ptr GetObject(const String& type,
+ const String& name);
static boost::signal<void (const ConfigItem::Ptr&)> OnCommitted;
static boost::signal<void (const ConfigItem::Ptr&)> OnRemoved;
private:
void CalculateProperties(const Dictionary::Ptr& dictionary) const;
- String m_Type;
- String m_Name;
+ String m_Type; /**< The object type. */
+ String m_Name; /**< The name. */
ExpressionList::Ptr m_ExpressionList;
- vector<String> m_Parents;
- DebugInfo m_DebugInfo;
+ vector<String> m_Parents; /**< The names of parent configuration
+ items. */
+ DebugInfo m_DebugInfo; /**< Debug information. */
- DynamicObject::WeakPtr m_DynamicObject;
+ DynamicObject::WeakPtr m_DynamicObject; /**< The instantiated version
+ of this configuration
+ item */
typedef map<pair<String, String>, ConfigItem::Ptr> ItemMap;
- static ItemMap m_Items;
+ static ItemMap m_Items; /**< All registered configuration items. */
};
}
m_ExpressionList->AddExpression(expr);
}
-void ConfigItemBuilder::AddExpression(const String& key, ExpressionOperator op, const Value& value)
+void ConfigItemBuilder::AddExpression(const String& key, ExpressionOperator op,
+ const Value& value)
{
Expression expr(key, op, value, m_DebugInfo);
AddExpression(expr);
Expression abstractExpr("__abstract", OperatorSet, m_Abstract, m_DebugInfo);
exprl->AddExpression(abstractExpr);
- return boost::make_shared<ConfigItem>(m_Type, m_Name, exprl, m_Parents, m_DebugInfo);
+ return boost::make_shared<ConfigItem>(m_Type, m_Name, exprl, m_Parents,
+ m_DebugInfo);
}
void AddParent(const String& parent);
void AddExpression(const Expression& expr);
- void AddExpression(const String& key, ExpressionOperator op, const Value& value);
+ void AddExpression(const String& key, ExpressionOperator op,
+ const Value& value);
void AddExpressionList(const ExpressionList::Ptr& exprl);
ConfigItem::Ptr Compile(void);
private:
- String m_Type;
- String m_Name;
- bool m_Local;
- bool m_Abstract;
- vector<String> m_Parents;
- ExpressionList::Ptr m_ExpressionList;
- DebugInfo m_DebugInfo;
+ String m_Type; /**< The object type. */
+ String m_Name; /**< The name. */
+ bool m_Local; /**< Whether the item is local. */
+ bool m_Abstract; /**< Whether the item is abstract. */
+ vector<String> m_Parents; /**< The names of parent configuration
+ items. */
+ ExpressionList::Ptr m_ExpressionList; /**< Expressions for this item. */
+ DebugInfo m_DebugInfo; /**< Debug information. */
};
}
};
};
+/**
+ * Outputs a DebugInfo struct to a stream.
+ *
+ * @param out The output stream.
+ * @param val The DebugInfo struct.
+ * @returns The output stream.
+ */
inline ostream& operator<<(ostream& out, const DebugInfo& val)
{
out << "in " << val.Path << ": "
using namespace icinga;
-Expression::Expression(const String& key, ExpressionOperator op, const Value& value, const DebugInfo& debuginfo)
+Expression::Expression(const String& key, ExpressionOperator op,
+ const Value& value, const DebugInfo& debuginfo)
: m_Key(key), m_Operator(op), m_Value(value), m_DebugInfo(debuginfo)
{
}
if (!dict) {
if (!oldValue.IsEmpty()) {
stringstream message;
- message << "Wrong argument types for += (non-dictionary and dictionary) (" << m_DebugInfo << ")";
+ message << "Wrong argument types for"
+ " += (non-dictionary and"
+ " dictionary) ("
+ << m_DebugInfo << ")";
throw_exception(domain_error(message.str()));
}
}
} else {
stringstream message;
- message << "+= only works for dictionaries (" << m_DebugInfo << ")";
+ message << "+= only works for dictionaries ("
+ << m_DebugInfo << ")";
throw_exception(domain_error(message.str()));
}
struct I2_CONFIG_API Expression
{
public:
- Expression(const String& key, ExpressionOperator op, const Value& value, const DebugInfo& debuginfo);
+ Expression(const String& key, ExpressionOperator op, const Value& value,
+ const DebugInfo& debuginfo);
void Execute(const Dictionary::Ptr& dictionary) const;
using namespace icinga;
+/**
+ * Adds an expression to an expression list.
+ *
+ * @param expression The expression that should be added.
+ */
void ExpressionList::AddExpression(const Expression& expression)
{
m_Expressions.push_back(expression);
}
+/**
+ * Returns the number of items currently contained in the expression list.
+ *
+ * @returns The length of the list.
+ */
size_t ExpressionList::GetLength(void) const
{
return m_Expressions.size();
}
+/**
+ * Executes the expression list.
+ *
+ * @param dictionary The dictionary that should be manipulated by the
+ * expressions.
+ */
void ExpressionList::Execute(const Dictionary::Ptr& dictionary) const
{
BOOST_FOREACH(const Expression& expression, m_Expressions) {
* @defgroup config Configuration library
*
* The configuration library implements a compiler for Icinga 2's configuration
- * format. It also provides functionality to create configuration objects
+ * format. It also provides functionality for creating configuration objects
* at runtime.
*/
projects / icinga2 / commitdiff