00001 /* 00002 * Copyright (C) 2008 Patrick Ohly 00003 * 00004 * This program is free software; you can redistribute it and/or modify 00005 * it under the terms of the GNU General Public License as published by 00006 * the Free Software Foundation; either version 2 of the License, or 00007 * (at your option) any later version. 00008 * 00009 * This program is distributed in the hope that it will be useful, 00010 * but WITHOUT ANY WARRANTY; without even the implied warranty of 00011 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 00012 * GNU General Public License for more details. 00013 * 00014 * You should have received a copy of the GNU General Public License 00015 * along with this program; if not, write to the Free Software 00016 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA 00017 */ 00018 00019 #ifndef INCL_EVOLUTION_CONFIG_TREE 00020 # define INCL_EVOLUTION_CONFIG_TREE 00021 00022 #include <boost/shared_ptr.hpp> 00023 #include <map> 00024 #include <list> 00025 #include <string> 00026 using namespace std; 00027 00028 class ConfigNode; 00029 00030 /** 00031 * This class organizes the access to config nodes in a tree. Nodes 00032 * are identified by a relative path name, using a slash / as 00033 * separator between levels. Each node can have user-visible and 00034 * hidden properties. The two sets might be stored in the same 00035 * ConfigNode, i.e. properties should have unique names per node. For 00036 * each path there's also a second, separate namespace of key/value 00037 * pairs. The intented use for that is saving state by sync sources 00038 * close to, but without interfering with their configuration and the 00039 * state maintained by the client library itself. 00040 * 00041 * A ConfigNode can list all its properties while the tree lists nodes 00042 * at a specific level and creates nodes. 00043 * 00044 * This model is similar to the Funambol C++ DeviceManagementTree. 00045 * Besides being implemented differently, it also provides additional 00046 * functionality: 00047 * - the same node can be opened more than once; in the client library 00048 * the content of multiple instances is not synchronized and changes 00049 * can get lost 00050 * - nodes and the whole tree can be explicitly flushed 00051 * - it distinguishes between user visible configuration options and 00052 * hidden read/write properties attached to the same path 00053 * - in addition to these visible or hidden properties under well-known 00054 * names there can be nodes attached to each path which can 00055 * be used for arbitrary key/value pairs; different "other" nodes can 00056 * be selected via an additional string 00057 * - temporarily override values without saving them (see FilterConfigNode 00058 * decorator) 00059 * - improved access to properties inside nodes (iterating, deleting) 00060 */ 00061 class ConfigTree { 00062 public: 00063 /** frees all resources *without* flushing changed nodes */ 00064 virtual ~ConfigTree() {} 00065 00066 /** ensure that all changes are saved persistently */ 00067 virtual void flush() = 0; 00068 00069 /** a string identifying the root of the configuration - exact meaning varies */ 00070 virtual string getRootPath() const = 0; 00071 00072 /** 00073 * Selects which node attached to a path name is to be used. 00074 * This is similar in concept to multiple data forks in a file. 00075 */ 00076 enum PropertyType { 00077 visible, /**< visible configuration properties */ 00078 hidden, /**< hidden read/write properties */ 00079 other /**< additional node selected via otherID */ 00080 }; 00081 00082 /** 00083 * Open the specified node. Opening it multiple 00084 * times will return the same instance, so the content 00085 * is always synchronized. 00086 * 00087 * @param path a relative path with / as separator 00088 * @param type selects which fork of that path is to be opened 00089 * (visible, hidden, change tracking) 00090 * @param otherId an additional string to be attached to the other 00091 * node's name (allows having multiple different such 00092 * nodes); an empty string is allowed 00093 */ 00094 virtual boost::shared_ptr<ConfigNode> open(const string &path, 00095 PropertyType type, 00096 const string &otherId = string("")) = 0; 00097 00098 /** 00099 * returns names of all existing nodes beneath the given path 00100 */ 00101 virtual list<string> getChildren(const string &path) = 0; 00102 }; 00103 00104 #endif