/*
 * Copyright (C) 2008 Patrick Ohly
 */

#ifndef INCL_EVOLUTION_ABSTRACT_CONFIG_NODE
# define INCL_EVOLUTION_ABSTRACT_CONFIG_NODE

#include <map>
#include <utility>
#include <string>
using namespace std;

/**
 * This class corresponds to the Funambol C++ client
 * DeviceManagementNode, but offers a slightly different API.  See
 * ConfigTree for details.
 */
class ConfigNode {
 public:
    /** free resources without saving */
    virtual ~ConfigNode() {}

    /** a name for the node that the user can understand */
    virtual string getName() const = 0;

    /**
     * save all changes persistently
     */
    virtual void flush() = 0;

    /**
     * Returns the value of the given property
     *
     * @param property - the property name
     * @return value of the property or empty string if not set
     */
    virtual string readProperty(const string &property) const = 0;

    /**
     * Sets a property value.
     *
     * @param property   the property name
     * @param value      the property value (zero terminated string)
     * @param comment    a comment explaining what the property is about, with
     *                   \n separating lines; might be used by the backend 
     *                   when adding a new property
     * @param defValue   If a defValue is provided and the value
     *                   matches the default, then the node is asked to
     *                   remember that the value hasn't really been changed.
     *                   An implementation can decide to not support this.
     */
    virtual void setProperty(const string &property,
                             const string &value,
                             const string &comment = string(""),
                             const string *defValue = NULL) = 0;

    /**
     * Extract all list of all currently defined properties
     * and their values. Does not include values which were
     * initialized with their defaults, if the implementation
     * remembers that.
     *
     * @retval props    to be filled with key/value pairs; guaranteed
     *                  to be empty before the call
     */
    virtual void readProperties(map<string, string> &props) const = 0;

    /**
     * Remove a certain property.
     *
     * @param property    the name of the property which is to be removed
     */
    virtual void removeProperty(const string &property) = 0;

    /**
     * Node exists in backend storage.
     */
    virtual bool exists() const = 0;
};

#endif