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 

    43 #ifndef QCONTACTMANAGERENGINE_H

    44 #define QCONTACTMANAGERENGINE_H

    45 

    46 #include <QSharedData>

    47 #include <QMap>

    48 #include <QList>

    49 #include <QString>

    50 #include <QDateTime>

    51 #include <QVariant>

    52 #include <QObject>

    53 

    54 #include "qcontact.h"

    55 #include "qcontactdetaildefinition.h"

    56 #include "qcontactmanager.h"

    57 #include "qcontactabstractrequest.h"

    58 #include "qcontactrequests.h"

    59 #include "qcontactfetchhint.h"

    60 

    61 QTM_BEGIN_NAMESPACE

    62 

    63 class QContactFilter;

    64 class QContactSortOrder;

    65 

    66 class Q_CONTACTS_EXPORT QContactManagerEngine : public QObject

    67 {

    68     Q_OBJECT

    69 

    70 public:

    71     QContactManagerEngine() {}

    72 

    73     /* URI reporting */

    74     virtual QString managerName() const = 0;                       // e.g. "Symbian"

    75     virtual QMap<QString, QString> managerParameters() const;  // e.g. "filename=private.db"

    76     virtual int managerVersion() const = 0;

    77 

    78     /* Default and only implementation of this */

    79     QString managerUri() const;

    80 

    81     /* Filtering */

    82     virtual QList<QContactLocalId> contactIds(const QContactFilter& filter, const QList<QContactSortOrder>& sortOrders, QContactManager::Error* error) const;

    83     virtual QList<QContact> contacts(const QContactFilter& filter, const QList<QContactSortOrder>& sortOrders, const QContactFetchHint& fetchHint, QContactManager::Error* error) const;

    84     virtual QContact contact(const QContactLocalId& contactId, const QContactFetchHint& fetchHint, QContactManager::Error* error) const;

    85 

    86     virtual bool saveContact(QContact* contact, QContactManager::Error* error);

    87     virtual bool removeContact(const QContactLocalId& contactId, QContactManager::Error* error);

    88     virtual bool saveRelationship(QContactRelationship* relationship, QContactManager::Error* error);

    89     virtual bool removeRelationship(const QContactRelationship& relationship, QContactManager::Error* error);

    90 

    91     virtual bool saveContacts(QList<QContact>* contacts, QMap<int, QContactManager::Error>* errorMap, QContactManager::Error* error);

    92     virtual bool removeContacts(const QList<QContactLocalId>& contactIds, QMap<int, QContactManager::Error>* errorMap, QContactManager::Error* error);

    93 

    94     /* Return a pruned or modified contact which is valid and can be saved in the backend */

    95     virtual QContact compatibleContact(const QContact& original, QContactManager::Error* error) const;

    96 

    97     /* Synthesize the display label of a contact */

    98     virtual QString synthesizedDisplayLabel(const QContact& contact, QContactManager::Error* error) const;

    99 

   100     /* "Self" contact id (MyCard) */

   101     virtual bool setSelfContactId(const QContactLocalId& contactId, QContactManager::Error* error);

   102     virtual QContactLocalId selfContactId(QContactManager::Error* error) const;

   103 

   104     /* Relationships between contacts */

   105     virtual QList<QContactRelationship> relationships(const QString& relationshipType, const QContactId& participantId, QContactRelationship::Role role, QContactManager::Error* error) const;

   106     virtual bool saveRelationships(QList<QContactRelationship>* relationships, QMap<int, QContactManager::Error>* errorMap, QContactManager::Error* error);

   107     virtual bool removeRelationships(const QList<QContactRelationship>& relationships, QMap<int, QContactManager::Error>* errorMap, QContactManager::Error* error);

   108 

   109     /* Validation for saving */

   110     virtual bool validateContact(const QContact& contact, QContactManager::Error* error) const;

   111     virtual bool validateDefinition(const QContactDetailDefinition& def, QContactManager::Error* error) const;

   112 

   113     /* Definitions - Accessors and Mutators */

   114     virtual QMap<QString, QContactDetailDefinition> detailDefinitions(const QString& contactType, QContactManager::Error* error) const;

   115     virtual QContactDetailDefinition detailDefinition(const QString& definitionId, const QString& contactType, QContactManager::Error* error) const;

   116     virtual bool saveDetailDefinition(const QContactDetailDefinition& def, const QString& contactType, QContactManager::Error* error);

   117     virtual bool removeDetailDefinition(const QString& definitionId, const QString& contactType, QContactManager::Error* error);

   118 

   119     /* Asynchronous Request Support */

   120     virtual void requestDestroyed(QContactAbstractRequest* req);

   121     virtual bool startRequest(QContactAbstractRequest* req);

   122     virtual bool cancelRequest(QContactAbstractRequest* req);

   123     virtual bool waitForRequestFinished(QContactAbstractRequest* req, int msecs);

   124 

   125     /* Capabilities reporting */

   126     virtual bool hasFeature(QContactManager::ManagerFeature feature, const QString& contactType) const;

   127     virtual bool isRelationshipTypeSupported(const QString& relationshipType, const QString& contactType) const;

   128     virtual bool isFilterSupported(const QContactFilter& filter) const;

   129     virtual QList<QVariant::Type> supportedDataTypes() const;

   130     virtual QStringList supportedContactTypes() const;

   131 

   132     /* Reports the built-in definitions from the schema */

   133     static QMap<QString, QMap<QString, QContactDetailDefinition> > schemaDefinitions();

   134 

   135 Q_SIGNALS:

   136     void dataChanged();

   137     void contactsAdded(const QList<QContactLocalId>& contactIds);

   138     void contactsChanged(const QList<QContactLocalId>& contactIds);

   139     void contactsRemoved(const QList<QContactLocalId>& contactIds);

   140     void relationshipsAdded(const QList<QContactLocalId>& affectedContactIds);

   141     void relationshipsRemoved(const QList<QContactLocalId>& affectedContactIds);

   142     void selfContactIdChanged(const QContactLocalId& oldId, const QContactLocalId& newId);

   143 

   144 public:

   145     // Async update functions

   146     static void updateRequestState(QContactAbstractRequest* req, QContactAbstractRequest::State state);

   147 

   148     static void updateContactLocalIdFetchRequest(QContactLocalIdFetchRequest* req, const QList<QContactLocalId>& result, QContactManager::Error error, QContactAbstractRequest::State);

   149     static void updateContactFetchRequest(QContactFetchRequest* req, const QList<QContact>& result, QContactManager::Error error, QContactAbstractRequest::State);

   150     static void updateContactRemoveRequest(QContactRemoveRequest* req, QContactManager::Error error, const QMap<int, QContactManager::Error>& errorMap, QContactAbstractRequest::State);

   151     static void updateContactSaveRequest(QContactSaveRequest* req, const QList<QContact>& result, QContactManager::Error error, const QMap<int, QContactManager::Error>& errorMap, QContactAbstractRequest::State);

   152     static void updateDefinitionSaveRequest(QContactDetailDefinitionSaveRequest* req, const QList<QContactDetailDefinition>& result, QContactManager::Error error, const QMap<int, QContactManager::Error>& errorMap, QContactAbstractRequest::State);

   153     static void updateDefinitionRemoveRequest(QContactDetailDefinitionRemoveRequest* req, QContactManager::Error error, const QMap<int, QContactManager::Error>& errorMap, QContactAbstractRequest::State);

   154     static void updateDefinitionFetchRequest(QContactDetailDefinitionFetchRequest* req, const QMap<QString, QContactDetailDefinition>& result, QContactManager::Error error, const QMap<int, QContactManager::Error>& errorMap, QContactAbstractRequest::State);

   155     static void updateRelationshipSaveRequest(QContactRelationshipSaveRequest* req, const QList<QContactRelationship>& result, QContactManager::Error error, const QMap<int, QContactManager::Error>& errorMap, QContactAbstractRequest::State);

   156     static void updateRelationshipRemoveRequest(QContactRelationshipRemoveRequest* req, QContactManager::Error error, const QMap<int, QContactManager::Error>& errorMap, QContactAbstractRequest::State);

   157     static void updateRelationshipFetchRequest(QContactRelationshipFetchRequest* req, const QList<QContactRelationship>& result, QContactManager::Error error, QContactAbstractRequest::State);

   158 

   159     // Other protected area update functions

   160     static void setDetailAccessConstraints(QContactDetail* detail, QContactDetail::AccessConstraints constraints);

   161     static QContact Q_DECL_DEPRECATED setContactDisplayLabel(const QString& displayLabel, const QContact& contact);

   162     static void setContactDisplayLabel(QContact* contact, const QString& displayLabel);

   163     static void setContactRelationships(QContact* contact, const QList<QContactRelationship>& relationships);

   164 

   165     /* Helper functions */

   166     static int compareContact(const QContact& a, const QContact& b, const QList<QContactSortOrder>& sortOrders);

   167     static void addSorted(QList<QContact>* sorted, const QContact& toAdd, const QList<QContactSortOrder>& sortOrders);

   168     static int compareVariant(const QVariant& first, const QVariant& second, Qt::CaseSensitivity sensitivity);

   169     static bool testFilter(const QContactFilter& filter, const QContact& contact);

   170     static bool validateActionFilter(const QContactFilter& filter);

   171     static QList<QContactLocalId> sortContacts(const QList<QContact>& contacts, const QList<QContactSortOrder>& sortOrders);

   172 

   173     static QContactFilter canonicalizedFilter(const QContactFilter& filter);

   174 

   175 private:

   176     /* QContactChangeSet is a utility class used to emit the appropriate signals */

   177     friend class QContactChangeSet;

   178 };

   179 

   180 QTM_END_NAMESPACE

   181 

   182 #endif