kopete/plugins/statistics/statisticscontact.h

   1 /*
   2     statisticscontact.h
   3
   4     Copyright (c) 2003-2004 by Marc Cramdal        <marc.cramdal@gmail.com>
   5
   6     Copyright (c) 2007      by the Kopete Developers <kopete-devel@kde.org>
   7
   8     *************************************************************************
   9     *                                                                       *
  10     * This program is free software; you can redistribute it and/or modify  *
  11     * it under the terms of the GNU General Public License as published by  *
  12     * the Free Software Foundation; either version 2 of the License, or     *
  13     * (at your option) any later version.                                   *
  14     *                                                                       *
  15     *************************************************************************
  16 */
  17
  18 #ifndef STATISTICSCONTACT_H
  19 #define STATISTICSCONTACT_H
  20
  21 #include "kopeteonlinestatus.h"
  22 #include "kopetemessage.h"
  23 #include <QtCore/QList>
  24 #include <QtCore/QTime>
  25
  26 class StatisticsDB;
  27 class QDateTime;
  28
  29 class StatisticsContact
  30 {
  31
  32 public:
  33         StatisticsContact(Kopete::MetaContact *mc, StatisticsDB *db);
  34
  35         /**
  36          * We save all stats to the database (commonstats)
  37          */
  38         ~StatisticsContact();
  39
  40
  41         /*
  42          * Access method
  43          */
  44
  45         /** \brief Access method
  46          *  \return m_db
  47          */
  48          StatisticsDB *db() { return m_db; }
  49
  50         /** \brief Access method
  51          *  \return m_metaContact
  52          */
  53         Kopete::MetaContact *metaContact() { return m_metaContact; }
  54         /** \brief Access method
  55          *  \return m_oldStatus
  56          */
  57         Kopete::OnlineStatus::StatusType oldStatus() { return m_oldStatus; }
  58
  59         /** \brief Access method
  60          *  \return m_oldStatusDateTime
  61          */
  62         QDateTime oldStatusDateTime() { return m_oldStatusDateTime; }
  63
  64         /** \brief Access method
  65          *  \return m_messageLength
  66          */
  67         int messageLength() { return m_messageLength; }
  68         /** \brief Access method
  69          *  \return m_timeBetweenTwoMessages
  70          */
  71         int timeBetweenTwoMessages() { return m_timeBetweenTwoMessages; }
  72         /**
  73          * \brief Access method
  74          * \return m_lastTalk
  75          */
  76         QDateTime lastTalk() { return m_lastTalk; }
  77         /**
  78          * \brief Access method
  79          * \return m_lastPresent
  80          */
  81         QDateTime lastPresent() { return m_lastPresent; }
  82         /**
  83          * \brief sets \p m_isChatWindowOpen to true
  84          */
  85         void setIsChatWindowOpen(bool c) { m_isChatWindowOpen = c; }
  86
  87
  88
  89         /*
  90          * Method performing some useful actions
  91          */
  92         /**
  93          * \brief update the events database with the new statuss
  94          */
  95         void onlineStatusChanged(Kopete::OnlineStatus::StatusType status);
  96
  97         /**
  98          * \brief update the average time between to messages for this contact
  99          * Should be called when a new message is received by this contact
 100          */
 101         void newMessageReceived(Kopete::Message& m);
 102
 103         /**
 104          * \returns true if contact was status at dt, false else.
 105          */
 106         bool wasStatus(QDateTime dt, Kopete::OnlineStatus::StatusType status);
 107
 108         /**
 109          * \returns the status of the contact at dt. Return false if dt is invalid.
 110          */
 111         QString statusAt(QDateTime dt);
 112
 113         /**
 114          * \returns the main (most used) status of the contact at date (not time) dt. return false if dt is invalid.
 115          */
 116         QString mainStatusDate(const QDate& date);
 117         /*
 118          * Prevision methods
 119          */
 120         /**
 121 //       * \brief Give information on when the next event will occur
 122 //       *
 123 //       * \param status the status to be checked.
 124 //       * \retval nextEventDateTime the next event average prevision datetime.
 125 //       */
 126 //      QDateTime nextEvent(const Kopete::OnlineStatus::StatusType& status);
 127 //
 128 //      /**
 129 //       * \brief Convenience method for nextEvent with Offline status
 130 //       */
 131 //      QDateTime nextOfflineEvent();
 132 //
 133 //      /**
 134 //       * \brief Convenience method for nextEvent with Online status
 135 //       */
 136 //      QDateTime nextOnlineEvent();
 137
 138
 139         /**
 140          * \brief computes the main "status" events for the contact
 141          */
 142         QList<QTime> mainEvents(const Kopete::OnlineStatus::StatusType& status);
 143         /// \brief used by mainEvents()
 144         QList<int> computeCentroids(const QList<int>& centroids, const QList<int>& values);
 145
 146
 147 private:
 148         /**
 149          * \brief Checks if the value name exists in "commonstats" table, if not, add the row.
 150          *
 151          * \param name the name of the entry to be checked
 152          * \param statVar1 retrieve this var from the database. If it doesn't exists, get it from \p defaultValue1
 153          * \param statVar2 retrieve this var from the database. If it doesn't exists, get it from \p defaultValue2
 154          * \param defaultValue1 defaultValue for \p statVar1
 155          * \param defaultValue2 defaultValue for \p statVar2
 156          * \retval statvar1
 157          * \retval statvar2
 158          */
 159         void commonStatsCheck(const QString name, QString& statVar1, QString& statVar2, const QString defaultValue1 = "", const QString defaultValue2 = "");
 160
 161         /**
 162          * @brief Same as commonStatsCheck for integers.
 163          * Provided for convenience
 164          */
 165         void commonStatsCheck(const QString name, int& statVar1, int& statVar2, const int defaultValue1 = 0, const int defaultValue2 = -1);
 166
 167         /**
 168          * @brief Save a value in the "commonstats" table
 169          * \param name the name of the entry to be saved
 170          * \param statVar1 what we are going to store in the first column for this entry
 171          * \param statVar2 the second stat we can save in this table for this entry
 172          * \param statVarChanged if this param is true, we save. Else, we don't. Spare some disk usage.
 173          */
 174         void commonStatsSave(const QString name, const QString statVar1, const QString statVar2, const bool statVarChanged);
 175
 176         /**
 177          * Kopete::MetaContact linked to this StatisticsContact
 178          * Each StatisticsContact object _has_ to be linked to a metaContact
 179          */
 180         Kopete::MetaContact *m_metaContact;
 181
 182         /**
 183          * Required to be able to write to the database
 184          */
 185         StatisticsDB *m_db;
 186
 187         /**
 188          * The interest of statistics contact is to manage the changes of status
 189          * in order to correctly update the database. That's why here we keep the oldStatus
 190          */
 191         Kopete::OnlineStatus::StatusType m_oldStatus;
 192         /// We keep the old status datetime here
 193         QDateTime m_oldStatusDateTime;
 194
 195         /**
 196          * Average time this user takes between two of his messages
 197          * It may be used to compute a "speed" or "availability" for this contact
 198          */
 199         int m_timeBetweenTwoMessages;
 200         bool m_timeBetweenTwoMessagesChanged;
 201         /// Date at which the last message was received.
 202         /// Used to compute m_timeBetweenTwoMessages
 203         QDateTime m_lastMessageReceived;
 204         /// This is the ponderation corresponding to m_timeBetweenTwoMessagesOn
 205         int m_timeBetweenTwoMessagesOn;
 206         /// We don't count time if a chatwindow isn't open
 207         bool m_isChatWindowOpen;
 208
 209         /**
 210          * Average length of contact's messages
 211          */
 212         int m_messageLength;
 213         bool m_messageLengthChanged;
 214         /// This is the ponderation corresponding to m_messageLength
 215         int m_messageLengthOn;
 216
 217         /**
 218          * Last time user talked with this contact
 219          */
 220         QDateTime m_lastTalk;
 221         bool m_lastTalkChanged;
 222
 223         /**
 224          * Last time user was present (=online or away)
 225          */
 226         QDateTime m_lastPresent;
 227         bool m_lastPresentChanged;
 228 };
 229
 230
 231 #endif