1 /****************************************************************************

     2 **

     3 ** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).

     4 ** All rights reserved.

     5 ** Contact: Nokia Corporation (qt-info@nokia.com)

     6 **

     7 ** This file is part of the Qt Mobility Components.

     8 **

     9 ** $QT_BEGIN_LICENSE:LGPL$

    10 ** No Commercial Usage

    11 ** This file contains pre-release code and may not be distributed.

    12 ** You may use this file in accordance with the terms and conditions

    13 ** contained in the Technology Preview License Agreement accompanying

    14 ** this package.

    15 **

    16 ** GNU Lesser General Public License Usage

    17 ** Alternatively, this file may be used under the terms of the GNU Lesser

    18 ** General Public License version 2.1 as published by the Free Software

    19 ** Foundation and appearing in the file LICENSE.LGPL included in the

    20 ** packaging of this file.  Please review the following information to

    21 ** ensure the GNU Lesser General Public License version 2.1 requirements

    22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

    23 **

    24 ** In addition, as a special exception, Nokia gives you certain additional

    25 ** rights.  These rights are described in the Nokia Qt LGPL Exception

    26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

    27 **

    28 ** If you have questions regarding the use of this file, please contact

    29 ** Nokia at qt-info@nokia.com.

    30 **

    31 **

    32 **

    33 **

    34 **

    35 **

    36 **

    37 **

    38 ** $QT_END_LICENSE$

    39 **

    40 ****************************************************************************/

    41 

    42 #include "qcontactdetail.h"

    43 #include "qcontactdetail_p.h"

    44 #include "qcontactmanager.h"

    45 #include <QDebug>

    46 

    47 QTM_BEGIN_NAMESPACE

    48 

    49 /* Initialise our static private data member */

    50 QAtomicInt QContactDetailPrivate::lastDetailKey(1);

    51 

    52 /* Definitions of predefined string constants */

    53 Q_DEFINE_LATIN1_CONSTANT(QContactDetail::FieldDetailUri, "DetailUri");

    54 Q_DEFINE_LATIN1_CONSTANT(QContactDetail::FieldLinkedDetailUris, "LinkedDetailUris");

    55 Q_DEFINE_LATIN1_CONSTANT(QContactDetail::FieldContext, "Context");

    56 Q_DEFINE_LATIN1_CONSTANT(QContactDetail::ContextOther, "Other");

    57 Q_DEFINE_LATIN1_CONSTANT(QContactDetail::ContextHome, "Home");

    58 Q_DEFINE_LATIN1_CONSTANT(QContactDetail::ContextWork, "Work");

    59 

    60 /* Storage */

    61 QHash<QString, char*> QContactStringHolder::s_allocated;

    62 QHash<const char *, QString> QContactStringHolder::s_qstrings;

    63 

    64 /* Dtor function */

    65 static int qClearAllocatedStringHash()

    66 {

    67     QHash<QString, char*>::const_iterator it = QContactStringHolder::s_allocated.constBegin();

    68     while (it != QContactStringHolder::s_allocated.constEnd()) {

    69         delete[] it.value();

    70         it++;

    71     }

    72     QContactStringHolder::s_allocated.clear();

    73     QContactStringHolder::s_qstrings.clear();

    74     return 1;

    75 }

    76 Q_DESTRUCTOR_FUNCTION(qClearAllocatedStringHash);

    77 

    78 /*!

    79   \class QContactDetail

    80  

    81   \brief The QContactDetail class represents a single, complete detail about a contact.

    82   \ingroup contacts-main

    83  

    84   All of the information for a contact is stored in one or more QContactDetail objects.

    85  

    86   A detail is a group of logically related bits of data - for example, a street address is a single

    87   detail that has multiple fields (number, region, country etc).  Every QContactDetail has the name of an

    88   associated QContactDetailDefinition that describes the fields, their data type, and any

    89   restrictions on their values.  Different contact managers might have different detail definitions

    90   for the same name, depending on their capabilities.  For example, for the QContactName definition name,

    91   one manager might not support the middle name field, while a different manager may add an extra field for

    92   specific extra information not present in the default schema.

    93 

    94   Both the names of all the fields, and the name of the associated QContactDetailDefinition are stored

    95   as 8-bit strings encoded in Latin 1 for memory conservation.  Note, however, that the values stored

    96   in each field are not constrained in this way, and full unicode QStrings or QVariant data can be stored.

    97 

    98   One field which is common to all details is the context field.  This field is intended to store one or

    99   more contexts that this detail is associated with.  Commonly this will be something like

   100   "Home" and/or "Work", although no limitations are placed on which values may be stored in this field

   101   in the default schema.

   102 

   103   There are two other, related fields which are common to all details.  The first is

   104   \a QContactDetail::FieldDetailUri, which stores the unique URI of the detail if one exists.

   105   The field is not mandatory, and backends are not required to verify that the given URI is indeed

   106   unique within the contact.  The second field is \a QContactDetail::LinkedDetailUris, which stores

   107   a list of detail URIs to which this detail is linked.  The link is one-way, and can be used to show

   108   how or where a detail was derived.  This is useful for things like presence information and avatars,

   109   which are linked to a particular online account detail of the contact.

   110 

   111   When a QContactDetail has been retrieved in a QContact from a QContactManager, it may have certain

   112   access constraints provided with it, like \l ReadOnly or \l Irremovable.  This might mean that the

   113   supplied detail is calculated or otherwise not modifiable by the user - presence information is a

   114   good example.  Also, some details may be marked \l Irremovable.  These are typically things that

   115   a contact has to have - like a QContactDisplayLabel or a QContactType.

   116 

   117   It is possible to inherit from QContactDetail to provide convenience or

   118   standardized access to values.  For example, \l QContactPhoneNumber provides

   119   a convenient API for manipulating a QContactDetail as a phone number, according

   120   to the schema.

   121  

   122   In general, QContactDetail and the built in subclasses (like \l QContactPhoneNumber) provide

   123   constants for the names of fields (like \l QContactPhoneNumber::FieldNumber), and for predefined

   124   common values like \l QContactDetail::ContextHome.  Typically the constants for field names start

   125   with \c Field, and the constants for predefined values of a field start with the name of that field

   126   (e.g. \c ContextHome is a predefined constant for \c FieldContext).

   127 

   128   If you wish to create your own, customized contact detail, you should use

   129   the \l Q_DECLARE_CUSTOM_CONTACT_DETAIL macro in order to ensure proper

   130   operation, and declare your own field constants with \l Q_DECLARE_LATIN1_CONSTANT.

   131   See the predefined detail subclasses (like \l QContactPhoneNumber,

   132   \l QContactAddress) for more information.

   133  

   134   QContactDetail objects act like type checked values.  In general, you can assign them

   135   to and fro and have reasonable behaviour, like the following example.

   136  

   137   \code

   138  

   139   QContactPhoneNumber number;

   140   number.setNumber("555-1212");

   141   // number.value(QContactPhoneNumber::FieldNumber) == "555-1212";

   142   // number.definitionName() == QContactPhoneNumber::DefinitionName

   143  

   144   QContactDetail detail = number;

   145   // detail.value(QContactPhoneNumber::FieldNumber) == "555-1212";

   146   // detail.definitionName() == QContactPhoneNumber::DefinitionName

   147  

   148   QContactPhoneNumber otherNumber = detail;

   149   // otherNumber.number() == "555-1212";

   150   // otherNumber.definitionName() == QContactPhoneNumber::DefinitionName

   151  

   152   QContactAddress address = detail;

   153   // address is now a default constructed QContactAddress

   154   // address.value(QContactPhoneNumber::FieldNumber) is empty

   155   // address.definitionName() == QContactAddress::DefinitionName

   156  

   157   QContactAddress otherAddress = number;

   158   // otherAddress is now a default constructed QContactAddress

   159   // otherAddress.value(QContactPhoneNumber::FieldNumber) is empty

   160   // otherAddress.definitionName() == QContactAddress::DefinitionName

   161   \endcode

   162  

   163   \sa QContact, QContactDetailDefinition, QContactDetailFilter, QContactDetailRangeFilter, Q_DECLARE_CUSTOM_CONTACT_DETAIL

   164  */

   165 

   166 /*!

   167   \macro Q_DECLARE_CUSTOM_CONTACT_DETAIL

   168   \relates QContactDetail

   169 

   170   Macro for simplifying declaring custom (leaf) detail classes.

   171 

   172   The first argument is the name of the class, and the second argument

   173   is a Latin-1 string literal naming the detail type.

   174 

   175   If you are creating a convenience class for a type of QContactDetail,

   176   you should use this macro when declaring your class to ensure that

   177   it interoperates with other contact functionality.

   178 

   179   Here is an example of a class (\l QContactPhoneNumber) using this macro.

   180   Note that the class provides some predefined constants

   181   and some convenience methods that return values associated with schema

   182   fields.

   183 

   184   \snippet ../../src/contacts/details/qcontactphonenumber.h 0

   185  */

   186 

   187 /*!

   188     \class QLatin1Constant

   189     \headerfile

   190     \brief The QLatin1Constant class holds a Latin 1 string constant

   191 

   192 */

   193 

   194 /*!

   195     \fn QLatin1Constant::operator QString() const

   196     \internal

   197  */

   198 /*!

   199     \fn QLatin1Constant::operator QLatin1String() const

   200     \internal

   201  */

   202 /*!

   203     \fn QLatin1Constant::operator QVariant() const

   204     \internal

   205  */

   206 /*!

   207     \fn bool QLatin1Constant::operator ==(const QLatin1Constant& other) const

   208 

   209     Returns true if this QLatin1Constant is the same as \a other (either same object or

   210     same string literal), and false otherwise.

   211  */

   212 /*!

   213     \fn bool QLatin1Constant::operator !=(const QLatin1Constant& other) const

   214 

   215     Returns false if this QLatin1Constant is the same as \a other (either same object or

   216     same string literal), and true otherwise.

   217 */

   218 /*!

   219     \fn inline const char * QLatin1Constant::latin1() const

   220 

   221     Returns the value of this literal as a C style string (null terminated).

   222 */

   223 

   224 

   225 /*!

   226   \macro Q_DECLARE_LATIN1_CONSTANT

   227   \relates QLatin1Constant

   228 

   229   This macro, along with the related Q_DEFINE_LATIN1_CONSTANT macro,

   230   allows you to describe a "Latin 1 string constant".

   231 

   232   The resulting constant can be passed to functions accepting a

   233   QLatin1String, a QString, or a QVariant.

   234 

   235   The first parameter is the name of the variable to declare.  The

   236   second parameter is the value of the constant, as a string literal.

   237 

   238   For example:

   239   \code

   240   // in a header file

   241   Q_DECLARE_LATIN1_CONSTANT(MyConstant, "MYCONSTANT");

   242   \endcode

   243 

   244   The declaration should be paired with a matching Q_DEFINE_LATIN1_CONSTANT

   245   with the same arguments to actually define the constant.

   246 

   247   \sa Q_DEFINE_LATIN1_CONSTANT

   248 */

   249 

   250 /*!

   251   \macro Q_DEFINE_LATIN1_CONSTANT

   252   \relates QLatin1Constant

   253 

   254   This macro, along with the related Q_DECLARE_LATIN1_CONSTANT macro,

   255   allows you to describe a "Latin 1 string constant".

   256 

   257   The resulting constant can be passed to functions accepting a

   258   QLatin1String, a QString, or a QVariant.

   259 

   260   The first parameter is the name of the variable to define.  The

   261   second parameter is the value of the constant, as a string literal.

   262 

   263   For example:

   264   \code

   265   // in a header file

   266   Q_DECLARE_LATIN1_CONSTANT(MyConstant, "MYCONSTANT");

   267 

   268   // in source file

   269   Q_DEFINE_LATIN1_CONSTANT(MyConstant, "MYCONSTANT");

   270   \endcode

   271 

   272   You can use this macro without the matching DECLARE macro if

   273   you are using the constant only in a single compilation unit.

   274 

   275   \sa Q_DECLARE_LATIN1_CONSTANT

   276 */

   277 

   278 /*!

   279   \fn QContactDetail::operator!=(const QContactDetail& other) const

   280   Returns true if the values or id of this detail is different to those of the \a other detail

   281  */

   282 

   283 /*!

   284   Constructs a new, empty detail

   285  */

   286 QContactDetail::QContactDetail()

   287     : d(new QContactDetailPrivate)

   288 {

   289 }

   290 

   291 /*!

   292     Constructs a new, empty detail of the definition identified by \a thisDefinitionId.

   293     The definitionId must be restricted to the Latin 1 character set.

   294  */

   295 QContactDetail::QContactDetail(const QString& thisDefinitionId)

   296     : d(new QContactDetailPrivate)

   297 {

   298     d->m_definitionName = thisDefinitionId;

   299 }

   300 

   301 /*!

   302     Constructs a new, empty detail of the definition identified by \a thisDefinitionId

   303 

   304     The supplied pointer must be valid for the lifetime of the program.  In general

   305     this means it should be a constant, and not allocated on the stack.  If you cannot

   306     meet this requirement, use the alternative constructor that takes a QString instead.

   307 */

   308 QContactDetail::QContactDetail(const char* thisDefinitionId)

   309     : d(new QContactDetailPrivate)

   310 {

   311     d->m_definitionName = thisDefinitionId;

   312 }

   313 

   314 /*! Constructs a detail that is a copy of \a other */

   315 QContactDetail::QContactDetail(const QContactDetail& other)

   316     : d(other.d)

   317 {

   318 }

   319 

   320 /*!

   321     \internal

   322 

   323     Constructs a detail that is a copy of \a other if \a other is of the expected definition

   324     identified by \a expectedDefinitionId, else constructs a new, empty detail of the

   325     definition identified by the \a expectedDefinitionId.

   326 

   327     The \a expectedDefinitionId pointer must be valid for the lifetime of the program.

   328 */

   329 QContactDetail::QContactDetail(const QContactDetail& other, const char* expectedDefinitionId)

   330 {

   331     if (other.d->m_definitionName == expectedDefinitionId) {

   332         d = other.d;

   333     } else {

   334         d = new QContactDetailPrivate;

   335         d->m_definitionName = expectedDefinitionId;

   336     }

   337 }

   338 

   339 /*!

   340     \internal

   341 

   342     Constructs a detail that is a copy of \a other if \a other is of the expected definition

   343     identified by \a expectedDefinitionId, else constructs a new, empty detail of the

   344     definition identified by the \a expectedDefinitionId

   345 */

   346 QContactDetail::QContactDetail(const QContactDetail& other, const QString& expectedDefinitionId)

   347 {

   348     if (other.d->m_definitionName == expectedDefinitionId) {

   349         d = other.d;

   350     } else {

   351         d = new QContactDetailPrivate;

   352         d->m_definitionName = expectedDefinitionId;

   353     }

   354 }

   355 

   356 /*! Assigns this detail to \a other */

   357 QContactDetail& QContactDetail::operator=(const QContactDetail& other)

   358 {

   359     if (this != &other)

   360         d = other.d;

   361     return *this;

   362 }

   363 

   364 /*!

   365     \internal

   366 

   367     Assigns this detail to \a other if the definition of \a other is that identified

   368     by the given \a expectedDefinitionId, else assigns this detail to be a new, empty

   369     detail of the definition identified by the given \a expectedDefinitionId

   370 */

   371 QContactDetail& QContactDetail::assign(const QContactDetail& other, const char* expectedDefinitionId)

   372 {

   373     if (this != &other) {

   374         if (other.d->m_definitionName == expectedDefinitionId) {

   375             d = other.d;

   376         } else {

   377             d = new QContactDetailPrivate;

   378             d->m_definitionName = expectedDefinitionId;

   379         }

   380     }

   381     return *this;

   382 }

   383 

   384 /*!

   385     \internal

   386 

   387     Assigns this detail to \a other if the definition of \a other is that identified

   388     by the given \a expectedDefinitionId, else assigns this detail to be a new, empty

   389     detail of the definition identified by the given \a expectedDefinitionId

   390 */

   391 QContactDetail& QContactDetail::assign(const QContactDetail& other, const QString& expectedDefinitionId)

   392 {

   393     if (this != &other) {

   394         if (other.d->m_definitionName == expectedDefinitionId) {

   395             d = other.d;

   396         } else {

   397             d = new QContactDetailPrivate;

   398             d->m_definitionName = expectedDefinitionId;

   399         }

   400     }

   401     return *this;

   402 }

   403 

   404 /*! Frees the memory used by this detail */

   405 QContactDetail::~QContactDetail()

   406 {

   407 }

   408 

   409 /*!

   410     Returns the (unique) name of the definition which defines the semantics and structure of this detail.

   411     The actual QContactDetailDefinition should be retrieved from the relevant QContactManager using this name.

   412  */

   413 QString QContactDetail::definitionName() const

   414 {

   415     return d.constData()->m_definitionName.toQString();

   416 }

   417 

   418 /*!

   419     Compares this detail to \a other.  Returns true if the definition, access constraints and values of \a other are equal to those of this detail.

   420     The keys of each detail are not considered during the comparison, in order to allow details from different contacts to

   421     be compared according to their values.

   422  */

   423 bool QContactDetail::operator==(const QContactDetail& other) const

   424 {

   425     if (! (d.constData()->m_definitionName == other.d.constData()->m_definitionName))

   426         return false;

   427 

   428     if (d.constData()->m_access != other.d.constData()->m_access)

   429         return false;

   430 

   431     if (d.constData()->m_values != other.d.constData()->m_values)

   432         return false;

   433 

   434     return true;

   435 }

   436 

   437 uint qHash(const QContactStringHolder& key)

   438 {

   439     if (!key.m_str)

   440         return 0;

   441     uint h = 0;

   442     uint g;

   443     const register uchar*p = (const uchar*)key.m_str;

   444 

   445     while (*p) {

   446         h = (h << 4) + *p++;

   447         if ((g = (h & 0xf0000000)) != 0)

   448             h ^= g >> 23;

   449         h &= ~g;

   450     }

   451     return h;

   452 }

   453 

   454 /*! Returns the hash value for \a key. */

   455 uint qHash(const QContactDetail &key)

   456 {

   457     const QContactDetailPrivate* dptr= QContactDetailPrivate::detailPrivate(key);

   458     uint hash = qHash(dptr->m_definitionName)

   459                 + QT_PREPEND_NAMESPACE(qHash)(dptr->m_access);

   460     QHash<QContactStringHolder, QVariant>::const_iterator it = dptr->m_values.constBegin();

   461     while(it != dptr->m_values.constEnd()) {

   462         hash += qHash(it.key())

   463                 + QT_PREPEND_NAMESPACE(qHash)(it.value().toString());

   464         ++it;

   465     }

   466     return hash;

   467 }

   468 

   469 #ifndef QT_NO_DEBUG_STREAM

   470 QDebug operator<<(QDebug dbg, const QContactDetail& detail)

   471 {

   472     dbg.nospace() << "QContactDetail(name=" << detail.definitionName() << ", key=" << detail.key();

   473     QVariantMap fields = detail.variantValues();

   474     QVariantMap::const_iterator it;

   475     for (it = fields.constBegin(); it != fields.constEnd(); ++it) {

   476         dbg.nospace() << ", " << it.key() << '=' << it.value();

   477     }

   478     dbg.nospace() << ')';

   479     return dbg.maybeSpace();

   480 }

   481 #endif

   482 

   483 /*!

   484     Returns true if no values are contained in this detail.  Note that context is stored as a value; hence, if a context is set, this function will return false.

   485  */

   486 bool QContactDetail::isEmpty() const

   487 {

   488     if (!d.constData()->m_values.isEmpty())

   489         return false;

   490     return true;

   491 }

   492 

   493 /*!

   494  * Returns the key of this detail.

   495  *

   496  * Be aware that if a contact is retrieved (or reloaded) from the backend, the

   497  * keys of any details it contains may have been changed by the backend, or other

   498  * threads may have modified the contact details in the backend.  Therefore,

   499  * clients should reload the detail that they wish to save in or remove from a contact

   500  * after retrieving the contact from the backend, in order to ascertain the keys of

   501  * any such details.

   502  */

   503 int QContactDetail::key() const

   504 {

   505     return d->m_id;

   506 }

   507 

   508 /*! Causes the implicitly-shared detail to be detached from any other copies, and generates a new key for it.

   509     This ensures that calling QContact::saveDetail() will result in a new detail being saved, rather than

   510     another detail being updated. */

   511 void QContactDetail::resetKey()

   512 {

   513     d->m_id = QContactDetailPrivate::lastDetailKey.fetchAndAddOrdered(1);

   514 }

   515 

   516 /*! \overload

   517   Returns the value stored in this detail for the given \a key as a QString, or an empty QString if

   518   no value for the given \a key exists */

   519 QString QContactDetail::value(const QString& key) const

   520 {

   521     return d.constData()->m_values.value(QContactStringHolder(key)).toString();

   522 }

   523 

   524 /*!

   525     \internal

   526     \overload

   527     Returns the value stored in this detail for the given \a key as a QString, or an empty QString if

   528     no value for the given \a key exists

   529 */

   530 QString QContactDetail::value(const char* key) const

   531 {

   532     return d.constData()->m_values.value(key).toString();

   533 }

   534 

   535 /*!

   536     \fn T QContactDetail::value(const char* key) const

   537     \internal

   538     \overload

   539 */

   540 

   541 /*! Returns the value stored in this detail for the given \a key as a QVariant, or an invalid QVariant if no value for the given \a key exists */

   542 QVariant QContactDetail::variantValue(const QString& key) const

   543 {

   544     return d.constData()->m_values.value(QContactStringHolder(key));

   545 }

   546 

   547 /*!

   548     \internal

   549     Returns the value stored in this detail for the given \a key as a QVariant, or an invalid QVariant if no value for the given \a key exists

   550  */

   551 QVariant QContactDetail::variantValue(const char* key) const

   552 {

   553     return d.constData()->m_values.value(key);

   554 }

   555 

   556 /*!

   557   Returns true if this detail has a field with the given \a key, or false otherwise.

   558  */

   559 bool QContactDetail::hasValue(const QString& key) const

   560 {

   561     return d.constData()->m_values.contains(QContactStringHolder(key));

   562 }

   563 

   564 /*!

   565   \internal

   566   Returns true if this detail has a field with the given \a key, or false otherwise.

   567  */

   568 bool QContactDetail::hasValue(const char * key) const

   569 {

   570     return d.constData()->m_values.contains(key);

   571 }

   572 

   573 /*! Inserts \a value into the detail for the given \a key if \a value is valid.  If \a value is invalid,

   574     removes the field with the given \a key from the detail.  Returns true if the given \a value was set

   575     for the \a key (if the \a value was valid), or if the given \a key was removed from detail (if the

   576     \a value was invalid), and returns false if the key was unable to be removed (and the \a value was invalid) */

   577 bool QContactDetail::setValue(const QString& key, const QVariant& value)

   578 {

   579     if (!value.isValid())

   580         return removeValue(key);

   581 

   582     d->m_values.insert(QContactStringHolder(key), value);

   583     return true;

   584 }

   585 

   586 /*!

   587     \internal

   588 

   589     Inserts \a value into the detail for the given \a key if \a value is valid.  If \a value is invalid,

   590     removes the field with the given \a key from the detail.  Returns true if the given \a value was set

   591     for the \a key (if the \a value was valid), or if the given \a key was removed from detail (if the

   592     \a value was invalid), and returns false if the key was unable to be removed (and the \a value was invalid)

   593 */

   594 bool QContactDetail::setValue(const char* key, const QVariant& value)

   595 {

   596     if (!value.isValid())

   597         return removeValue(key);

   598 

   599     d->m_values.insert(key, value);

   600     return true;

   601 }

   602 

   603 /*!

   604     Removes the value stored in this detail for the given \a key.  Returns true if a value was stored

   605     for the given \a key and the operation succeeded, and false otherwise.

   606 */

   607 bool QContactDetail::removeValue(const QString& key)

   608 {

   609     if(d->m_values.remove(QContactStringHolder(key)))

   610         return true;

   611     return false;

   612 }

   613 

   614 /*!

   615     \internal

   616     Removes the value stored in this detail for the given \a key.  Returns true if a value was stored

   617     for the given \a key and the operation succeeded, and false otherwise.

   618 */

   619 bool QContactDetail::removeValue(const char * key)

   620 {

   621     if(d->m_values.remove(key))

   622         return true;

   623     return false;

   624 }

   625 

   626 /*!

   627   Returns the values stored in this detail as a map from value key to value

   628  */

   629 QVariantMap QContactDetail::variantValues() const

   630 {

   631     QVariantMap ret;

   632     QHash<QContactStringHolder, QVariant>::const_iterator it = d.constData()->m_values.constBegin();

   633     while(it != d.constData()->m_values.constEnd()) {

   634         ret.insert(it.key().toQString(), it.value());

   635         ++it;

   636     }

   637 

   638     return ret;

   639 }

   640 

   641 

   642 /*!

   643     \fn bool QContactDetail::setValue(const QLatin1Constant& key, const QVariant& value)

   644 

   645     Inserts \a value into the detail for the given \a key if \a value is valid.  If \a value is invalid,

   646     removes the field with the given \a key from the detail.  Returns true if the given \a value was set

   647     for the \a key (if the \a value was valid), or if the given \a key was removed from detail (if the

   648     \a value was invalid), and returns false if the key was unable to be removed (and the \a value was invalid)

   649 */

   650 /*!

   651     \fn bool QContactDetail::removeValue(const QLatin1Constant& key)

   652 

   653     Removes the value stored in this detail for the given \a key.  Returns true if a value was stored

   654     for the given \a key and the operation succeeded, and false otherwise.

   655 */

   656 

   657 /*!

   658     \fn bool QContactDetail::hasValue(const QLatin1Constant& key) const

   659     Returns true if this detail has a field with the given \a key, or false otherwise.

   660  */

   661 

   662 /*!

   663     \fn QVariant QContactDetail::variantValue(const QLatin1Constant& key) const

   664     Returns the value stored in this detail for the given \a key as a QVariant, or an invalid QVariant if no value for the given \a key exists

   665  */

   666 

   667 /*!

   668     \fn T QContactDetail::value(const QLatin1Constant& key) const

   669     \overload

   670     Returns the value of the template type associated with the given \a key

   671  */

   672 /*!

   673     \fn QString QContactDetail::value(const QLatin1Constant& key) const

   674     Returns the value stored in this detail for the given \a key as a QString, or an empty QString if

   675     no value for the given \a key exists

   676 */

   677 /*!

   678     \fn T QContactDetail::value(const QString& key) const

   679     Returns the value of the template type associated with the given \a key

   680  */

   681 

   682 /*!

   683   \enum QContactDetail::AccessConstraint

   684 

   685   This enum defines the access constraints for a detail.  This information is typically provided by

   686   the manager when a contact is retrieved.

   687 

   688   \value NoConstraint Users can read, write, and otherwise modify this detail in any manner.

   689   \value ReadOnly Users cannot write or modify values in this detail.

   690   \value Irremovable Users cannot remove this detail from a contact.

   691  */

   692 

   693 

   694 /*!

   695   Returns the access constraints associated with the detail.

   696 

   697   Some details may not be written to, while other details may

   698   not be removed from a contact.

   699 

   700   \sa QContactDetail::AccessConstraints

   701  */

   702 QContactDetail::AccessConstraints QContactDetail::accessConstraints() const

   703 {

   704     return d.constData()->m_access;

   705 }

   706 

   707 /*!

   708   \fn void QContactDetail::setContexts(const QStringList& contexts)

   709 

   710   This is a convenience function that sets the \c Context field of this detail to the given \a contexts.

   711 

   712   It is equivalent to the following code:

   713   \code

   714   setValue(QContactDetail::FieldContext, contexts);

   715   \endcode

   716 

   717   \sa setValue()

   718  */

   719 

   720 /*!

   721   \fn void QContactDetail::setContexts(const QString& context)

   722 

   723   This is a convenience function that sets the \c Context field of this detail to the given \a context.

   724   It is useful if the detail is only valid in a single context.

   725 

   726   It is equivalent to the following code:

   727   \code

   728   setValue(FieldContext, QStringList(context));

   729   \endcode

   730 

   731   \sa setValue()

   732  */

   733 

   734 /*!

   735   \fn QStringList QContactDetail::contexts() const

   736 

   737   This is a convenience function to return the \c Context field of this detail.

   738 

   739   It is equivalent to the following code:

   740   \code

   741   value<QStringList>(QContactDetail::FieldContext);

   742   \endcode

   743 

   744   \sa value()

   745  */

   746 

   747 

   748 /*!

   749   \fn void QContactDetail::setDetailUri(const QString& detailUri)

   750 

   751   This is a convenience function that sets the \c DetailUri field of this detail to the given \a detailUri.

   752   In order to be linked to, a detail must have a specific and (per-contact) unique detail URI set.

   753 

   754   It is equivalent to the following code:

   755   \code

   756   setValue(FieldDetailUri, detailUri);

   757   \endcode

   758 

   759   \sa setValue()

   760  */

   761 

   762 /*!

   763   \fn QString QContactDetail::detailUri() const

   764 

   765   This is a convenience function to return the \c DetailUri field of this detail.

   766 

   767   It is equivalent to the following code:

   768   \code

   769   value(QContactDetail::FieldDetailUri);

   770   \endcode

   771 

   772   \sa value()

   773  */

   774 

   775 

   776 /*!

   777   \fn void QContactDetail::setLinkedDetailUris(const QStringList& linkedDetailUris)

   778 

   779   This is a convenience function that sets the \c LinkedDetailUris field of this detail to the given \a linkedDetailUris.

   780 

   781   It is equivalent to the following code:

   782   \code

   783   setValue(QContactDetail::FieldLinkedDetailUris, linkedDetailUris);

   784   \endcode

   785 

   786   \sa setValue()

   787  */

   788 

   789 /*!

   790   \fn void QContactDetail::setLinkedDetailUris(const QString& linkedDetailUri)

   791 

   792   This is a convenience function that sets the \c LinkedDetailUris field of this detail to the given \a linkedDetailUri.

   793   It is useful if the detail is linked to a single other detail in the contact.

   794 

   795   It is equivalent to the following code:

   796   \code

   797   setValue(FieldLinkedDetailUris, QStringList(linkedDetailUri));

   798   \endcode

   799 

   800   \sa setValue()

   801  */

   802 

   803 /*!

   804   \fn QStringList QContactDetail::linkedDetailUris() const

   805 

   806   This is a convenience function to return the \c Context field of this detail.

   807 

   808   It is equivalent to the following code:

   809   \code

   810   value<QStringList>(QContactDetail::FieldLinkedDetailUris);

   811   \endcode

   812 

   813   \sa value()

   814  */

   815 

   816 QTM_END_NAMESPACE