1 /*

     2 * Copyright (c) 2010 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description: Class for asynchronously fetching and caching

    15 *              basic contact info for list views.

    16 *

    17 */

    18 

    19 #ifndef CNTCACHE_H

    20 #define CNTCACHE_H

    21 

    22 #include <QObject>

    23 #include <QSharedData>

    24 #include <HbIcon>

    25 #include <qcontactmanager.h>

    26 #include <cntinfoprovider.h>

    27 

    28 class CntContactInfoData;

    29 class CntCacheThread;

    30 class CntInfoCacheItem;

    31 class CntIconCacheItem;

    32 

    33 QTM_USE_NAMESPACE

    34 

    35 /*

    36    Info about one contact that can be used by listviews:

    37    - the id

    38    - the full name, properly formatted

    39    - text, secondary information like phone number

    40    - icon1, the main icon

    41    - icon2, a secondary icon

    42  */

    43 class CntContactInfo : public QObject

    44 {

    45     Q_OBJECT

    46 public:

    47     CntContactInfo();

    48     CntContactInfo(int id, const QString& name, const QString& text, const HbIcon& icon1, const HbIcon& icon2);

    49     ~CntContactInfo();

    50 

    51     CntContactInfo(const CntContactInfo& other);

    52     CntContactInfo& operator=(const CntContactInfo& other);

    53 

    54     int id() const;

    55     QString name() const;

    56     QString text() const;

    57     HbIcon icon1() const;

    58     HbIcon icon2() const;

    59 

    60 private:

    61     QSharedDataPointer<CntContactInfoData> d;

    62 };

    63 

    64 /*

    65    Singleton class that acts as a proxy to get CntContactInfo objects for contacts.

    66    It also implements caching for faster access. This is why the fetchContactInfo()

    67    function takes a row number and the full list of contact IDs rather than just a

    68    contact ID -- the former allows caching ahead.

    69    

    70    The usage pattern for clients is to call fetchContactInfo() to get at least the

    71    name of the contact. If all the info is cached then it will be provided. If not,

    72    then the uncached info is fetched asynchronously and contactInfoUpdated signals

    73    are emitted as the pieces of information arrive -- up to three times per contact;

    74    once for text, once for icon1 and once for icon2.

    75  */

    76 class CntCache : public QObject

    77 {

    78     Q_OBJECT

    79 public:

    80     static CntCache* instance();

    81     CntContactInfo fetchContactInfo(int row, const QList<QContactLocalId>& idList);

    82 

    83 public slots:

    84     void clearCache();

    85 

    86 signals:

    87     void contactInfoUpdated(QContactLocalId contactId);

    88 

    89 private:

    90     CntCache();

    91     ~CntCache();

    92     bool fetchContactName(int contactId, QString& contactName);

    93     void updateReadAheadCache(int mostRecentRow, const QList<QContactLocalId>& idList);

    94     CntInfoCacheItem* createInfoCacheItem(int contactId);

    95     CntIconCacheItem* createIconCacheItem(const QString& iconName);

    96     void emitContactInfoUpdated(int contactId);

    97 

    98 private slots:

    99     void onNewInfo(int contactId, const ContactInfoField& infoField, const QString& infoValue);

   100     void onInfoCancelled(int contactId);

   101     void onNewIcon(const QString& iconName, const HbIcon& icon);

   102     void onIconCancelled(const QString& iconName);

   103     void onShutdown();

   104     void removeContactsFromCache(const QList<QContactLocalId>& contactIds);

   105     void scheduleOneReadAheadItem();

   106 

   107 private:

   108     static CntCache* mInstance;                   // the one and only instance of CntCache

   109     QContactManager* mContactManager;             // for fetching contact names and for getting

   110                                                   // notifications about changes to contacts

   111     CntCacheThread* mWorker;                      // the background thread that does the actual fetching

   112     QList<int> mReadAheadCache;                   // cache with set of IDs to prefetch (they are likely to be needed soon)

   113     QHash<int,CntInfoCacheItem*> mInfoCache;      // cache with contact info, indexed by contact ids

   114     QHash<QString,CntIconCacheItem*> mIconCache;  // cache with icons, indexed by icon name

   115     int mNextInfoCacheOrder;                      // cache order for the next item to be updated/inserted in info cache

   116     int mNextIconCacheOrder;                      // cache order for the next item to be updated/inserted in icon cache

   117     int mEmittedContactId;                        // id of the last contact emitted to UI

   118 };

   119 

   120 #endif