TelepathyQt4: connection.h Source File

00001 /*
00002  * This file is part of TelepathyQt4
00003  *
00004  * Copyright (C) 2008, 2009 Collabora Ltd. <http://www.collabora.co.uk/>
00005  * Copyright (C) 2008, 2009 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_connection_h_HEADER_GUARD_
00023 #define _TelepathyQt4_connection_h_HEADER_GUARD_
00024 
00025 #ifndef IN_TELEPATHY_QT4_HEADER
00026 #error IN_TELEPATHY_QT4_HEADER
00027 #endif
00028 
00029 #include <TelepathyQt4/_gen/cli-connection.h>
00030 
00031 #include <TelepathyQt4/Contact>
00032 #include <TelepathyQt4/DBus>
00033 #include <TelepathyQt4/DBusProxy>
00034 #include <TelepathyQt4/OptionalInterfaceFactory>
00035 #include <TelepathyQt4/ReadinessHelper>
00036 #include <TelepathyQt4/ReadyObject>
00037 #include <TelepathyQt4/Types>
00038 #include <TelepathyQt4/SharedPtr>
00039 
00040 #include <TelepathyQt4/Constants>
00041 #include <TelepathyQt4/Types>
00042 
00043 #include <QSet>
00044 #include <QString>
00045 #include <QStringList>
00046 
00047 namespace Tp
00048 {
00049 
00050 class Channel;
00051 class ConnectionCapabilities;
00052 class Contact;
00053 class ContactManager;
00054 class PendingChannel;
00055 class PendingContactAttributes;
00056 class PendingHandles;
00057 class PendingOperation;
00058 class PendingReady;
00059 
00060 class TELEPATHY_QT4_EXPORT Connection : public StatefulDBusProxy,
00061                    public OptionalInterfaceFactory<Connection>,
00062                    public ReadyObject,
00063                    public RefCounted
00064 {
00065     Q_OBJECT
00066     Q_DISABLE_COPY(Connection)
00067     Q_ENUMS(Status)
00068 
00069 public:
00070     static const Feature FeatureCore;
00071     static const Feature FeatureSelfContact;
00072     static const Feature FeatureSimplePresence;
00073     static const Feature FeatureRoster;
00074     static const Feature FeatureRosterGroups;
00075     static const Feature FeatureAccountBalance; // TODO unit tests for this
00076 
00077     enum Status {
00078         StatusDisconnected = ConnectionStatusDisconnected,
00079         StatusConnecting = ConnectionStatusConnecting,
00080         StatusConnected = ConnectionStatusConnected,
00081         StatusUnknown = 0xFFFFFFFF
00082     };
00083 
00084     TELEPATHY_QT4_DEPRECATED static ConnectionPtr create(const QString &busName,
00085             const QString &objectPath);
00086     TELEPATHY_QT4_DEPRECATED static ConnectionPtr create(const QDBusConnection &bus,
00087             const QString &busName, const QString &objectPath);
00088 
00089     static ConnectionPtr create(const QString &busName,
00090             const QString &objectPath,
00091             const ChannelFactoryConstPtr &channelFactory,
00092             const ContactFactoryConstPtr &contactFactory);
00093     static ConnectionPtr create(const QDBusConnection &bus,
00094             const QString &busName, const QString &objectPath,
00095             const ChannelFactoryConstPtr &channelFactory,
00096             const ContactFactoryConstPtr &contactFactory);
00097 
00098     virtual ~Connection();
00099 
00100     ChannelFactoryConstPtr channelFactory() const;
00101     ContactFactoryConstPtr contactFactory() const;
00102 
00103     QString cmName() const;
00104     QString protocolName() const;
00105 
00106     Status status() const;
00107     ConnectionStatusReason statusReason() const;
00108 
00109     class ErrorDetails
00110     {
00111         public:
00112             ErrorDetails();
00113             ErrorDetails(const QVariantMap &details);
00114             ErrorDetails(const ErrorDetails &other);
00115             ~ErrorDetails();
00116 
00117             ErrorDetails &operator=(const ErrorDetails &other);
00118 
00119             bool isValid() const { return mPriv.constData() != 0; }
00120 
00121             bool hasDebugMessage() const
00122             {
00123                 return allDetails().contains(QLatin1String("debug-message"));
00124             }
00125 
00126             QString debugMessage() const
00127             {
00128                 return qdbus_cast<QString>(allDetails().value(QLatin1String("debug-message")));
00129             }
00130 
00131 #if 0
00132             /*
00133              * TODO: these are actually specified in a draft interface only. Probably shouldn't
00134              * include them yet.
00135              */
00136             bool hasExpectedHostname() const
00137             {
00138                 return allDetails().contains(QLatin1String("expected-hostname"));
00139             }
00140 
00141             QString expectedHostname() const
00142             {
00143                 return qdbus_cast<QString>(allDetails().value(QLatin1String("expected-hostname")));
00144             }
00145 
00146             bool hasCertificateHostname() const
00147             {
00148                 return allDetails().contains(QLatin1String("certificate-hostname"));
00149             }
00150 
00151             QString certificateHostname() const
00152             {
00153                 return qdbus_cast<QString>(allDetails().value(QLatin1String("certificate-hostname")));
00154             }
00155 #endif
00156 
00157             QVariantMap allDetails() const;
00158 
00159         private:
00160             friend class Connection;
00161 
00162             struct Private;
00163             friend struct Private;
00164             QSharedDataPointer<Private> mPriv;
00165     };
00166 
00167     const ErrorDetails &errorDetails() const;
00168 
00169     uint selfHandle() const;
00170     ContactPtr selfContact() const;
00171 
00172     SimpleStatusSpecMap allowedPresenceStatuses() const;
00173     PendingOperation *setSelfPresence(const QString &status, const QString &statusMessage);
00174 
00175     CurrencyAmount accountBalance() const;
00176 
00177     ConnectionCapabilities *capabilities() const;
00178 
00179     PendingChannel *createChannel(const QVariantMap &request);
00180     PendingChannel *ensureChannel(const QVariantMap &request);
00181 
00182     PendingReady *requestConnect(const Features &requestedFeatures = Features());
00183     PendingOperation *requestDisconnect();
00184 
00185     PendingHandles *requestHandles(uint handleType, const QStringList &names);
00186     PendingHandles *referenceHandles(uint handleType, const UIntList &handles);
00187 
00188     PendingContactAttributes *contactAttributes(const UIntList &handles,
00189             const QStringList &interfaces, bool reference = true);
00190     QStringList contactAttributeInterfaces() const;
00191     ContactManager *contactManager() const;
00192 
00193     TELEPATHY_QT4_DEPRECATED inline Client::DBus::PropertiesInterface *propertiesInterface() const
00194     {
00195         return optionalInterface<Client::DBus::PropertiesInterface>(BypassInterfaceCheck);
00196     }
00197 
00198     TELEPATHY_QT4_DEPRECATED inline Client::ConnectionInterfaceAliasingInterface *aliasingInterface(
00199             InterfaceSupportedChecking check = CheckInterfaceSupported) const
00200     {
00201         return optionalInterface<Client::ConnectionInterfaceAliasingInterface>(check);
00202     }
00203 
00204     TELEPATHY_QT4_DEPRECATED inline Client::ConnectionInterfaceAnonymityInterface *anonymityInterface(
00205             InterfaceSupportedChecking check = CheckInterfaceSupported) const
00206     {
00207         return optionalInterface<Client::ConnectionInterfaceAnonymityInterface>(check);
00208     }
00209 
00210     TELEPATHY_QT4_DEPRECATED inline Client::ConnectionInterfaceAvatarsInterface *avatarsInterface(
00211             InterfaceSupportedChecking check = CheckInterfaceSupported) const
00212     {
00213         return optionalInterface<Client::ConnectionInterfaceAvatarsInterface>(check);
00214     }
00215 
00216     TELEPATHY_QT4_DEPRECATED inline Client::ConnectionInterfaceCapabilitiesInterface *capabilitiesInterface(
00217             InterfaceSupportedChecking check = CheckInterfaceSupported) const
00218     {
00219         return optionalInterface<Client::ConnectionInterfaceCapabilitiesInterface>(check);
00220     }
00221 
00222     TELEPATHY_QT4_DEPRECATED inline Client::ConnectionInterfaceClientTypesInterface *clientTypesInterface(
00223             InterfaceSupportedChecking check = CheckInterfaceSupported) const
00224     {
00225         return optionalInterface<Client::ConnectionInterfaceClientTypesInterface>(check);
00226     }
00227 
00228     TELEPATHY_QT4_DEPRECATED inline Client::ConnectionInterfaceContactCapabilitiesInterface *contactCapabilitiesInterface(
00229              InterfaceSupportedChecking check = CheckInterfaceSupported) const
00230     {
00231         return optionalInterface<Client::ConnectionInterfaceContactCapabilitiesInterface>(check);
00232     }
00233 
00234     TELEPATHY_QT4_DEPRECATED inline Client::ConnectionInterfaceContactGroupsInterface *contactGroupsInterface(
00235             InterfaceSupportedChecking check = CheckInterfaceSupported) const
00236     {
00237         return optionalInterface<Client::ConnectionInterfaceContactGroupsInterface>(check);
00238     }
00239 
00240     TELEPATHY_QT4_DEPRECATED inline Client::ConnectionInterfaceContactInfoInterface *contactInfoInterface(
00241             InterfaceSupportedChecking check = CheckInterfaceSupported) const
00242     {
00243         return optionalInterface<Client::ConnectionInterfaceContactInfoInterface>(check);
00244     }
00245 
00246     TELEPATHY_QT4_DEPRECATED inline Client::ConnectionInterfaceContactListInterface *contactListInterface(
00247             InterfaceSupportedChecking check = CheckInterfaceSupported) const
00248     {
00249         return optionalInterface<Client::ConnectionInterfaceContactListInterface>(check);
00250     }
00251 
00252     TELEPATHY_QT4_DEPRECATED inline Client::ConnectionInterfaceLocationInterface *locationInterface(
00253             InterfaceSupportedChecking check = CheckInterfaceSupported) const
00254     {
00255         return optionalInterface<Client::ConnectionInterfaceLocationInterface>(check);
00256     }
00257 
00258     TELEPATHY_QT4_DEPRECATED inline Client::ConnectionInterfacePresenceInterface *presenceInterface(
00259             InterfaceSupportedChecking check = CheckInterfaceSupported) const
00260     {
00261         return optionalInterface<Client::ConnectionInterfacePresenceInterface>(check);
00262     }
00263 
00264     TELEPATHY_QT4_DEPRECATED inline Client::ConnectionInterfacePowerSavingInterface *powerSavingInterface(
00265             InterfaceSupportedChecking check = CheckInterfaceSupported) const
00266     {
00267         return optionalInterface<Client::ConnectionInterfacePowerSavingInterface>(check);
00268     }
00269 
00270     TELEPATHY_QT4_DEPRECATED inline Client::ConnectionInterfaceServicePointInterface *servicePointInterface(
00271             InterfaceSupportedChecking check = CheckInterfaceSupported) const
00272     {
00273         return optionalInterface<Client::ConnectionInterfaceServicePointInterface>(check);
00274     }
00275 
00276     TELEPATHY_QT4_DEPRECATED inline Client::ConnectionInterfaceSimplePresenceInterface *simplePresenceInterface(
00277             InterfaceSupportedChecking check = CheckInterfaceSupported) const
00278     {
00279         return optionalInterface<Client::ConnectionInterfaceSimplePresenceInterface>(check);
00280     }
00281 
00282     TELEPATHY_QT4_DEPRECATED inline Client::ConnectionInterfaceRequestsInterface *requestsInterface(
00283             InterfaceSupportedChecking check = CheckInterfaceSupported) const
00284     {
00285         return optionalInterface<Client::ConnectionInterfaceRequestsInterface>(check);
00286     }
00287 
00288     TELEPATHY_QT4_DEPRECATED inline Client::ConnectionInterfaceBalanceInterface *balanceInterface(
00289             InterfaceSupportedChecking check = CheckInterfaceSupported) const
00290     {
00291         return optionalInterface<Client::ConnectionInterfaceBalanceInterface>(check);
00292     }
00293 
00294     TELEPATHY_QT4_DEPRECATED inline Client::ConnectionInterfaceCellularInterface *cellularInterface(
00295             InterfaceSupportedChecking check = CheckInterfaceSupported) const
00296     {
00297         return optionalInterface<Client::ConnectionInterfaceCellularInterface>(check);
00298     }
00299 
00300 Q_SIGNALS:
00301     void statusChanged(Tp::Connection::Status newStatus);
00302     // FIXME: (API/ABI break) Remove statusChanged(status, reason) in favor of statusChanged(status)
00303     void statusChanged(Tp::Connection::Status newStatus, Tp::ConnectionStatusReason newStatusReason);
00304 
00305     void selfHandleChanged(uint newHandle);
00306     // FIXME: might not need this when Renaming is fixed and mapped to Contacts
00307     void selfContactChanged();
00308 
00309     void accountBalanceChanged(const Tp::CurrencyAmount &accountBalance);
00310 
00311 protected:
00312     TELEPATHY_QT4_DEPRECATED Connection(const QString &busName, const QString &objectPath);
00313     TELEPATHY_QT4_DEPRECATED Connection(const QDBusConnection &bus, const QString &busName,
00314             const QString &objectPath);
00315 
00316     Connection(const QDBusConnection &bus, const QString &busName,
00317             const QString &objectPath,
00318             const ChannelFactoryConstPtr &channelFactory,
00319             const ContactFactoryConstPtr &contactFactory);
00320 
00321     Client::ConnectionInterface *baseInterface() const;
00322 
00323     // FIXME: (API/ABI break) Remove connectNotify
00324     void connectNotify(const char *);
00325 
00326 private Q_SLOTS:
00327     void onStatusReady(uint status);
00328     void onStatusChanged(uint status, uint reason);
00329     void onConnectionError(const QString &error, const QVariantMap &details);
00330     void gotMainProperties(QDBusPendingCallWatcher *watcher);
00331     void gotStatus(QDBusPendingCallWatcher *watcher);
00332     void gotInterfaces(QDBusPendingCallWatcher *watcher);
00333     void gotSelfHandle(QDBusPendingCallWatcher *watcher);
00334     void gotCapabilities(QDBusPendingCallWatcher *watcher);
00335     void gotContactAttributeInterfaces(QDBusPendingCallWatcher *watcher);
00336     void gotSimpleStatuses(QDBusPendingCallWatcher *watcher);
00337     void gotSelfContact(Tp::PendingOperation *op);
00338     void gotContactListsHandles(Tp::PendingOperation *op);
00339     void gotContactListChannel(Tp::PendingOperation *op);
00340     void contactListChannelReady();
00341     void onNewChannels(const Tp::ChannelDetailsList &channelDetailsList);
00342     void onContactListGroupChannelReady(Tp::PendingOperation *op);
00343     void gotChannels(QDBusPendingCallWatcher *watcher);
00344 
00345     void doReleaseSweep(uint type);
00346 
00347     void onSelfHandleChanged(uint);
00348 
00349     void gotBalance(QDBusPendingCallWatcher *watcher);
00350     void onBalanceChanged(const Tp::CurrencyAmount &);
00351 
00352 private:
00353     class PendingConnect;
00354     friend class PendingChannel;
00355     friend class PendingConnect;
00356     friend class PendingContactAttributes;
00357     friend class PendingContacts;
00358     friend class PendingHandles;
00359     friend class ReferencedHandles;
00360 
00361     void refHandle(uint type, uint handle);
00362     void unrefHandle(uint type, uint handle);
00363     void handleRequestLanded(uint type);
00364 
00365     struct Private;
00366     friend struct Private;
00367     Private *mPriv;
00368 };
00369 
00370 } // Tp
00371 
00372 Q_DECLARE_METATYPE(Tp::Connection::ErrorDetails);
00373 
00374 #endif