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

contact.h

00001 /*
00002  * This file is part of TelepathyQt4
00003  *
00004  * Copyright (C) 2008-2010 Collabora Ltd. <http://www.collabora.co.uk/>
00005  * Copyright (C) 2008-2010 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/Channel>
00030 #include <TelepathyQt4/Feature>
00031 #include <TelepathyQt4/Object>
00032 #include <TelepathyQt4/Types>
00033 
00034 #include <QSet>
00035 #include <QVariantMap>
00036 
00037 namespace Tp
00038 {
00039 
00040 struct AvatarData;
00041 class ContactCapabilities;
00042 class LocationInfo;
00043 class ContactManager;
00044 class PendingContactInfo;
00045 class PendingOperation;
00046 class Presence;
00047 class ReferencedHandles;
00048 
00049 class TELEPATHY_QT4_EXPORT Contact : public Object
00050 {
00051     Q_OBJECT
00052     Q_DISABLE_COPY(Contact)
00053 
00054 public:
00055     static const Feature FeatureAlias;
00056     static const Feature FeatureAvatarData;
00057     static const Feature FeatureAvatarToken;
00058     static const Feature FeatureCapabilities;
00059     static const Feature FeatureInfo;
00060     static const Feature FeatureLocation;
00061     static const Feature FeatureSimplePresence;
00062 
00063     enum PresenceState {
00064          PresenceStateNo,
00065          PresenceStateAsk,
00066          PresenceStateYes
00067     };
00068 
00069     class InfoFields
00070     {
00071     public:
00072         InfoFields();
00073         InfoFields(const ContactInfoFieldList &fields);
00074         InfoFields(const InfoFields &other);
00075         ~InfoFields();
00076 
00077         bool isValid() const { return mPriv.constData() != 0; }
00078 
00079         InfoFields &operator=(const InfoFields &other);
00080 
00081         ContactInfoFieldList fields(const QString &name) const;
00082 
00083         ContactInfoFieldList allFields() const;
00084 
00085     private:
00086         struct Private;
00087         friend struct Private;
00088         QSharedDataPointer<Private> mPriv;
00089     };
00090 
00091     ~Contact();
00092 
00093     ContactManagerPtr manager() const;
00094 
00095     ReferencedHandles handle() const;
00096 
00097     // TODO filter: exact, prefix, substring match
00098     QString id() const;
00099 
00100     Features requestedFeatures() const;
00101     Features actualFeatures() const;
00102 
00103     // TODO filter: exact, prefix, substring match
00104     QString alias() const;
00105 
00106     bool isAvatarTokenKnown() const;
00107     QString avatarToken() const;
00108     AvatarData avatarData() const;
00109     void requestAvatarData();
00110 
00111     /*
00112      * TODO filter:
00113      *  - exact match of presence().type(), presence().status()
00114      *  - ANY 1 of a number of presence types/statuses
00115      *  - presence().type() greater or less than a set value
00116      *  - have/don't have presence().message() AND exact/prefix/substring
00117      */
00118     Presence presence() const;
00119 
00120     // TODO filter: the same as Account filtering by caps
00121     ContactCapabilities capabilities() const;
00122 
00123     // TODO filter: is it available, how accurate, are they near me
00124     LocationInfo location() const;
00125 
00126     // TODO filter: having a specific field, having ANY field,
00127     // (field: exact, contents: exact/prefix/substring)
00128     bool isContactInfoKnown() const;
00129     InfoFields infoFields() const;
00130     PendingOperation *refreshInfo();
00131     PendingContactInfo *requestInfo();
00132 
00133     /*
00134      * Filters on exact values of these, but also the "in your contact list at all or not" usecase
00135      */
00136     bool isSubscriptionStateKnown() const;
00137     bool isSubscriptionRejected() const;
00138     PresenceState subscriptionState() const;
00139     bool isPublishStateKnown() const;
00140     bool isPublishCancelled() const;
00141     PresenceState publishState() const;
00142     QString publishStateMessage() const;
00143 
00144     PendingOperation *requestPresenceSubscription(const QString &message = QString());
00145     PendingOperation *removePresenceSubscription(const QString &message = QString());
00146     PendingOperation *authorizePresencePublication(const QString &message = QString());
00147     PendingOperation *removePresencePublication(const QString &message = QString());
00148 
00149     /*
00150      * Filter on being blocked or not
00151      */
00152     bool isBlocked() const;
00153     PendingOperation *block(bool value = true);
00154 
00155     /*
00156      * Filter on the groups they're in - to show a specific group only
00157      *
00158      * Also prefix/substring match on ANY of the groups of the contact
00159      */
00160     QStringList groups() const;
00161     PendingOperation *addToGroup(const QString &group);
00162     PendingOperation *removeFromGroup(const QString &group);
00163 
00164 Q_SIGNALS:
00165     void aliasChanged(const QString &alias);
00166 
00167     void avatarTokenChanged(const QString &avatarToken);
00168     void avatarDataChanged(const Tp::AvatarData &avatarData);
00169 
00170     void presenceChanged(const Tp::Presence &presence);
00171 
00172     void capabilitiesChanged(const Tp::ContactCapabilities &caps);
00173 
00174     void locationUpdated(const Tp::LocationInfo &location);
00175 
00176     void infoFieldsChanged(const Tp::Contact::InfoFields &infoFields);
00177 
00178     void subscriptionStateChanged(Tp::Contact::PresenceState state);
00179     // deprecated
00180     void subscriptionStateChanged(Tp::Contact::PresenceState state,
00181             const Tp::Channel::GroupMemberChangeDetails &details);
00182 
00183     void publishStateChanged(Tp::Contact::PresenceState state, const QString &message);
00184     // deprecated
00185     void publishStateChanged(Tp::Contact::PresenceState state,
00186             const Tp::Channel::GroupMemberChangeDetails &details);
00187 
00188     void blockStatusChanged(bool blocked);
00189     // deprecated
00190     void blockStatusChanged(bool blocked, const Tp::Channel::GroupMemberChangeDetails &details);
00191 
00192     void addedToGroup(const QString &group);
00193     void removedFromGroup(const QString &group);
00194 
00195     // TODO: consider how the Renaming interface should work and map to Contacts
00196     // I guess it would be something like:
00197     // void renamedTo(Tp::ContactPtr)
00198     // with that contact getting the same features requested as the current one. Or would we rather
00199     // want to signal that change right away with a handle?
00200 
00201 protected:
00202     // FIXME: (API/ABI break) Remove connectNotify
00203     void connectNotify(const char *);
00204 
00205 private:
00206     static const Feature FeatureRosterGroups;
00207 
00208     Contact(ContactManager *manager, const ReferencedHandles &handle,
00209             const Features &requestedFeatures, const QVariantMap &attributes);
00210 
00211     void augment(const Features &requestedFeatures, const QVariantMap &attributes);
00212 
00213     void receiveAlias(const QString &alias);
00214     void receiveAvatarToken(const QString &avatarToken);
00215     void setAvatarToken(const QString &token);
00216     void receiveAvatarData(const AvatarData &);
00217     void receiveSimplePresence(const SimplePresence &presence);
00218     void receiveCapabilities(const RequestableChannelClassList &caps);
00219     void receiveLocation(const QVariantMap &location);
00220     void receiveInfo(const ContactInfoFieldList &info);
00221 
00222     static PresenceState subscriptionStateToPresenceState(uint subscriptionState);
00223     void setSubscriptionState(SubscriptionState state);
00224     void setPublishState(SubscriptionState state, const QString &message = QString());
00225     void setBlocked(bool value);
00226 
00227     void setAddedToGroup(const QString &group);
00228     void setRemovedFromGroup(const QString &group);
00229 
00230     struct Private;
00231     friend class Connection;
00232     friend class ContactFactory;
00233     friend class ContactManager;
00234     friend struct Private;
00235     Private *mPriv;
00236 };
00237 
00238 } // Tp
00239 
00240 Q_DECLARE_METATYPE(Tp::Contact::InfoFields);
00241 
00242 #endif


Copyright © 2008-2010 Collabora Ltd. and Nokia Corporation
Telepathy-Qt4 0.5.8