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 #ifndef QCONTACT_H

    43 #define QCONTACT_H

    44 

    45 #include <QVariant>

    46 #include <QString>

    47 #include <QPair>

    48 #include <QMultiMap>

    49 #include <QList>

    50 #include <QDateTime>

    51 #include <QSharedDataPointer>

    52 

    53 #include "qtcontactsglobal.h"

    54 

    55 #include "qcontactdetail.h"

    56 #include "qcontactdetaildefinition.h"

    57 #include "qcontactdisplaylabel.h"

    58 #include "qcontactrelationship.h"

    59 #include "qcontactrelationshipfilter.h"

    60 #include "qcontacttype.h"

    61 

    62 QTM_BEGIN_NAMESPACE

    63 

    64 class QContactManager;

    65 class QContactData;

    66 class QContactName;

    67 class QContactAction;

    68 

    69 class Q_CONTACTS_EXPORT QContact

    70 {

    71 public:

    72     QContact();

    73 

    74     ~QContact();

    75 

    76     QContact(const QContact& other);

    77     QContact& operator=(const QContact& other);

    78 

    79     bool operator==(const QContact &other) const;

    80     bool operator!=(const QContact &other) const {return !(other == *this);}

    81 

    82     /* Unique ID */

    83     QContactId id() const;

    84     void setId(const QContactId& id);

    85     QContactLocalId localId() const;

    86 

    87     /* Type - contact, group, metacontact, ... */

    88     QString type() const;

    89     void setType(const QString& type);

    90     void setType(const QContactType& type);

    91 

    92     /* The (backend synthesized) display label of the contact */

    93     QString displayLabel() const;

    94 

    95     /* Is this an empty contact? */

    96     bool isEmpty() const;

    97     void clearDetails();

    98 

    99     /* deprecated */

   100     QContactDetail Q_DECL_DEPRECATED detailWithAction(const QString& actionName) const;

   101     QList<QContactDetail> Q_DECL_DEPRECATED detailsWithAction(const QString& actionName) const;

   102 

   103     /* Access details of particular type or which support a particular action */

   104     QContactDetail detail(const QString& definitionId) const;

   105     QList<QContactDetail> details(const QString& definitionId = QString()) const;

   106     QContactDetail detailWithAction(QContactAction* action) const;

   107     QList<QContactDetail> detailsWithAction(QContactAction* action) const;

   108 

   109     QList<QContactDetail> details(const QString& definitionName, const QString& fieldName, const QString& value) const;

   110 

   111     QContactDetail detail(const char* definitionId) const;

   112     QList<QContactDetail> details(const char* definitionId) const;

   113     QList<QContactDetail> details(const char* definitionId, const char* fieldName, const QString& value) const;

   114 

   115     /* Templated retrieval for definition names */

   116 #ifdef Q_QDOC

   117     QContactDetail detail(const QLatin1Constant& definitionName) const;

   118     QList<QContactDetail> details(const QLatin1Constant& definitionName) const;

   119     QList<QContactDetail> details(const QLatin1Constant& definitionName, const QLatin1Constant& fieldName, const QString& value);

   120 #else

   121     template <int N> QContactDetail detail(const QLatin1Constant<N>& definitionName) const

   122     {

   123         return detail(definitionName.latin1());

   124     }

   125     template <int N> QList<QContactDetail> details(const QLatin1Constant<N>& definitionName) const

   126     {

   127         return details(definitionName.latin1());

   128     }

   129     template <int N, int M> QList<QContactDetail> details(const QLatin1Constant<N>& definitionName, const QLatin1Constant<M>& fieldName, const QString& value)

   130     {

   131         return details(definitionName.latin1(), fieldName.latin1(), value);

   132     }

   133 #endif

   134 

   135     /* Templated (type-specific) detail retrieval */

   136     template<typename T> QList<T> details() const

   137     {

   138         QList<QContactDetail> props = details(T::DefinitionName.latin1());

   139         QList<T> ret;

   140         foreach(QContactDetail prop, props)

   141             ret.append(T(prop));

   142         return ret;

   143     }

   144 

   145     /* Templated (type-specific) detail retrieval base on given detail field name and field value */

   146     template<typename T> QList<T> details(const QString& fieldName, const QString& value) const

   147     {

   148         QList<QContactDetail> props = details(T::DefinitionName, fieldName, value);

   149         QList<T> ret;

   150         foreach(QContactDetail prop, props)

   151             ret.append(T(prop));

   152         return ret;

   153     }

   154 

   155     template<typename T> QList<T> details(const char* fieldName, const QString& value) const

   156     {

   157         QList<QContactDetail> props = details(T::DefinitionName.latin1(), fieldName, value);

   158         QList<T> ret;

   159         foreach(QContactDetail prop, props)

   160             ret.append(T(prop));

   161         return ret;

   162     }

   163 

   164     template<typename T> T detail() const

   165     {

   166         return T(detail(T::DefinitionName.latin1()));

   167     }

   168 

   169     /* generic detail addition/removal functions */

   170     bool saveDetail(QContactDetail* detail);   // modifies the detail - sets its ID if detail already exists

   171     bool removeDetail(QContactDetail* detail); // modifies the detail - unsets its ID

   172 

   173     /* Relationships that this contact was involved in when it was retrieved from the manager */

   174     QList<QContactRelationship> relationships(const QString& relationshipType = QString()) const;

   175     QList<QContactId> relatedContacts(const QString& relationshipType = QString(), QContactRelationship::Role role = QContactRelationship::Either) const;

   176 

   177     /* Actions available to be performed on this contact */

   178     QList<QContactActionDescriptor> availableActions(const QString& vendorName = QString(), int implementationVersion = -1) const;

   179 

   180     /* Preferences (eg, set a particular detail preferred for the SMS action) - subject to change! */

   181     bool setPreferredDetail(const QString& actionName, const QContactDetail& preferredDetail);

   182     bool isPreferredDetail(const QString& actionName, const QContactDetail& detail) const;

   183     QContactDetail preferredDetail(const QString& actionName) const;

   184     QMap<QString, QContactDetail> preferredDetails() const;

   185 

   186 private:

   187     friend class QContactManager;

   188     friend class QContactManagerData;

   189     friend class QContactManagerEngine;

   190 

   191     QSharedDataPointer<QContactData> d;

   192 };

   193 

   194 Q_CONTACTS_EXPORT uint qHash(const QContact& key);

   195 #ifndef QT_NO_DEBUG_STREAM

   196 Q_CONTACTS_EXPORT QDebug operator<<(QDebug dbg, const QContact& contact);

   197 #endif

   198 

   199 QTM_END_NAMESPACE

   200 

   201 Q_DECLARE_TYPEINFO(QTM_PREPEND_NAMESPACE(QContact), Q_MOVABLE_TYPE);

   202 

   203 

   204 #endif

   205