2
* This file is part of buteo-syncfw package
4
* Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
6
* Contact: Sateesh Kavuri <sateesh.kavuri@nokia.com>
8
* This library is free software; you can redistribute it and/or
9
* modify it under the terms of the GNU Lesser General Public License
10
* version 2.1 as published by the Free Software Foundation.
12
* This library is distributed in the hope that it will be useful, but
13
* WITHOUT ANY WARRANTY; without even the implied warranty of
14
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15
* Lesser General Public License for more details.
17
* You should have received a copy of the GNU Lesser General Public
18
* License along with this library; if not, write to the Free Software
19
* Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
31
#include <QStringList>
32
#include "ProfileField.h"
43
/*! \brief This class represents a single profile, a collection of settings or
44
* data releated to some entity.
46
* A profile can contain keys, fields and other profiles as sub-profiles.
47
* Functions for accessing all these in different ways are provided. A profile
48
* object can be created from XML and exported to XML, but otherwise the class
49
* interface does not use XML. New classes can be derived from this class for
50
* different profile types to add helper functions for accessing specific keys
51
* and fields known by the profile type.
57
//! String constants for different profile type names.
58
static const QString TYPE_CLIENT;
59
static const QString TYPE_SERVER;
60
static const QString TYPE_STORAGE;
61
static const QString TYPE_SERVICE;
62
static const QString TYPE_SYNC;
64
/*! \brief Constructs a Profile object with given name and type.
66
* \param aName Profile name.
67
* \param aType Profile type. Prefer using predefined constants like
70
Profile(const QString &aName, const QString &aType);
72
/*! \brief Constructs a Profile object from XML.
74
* \param aRoot Root element of the profile XML.
76
explicit Profile(const QDomElement &aRoot);
78
/*! \brief Copy constructor.
80
* \param aSource Copy source.
82
Profile(const Profile &aSource);
84
/*! \brief Creates a clone of the profile.
88
virtual Profile *clone() const;
90
//! \brief Destructor.
93
/*! \brief Gets the name of the profile.
95
* \return Profile name.
99
/*! \brief Sets the name of the profile.
101
* \param aName Name of the profile.
103
virtual void setName(const QString &aName);
105
/*! \brief Gets the type of the profile.
107
* \return Profile type.
109
QString type() const;
111
/*! \brief Creates a XML representation of the profile.
113
* \param aDoc Parent document for the created XML elements. The elements
114
* are not inserted to the document by this function, but the document is
115
* required to create the elements.
116
* \param aLocalOnly Should only local profile elements be present in the
117
* generated XML. If this is true, elements merged from sub-profiles are
119
* \return Generated XML node tree.
121
virtual QDomElement toXml(QDomDocument &aDoc, bool aLocalOnly = true) const;
123
/*! \brief Outputs a XML representation of the profile to a string.
125
* Merged sub-profile data is also included in the output string.
126
* \return Generated XML string.
128
QString toString() const;
130
/*! \brief Gets the value of the given key.
132
* \param aName Name of the key to read.
133
* \param aDefault Default value.
134
* \return Value of the key. If the key was not found, the default is
135
* returned. If there are multiple instances of the key with the given
136
* name, the value of the first instance is returned.
138
QString key(const QString &aName, const QString &aDefault = QString()) const;
140
/*! \brief Gets all keys and their values.
142
* \return Map of key names/values.
144
QMap<QString, QString> allKeys() const;
146
/*! \brief Gets all keys that are not related to storages.
148
* \return Map of key names/values.
150
QMap<QString, QString> allNonStorageKeys() const;
152
/*! \brief Gets the value of the given boolean key.
154
* Returns true if the key exists and its value equals "true". If
155
* the key does not exist, the default value is returned.
156
* \param aName Name of the key to read.
157
* \param aDefault Value to return if the key does not exist.
158
* \return The boolean value of the key.
160
bool boolKey(const QString &aName, bool aDefault = false) const;
162
/*! \brief Gets the values of all keys with the given name.
164
* If the key does not exist at all, an empty list is returned.
165
* \param aName Name of the key to read.
166
* \return List of values associated with the key.
168
QStringList keyValues(const QString &aName) const;
170
/*! \brief Gets the names of all keys.
172
* \return List of key names.
174
QStringList keyNames() const;
176
/*! \brief Sets the value of a key.
178
* If the key does not exist yet, it is created.
179
* \param aName Name of the key.
180
* \param aValue Value of the key.
182
void setKey(const QString &aName, const QString &aValue);
184
/*! \brief Sets multiple values for a key.
186
* All previous (local) values of the key are removed. A key entry for
187
* each of the provided values is then created.
188
* \param aName Name of the key.
189
* \param aValues Values for the key.
191
void setKeyValues(const QString &aName, const QStringList &aValues);
193
/*! \brief Sets the value of a boolean key.
195
* The key value is set to "true" of "false". If the key does not exist
196
* yet, it is created.
197
* \param aName Name of the key.
198
* \param aValue Value of the key.
200
void setBoolKey(const QString &aName, bool aValue);
202
/*! \brief Removes a key from profile. All instances of the key are removed.
204
* \param aName Name of the key to remove.
206
void removeKey(const QString &aName);
208
/*! \brief Gets the field with the given name.
210
* If the field does not exist, NULL is returned.
211
* To get/set the value associated with the field, use the key handling
212
* functions with the name of the field.
213
* \param aName Name of the field.
214
* \return Pointer to the field.
216
const ProfileField *field(const QString &aName) const;
218
/*! \brief Gets all fields.
220
* \return List of pointers to the fields.
222
QList<const ProfileField*> allFields() const;
224
/*! \brief Gets all visible fields of the profile.
226
* Each field can define its visibility. This functions returns only
227
* fields that are visible.
228
* \return List of pointers to the visible fields.
230
QList<const ProfileField*> visibleFields() const;
232
/*! \brief Checks if the profile is valid.
234
* A profile is valid if:
235
* 1. Name and type are set (not empty).
236
* 2. For each field there is a key with the same name, and the key value
237
* (or all values, if multiple keys with the same name exist) is valid for
239
* 3. All sub-profiles are valid according to these three rules.
240
* \return Is the profile valid.
242
bool isValid() const;
244
/*! \brief Gets the names of all sub-profiles with the given type.
246
* \param aType Type of sub-profiles to get. If this is empty, all
247
* sub-profile names are returned.
248
* \return Names of the sub-profiles.
250
QStringList subProfileNames(const QString &aType = "") const;
252
/*! \brief Gets a sub-profile with the given name and type.
254
* \param aName Name of the sub-profile to get.
255
* \param aType Type of the sub-profile to get. If the type is empty,
256
* any type is accepted.
257
* \return The first sub-profile that matches the criteria. NULL if no such
258
* sub-profile was found. The returned sub-profile is owned by the main
259
* profile and the user must not delete it.
261
Profile *subProfile(const QString &aName, const QString &aType = "");
263
const Profile *subProfile(const QString &aName, const QString &aType = "") const;
265
/*! \brief Gets a sub-profile by key value.
267
* Returns the first sub-profile that has a key with the given value.
268
* \param aKey Name of the key.
269
* \param aValue Required value of the key.
270
* \param aType Type of the sub-profile. If empty, any type can match.
271
* \param aEnabledOnly Should only enabled sub-profiles be compared.
272
* \return First matching sub-profile, NULL if no match.
274
const Profile *subProfileByKeyValue(const QString &aKey,
275
const QString &aValue,
276
const QString &aType,
277
bool aEnabledOnly) const;
279
/*! \brief Gets all sub-profiles.
281
* \return List of sub-profiles. The returned sub-profiles are owned by the main
282
* profile and the user must not delete them.
284
QList<Profile*> allSubProfiles();
286
QList<const Profile*> allSubProfiles() const;
288
/*! \brief Merges a profile to this profile.
290
* The source profile and all its sub-profiles are merged as direct
291
* sub-profiles of this profile. This function is mainly used by the
292
* ProfileManager, when it constructs a single profile from multiple
294
* \param aSource Profile to merge.
296
void merge(const Profile &aSource);
298
/*! \brief Checks if the profile is fully constructed by loading all
299
* sub-profiles from separate profile files.
301
* A profile can have sub-profiles defined directly inside it, but
302
* typically the sub-profiles are made complete by checking if there is
303
* a separate profile file with the same name and type, and then loading
304
* and merging the keys and fields defined in these files to the ones
305
* defined directly in the main profile.
306
* \return Is the profile fully loaded.
308
bool isLoaded() const;
310
/*! \brief Sets if the profile is fully loaded.
312
* This function is used by the ProfileManager. The purpose of this flag
313
* is to avoid loading the same sub-profile multiple times, if there are
314
* more than one references to it in the sub-profile tree.
315
* \param aLoaded Is the profile loaded.
317
void setLoaded(bool aLoaded);
319
/*! \brief Returns if the profile is enabled.
321
* \return Is the profile enabled.
323
virtual bool isEnabled() const;
325
/*! \brief Set is the profile is enabled.
327
* \param aEnabled New enabled status.
329
void setEnabled(bool aEnabled);
331
/*! \brief Checks if the profile is hidden.
333
* A hidden profile should not be visible in sync ui.
334
* \return True if hidden.
336
bool isHidden() const;
338
/*! \brief Checks if the profile is protected.
340
* A protected profile can not be removed using the ProfileManager.
341
* \return True if protected.
343
bool isProtected() const;
347
Profile& operator=(const Profile &aRhs);
349
ProfilePrivate *d_ptr;
351
friend class ProfileTest;
added
removed
libsyncprofile/Profile.h
