| Home · All Classes · All Namespaces · Modules · Functions · Files

# contact.h

    00001 /*
    00002  * This file is part of TelepathyQt4
    00003  *
    00004  * Copyright (C) 2008 Collabora Ltd. <http://www.collabora.co.uk/>
    00005  * Copyright (C) 2008 Nokia Corporation
    00006  *
    00007  * This library is free software; you can redistribute it and/or
    00008  * modify it under the terms of the GNU Lesser General Public
    00009  * License as published by the Free Software Foundation; either
    00010  * version 2.1 of the License, or (at your option) any later version.
    00011  *
    00012  * This library is distributed in the hope that it will be useful,
    00013  * but WITHOUT ANY WARRANTY; without even the implied warranty of
    00014  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
    00015  * Lesser General Public License for more details.
    00016  *
    00017  * You should have received a copy of the GNU Lesser General Public
    00018  * License along with this library; if not, write to the Free Software
    00019  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
    00020  */
    00021
    00022 #ifndef _TelepathyQt4_contact_h_HEADER_GUARD_
    00023 #define _TelepathyQt4_contact_h_HEADER_GUARD_
    00024
    00025 #ifndef IN_TELEPATHY_QT4_HEADER
    00026 #error IN_TELEPATHY_QT4_HEADER
    00027 #endif
    00028
    00029 #include <TelepathyQt4/Types>
    00030
    00031 #include <QObject>
    00032 #include <QSet>
    00033 #include <QSharedPointer>
    00034 #include <QVariantMap>
    00035
    00036 namespace Tp
    00037 {
    00038
    00039 class ContactCapabilities;
    00040 class ContactLocation;
    00041 class ContactManager;
    00042 class PendingContactInfo;
    00043 class PendingOperation;
    00044 class Presence;
    00045 class ReferencedHandles;
    00046
    00047 class TELEPATHY_QT4_EXPORT Contact : public QObject
    00048 {
    00049     Q_OBJECT
    00050     Q_DISABLE_COPY(Contact);
    00051
    00052 public:
    00053     enum Feature {
    00054         FeatureAlias,
    00055         FeatureAvatarToken,
    00056         FeatureSimplePresence,
    00057         FeatureCapabilities,
    00058         FeatureLocation,
    00059         FeatureInfo,
    00060         FeatureAvatarData,
    00061         _Padding = 0xFFFFFFFF
    00062     };
    00063
    00064     enum PresenceState {
    00065          PresenceStateNo,
    00066          PresenceStateAsk,
    00067          PresenceStateYes
    00068     };
    00069
    00070     class InfoFields
    00071     {
    00072     public:
    00073         InfoFields();
    00074         InfoFields(const ContactInfoFieldList &fields);
    00075         InfoFields(const InfoFields &other);
    00076         ~InfoFields();
    00077
    00078         bool isValid() const { return mPriv.constData() != 0; }
    00079
    00080         InfoFields &operator=(const InfoFields &other);
    00081
    00082         ContactInfoFieldList fields(const QString &name) const;
    00083
    00084         ContactInfoFieldList allFields() const;
    00085
    00086     private:
    00087         struct Private;
    00088         friend struct Private;
    00089         QSharedDataPointer<Private> mPriv;
    00090     };
    00091
    00092     ContactManager *manager() const;
    00093
    00094     ReferencedHandles handle() const;
    00095     QString id() const; // TODO filter: exact, prefix, substring match
    00096
    00097     QSet<Feature> requestedFeatures() const;
    00098     QSet<Feature> actualFeatures() const;
    00099
    00100     QString alias() const; // TODO filter: exact, prefix, substring match
    00101
    00102     bool isAvatarTokenKnown() const;
    00103     QString avatarToken() const;
    00104     AvatarData avatarData() const;
    00105
    00106     /*
    00107      * TODO filter:
    00108      *  - exact match of presenceType, presenceStatus
    00109      *  - ANY 1 of a number of presenceTypes/Statuses
    00110      *  - presenceType greater or less than a set value
    00111      */
    00112     TELEPATHY_QT4_DEPRECATED QString presenceStatus() const;
    00113     TELEPATHY_QT4_DEPRECATED uint presenceType() const;
    00114     // TODO filter: have/don't have message AND exact/prefix/substring
    00115     TELEPATHY_QT4_DEPRECATED QString presenceMessage() const;
    00116
    00117     Presence presence() const;
    00118
    00119     // TODO filter: the same as Account filtering by caps
    00120     // FIXME: (API/ABI break) Return ContactCapabilities
    00121     ContactCapabilities *capabilities() const;
    00122
    00123     // TODO filter: is it available, how accurate, are they near me
    00124     // FIXME: (API/ABI break) Return ContactLocation
    00125     ContactLocation *location() const;
    00126
    00127     // TODO filter: having a specific field, having ANY field,
    00128     // (field: exact, contents: exact/prefix/substring)
    00129     TELEPATHY_QT4_DEPRECATED ContactInfoFieldList info() const;
    00130     InfoFields infoFields() const;
    00131     PendingOperation *refreshInfo();
    00132     PendingContactInfo *requestInfo();
    00133
    00134     /*
    00135      * Filters on exact values of these, but also the "in your contact list at all or not" usecase
    00136      */
    00137     PresenceState subscriptionState() const;
    00138     PresenceState publishState() const;
    00139
    00140     PendingOperation *requestPresenceSubscription(const QString &message = QString());
    00141     PendingOperation *removePresenceSubscription(const QString &message = QString());
    00142     PendingOperation *authorizePresencePublication(const QString &message = QString());
    00143     PendingOperation *removePresencePublication(const QString &message = QString());
    00144
    00145     /*
    00146      * Filter on being blocked or not
    00147      */
    00148     bool isBlocked() const;
    00149     PendingOperation *block(bool value = true);
    00150
    00151     /*
    00152      * Filter on the groups they're in - to show a specific group only
    00153      *
    00154      * Also prefix/substring match on ANY of the groups of the contact
    00155      */
    00156     QStringList groups() const;
    00157     PendingOperation *addToGroup(const QString &group);
    00158     PendingOperation *removeFromGroup(const QString &group);
    00159
    00160     ~Contact();
    00161
    00162 Q_SIGNALS:
    00163     void aliasChanged(const QString &alias);
    00164
    00165     void avatarTokenChanged(const QString &avatarToken);
    00166     void avatarDataChanged(const Tp::AvatarData &avatarData);
    00167
    00168     // FIXME: (API/ABI break) Remove simplePresenceChanged in favor of presenceChanged
    00169     void simplePresenceChanged(const QString &status, uint type, const QString &presenceMessage);
    00170     void presenceChanged(const Tp::Presence &presence);
    00171
    00172     // FIXME: (API/ABI break) Use Tp::ContactCapabilities
    00173     void capabilitiesChanged(Tp::ContactCapabilities *caps);
    00174
    00175     // FIXME: (API/ABI break) Use Tp::ContactLocation
    00176     void locationUpdated(Tp::ContactLocation *location);
    00177
    00178     // FIXME: (API/ABI break) Remove infoChanged in favor of infoFieldsChanged
    00179     void infoChanged(const Tp::ContactInfoFieldList &info);
    00180     void infoFieldsChanged(const Tp::Contact::InfoFields &infoFields);
    00181
    00182     void subscriptionStateChanged(Tp::Contact::PresenceState state);
    00183     void publishStateChanged(Tp::Contact::PresenceState state);
    00184     void blockStatusChanged(bool blocked);
    00185
    00186     void addedToGroup(const QString &group);
    00187     void removedFromGroup(const QString &group);
    00188
    00189     // TODO: consider how the Renaming interface should work and map to Contacts
    00190     // I guess it would be something like:
    00191     // void renamedTo(Tp::ContactPtr)
    00192     // with that contact getting the same features requested as the current one. Or would we rather
    00193     // want to signal that change right away with a handle?
    00194
    00195 protected:
    00196     // FIXME: (API/ABI break) Remove connectNotify
    00197     void connectNotify(const char *);
    00198
    00199 private:
    00200     Contact(ContactManager *manager, const ReferencedHandles &handle,
    00201             const QSet<Feature> &requestedFeatures, const QVariantMap &attributes);
    00202
    00203     void augment(const QSet<Feature> &requestedFeatures, const QVariantMap &attributes);
    00204
    00205     void receiveAlias(const QString &alias);
    00206     void receiveAvatarToken(const QString &avatarToken);
    00207     void setAvatarToken(const QString &token);
    00208     void receiveAvatarData(const AvatarData &);
    00209     void receiveSimplePresence(const SimplePresence &presence);
    00210     void receiveCapabilities(const RequestableChannelClassList &caps);
    00211     void receiveLocation(const QVariantMap &location);
    00212     void receiveInfo(const ContactInfoFieldList &info);
    00213
    00214     void setSubscriptionState(PresenceState state);
    00215     void setPublishState(PresenceState state);
    00216     void setBlocked(bool value);
    00217
    00218     void setAddedToGroup(const QString &group);
    00219     void setRemovedFromGroup(const QString &group);
    00220
    00221     struct Private;
    00222     friend class ContactManager;
    00223     friend struct Private;
    00224     Private *mPriv;
    00225 };
    00226
    00227 typedef QSet<ContactPtr> Contacts;
    00228
    00229 // FIXME: (API/ABI break) Remove once Contact is a SharedPtr and add a new qHash(SharedPtr<T>)
    00230 inline uint qHash(const ContactPtr &contact)
    00231 {
    00232     return qHash(contact.data());
    00233 }
    00234
    00235 } // Tp
    00236
    00237 Q_DECLARE_METATYPE(Tp::Contact::InfoFields);
    00238
    00239 #endif