kopete/libkopete/kopetecontact.h

   1 /*
   2     kopetecontact.h - Kopete Contact
   3
   4     Copyright (c) 2002-2004 by Duncan Mac-Vicar Prett <duncan@kde.org>
   5     Copyright (c) 2002-2003 by Martijn Klingens       <klingens@kde.org>
   6     Copyright (c) 2002-2004 by Olivier Goffart        <ogoffart@kde.org>
   7
   8     Kopete    (c) 2002-2004 by the Kopete developers  <kopete-devel@kde.org>
   9
  10     *************************************************************************
  11     *                                                                       *
  12     * This library is free software; you can redistribute it and/or         *
  13     * modify it under the terms of the GNU Lesser General Public            *
  14     * License as published by the Free Software Foundation; either          *
  15     * version 2 of the License, or (at your option) any later version.      *
  16     *                                                                       *
  17     *************************************************************************
  18 */
  19
  20 #ifndef KOPETECONTACT_H
  21 #define KOPETECONTACT_H
  22
  23 #include "kopetecontactlistelement.h"
  24 #include "kopetepropertycontainer.h"
  25
  26 #include <kurl.h>
  27 #include <kdemacros.h>
  28 #include "kopeteglobal.h"
  29
  30 #include "kopete_export.h"
  31
  32 class KMenu;
  33 class KAction;
  34
  35 namespace Kopete
  36 {
  37
  38 class Group;
  39 class MetaContact;
  40 class ChatSession;
  41 class OnlineStatus;
  42 class Plugin;
  43 class Protocol;
  44 class Account;
  45 class StatusMessage;
  46
  47 typedef QList<Group *> GroupList;
  48
  49 /**
  50  * @author Duncan Mac-Vicar P. <duncan@kde.org>
  51  * @author Martijn Klingens <klingens@kde.org>
  52  * @author Olivier Goffart <ogoffart@kde.org>
  53  *
  54  * This class abstracts a generic contact
  55  * Use it for inserting contacts in the contact list for example.
  56  */
  57 class KOPETE_EXPORT Contact
  58         : public ContactListElement
  59 {
  60         Q_OBJECT
  61
  62         Q_ENUMS( CanCreateFlags )
  63         Q_PROPERTY( QString formattedName READ formattedName )
  64         Q_PROPERTY( QString formattedIdleTime READ formattedIdleTime )
  65         Q_PROPERTY( bool isOnline READ isOnline )
  66         Q_PROPERTY( bool fileCapable READ isFileCapable WRITE setFileCapable )
  67         Q_PROPERTY( bool canAcceptFiles READ canAcceptFiles )
  68         //Q_PROPERTY( bool isReachable READ isReachable )
  69         Q_PROPERTY( QString contactId READ contactId )
  70         Q_PROPERTY( QString icon READ icon WRITE setIcon )
  71         Q_PROPERTY( QString toolTip READ toolTip )
  72         Q_PROPERTY( QString nickName READ nickName WRITE setNickName )
  73         //Q_PROPERTY( unsigned long idleTime READ idleTime WRITE setIdleTime )
  74
  75 public:
  76         /**
  77          * used in @ref sync()
  78          */
  79         enum Changed{ MovedBetweenGroup = 0x01, ///< the contact has been moved between groups
  80                       DisplayNameChanged = 0x02 ///< the displayname of the contact changed
  81         };
  82
  83         /**
  84          * \brief Create new contact.
  85          *
  86          * <b>The parent MetaContact must not be NULL</b>
  87          *
  88          * \note id is required to be unique per protocol and per account.
  89          * Across those boundaries ids may occur multiple times.
  90          * The id is solely for comparing items safely (using pointers is
  91          * more crash-prone). DO NOT assume anything regarding the id's
  92          * value! Even if it may look like an ICQ UIN or an MSN passport,
  93          * this is undefined and may change at any time!
  94          *
  95          * @param account is the parent account. this constructor automatically register the contact to the account
  96          * @param id is the Contact's unique Id (mostly the user's login)
  97          * @param parent is the parent @ref MetaContact this Contact is part of
  98          * @param icon is an optional icon
  99          */
 100         Contact( Account *account, const QString &id, MetaContact *parent,
 101                 const QString &icon = QString() );
 102
 103         ~Contact();
 104
 105         /**
 106          * \brief Get the metacontact for this contact
 107          * @return The MetaContact object for this contact
 108          */
 109         MetaContact *metaContact() const;
 110
 111
 112         /**
 113          * \brief Get the unique id that identifies a contact.
 114          *
 115          * \note Id is required to be unique per protocol and per account.
 116          * Across those boundaries ids may occur multiple times.
 117          * The id is solely for comparing items safely (using pointers is
 118          * more crash-prone). DO NOT assume anything regarding the id's
 119          * value! Even if it may look like an ICQ UIN or an MSN passport,
 120          * this is undefined and may change at any time!
 121          *
 122          * @return The unique id of the contact
 123          */
 124         QString contactId() const;
 125
 126         /**
 127          * \brief Get the protocol that the contact belongs to.
 128          *
 129          * simply return account()->protocol()
 130          *
 131          * @return the contact's protocol
 132          */
 133         Protocol* protocol() const;
 134
 135         /**
 136          * \brief Get the account that this contact belongs to
 137          *
 138          * @return the Account object for this contact
 139          */
 140         Account* account() const;
 141
 142         /**
 143          * \brief Move this contact to a new MetaContact.
 144          * This basically reparents the contact and updates the internal
 145          * data structures.
 146          * If the old contact is going to be empty, the old contact will be removed.
 147          *
 148          * @param m The new MetaContact to move this contact to
 149          */
 150         void setMetaContact(MetaContact *m);
 151
 152         /**
 153          * @brief Get whether this contact is online.
 154          * @return @c true if the contact is online, @c false otherwise.
 155          */
 156         bool isOnline() const;
 157
 158         /**
 159          * \brief Get whether this contact can receive messages
 160          *
 161          * Used in determining if the contact is able to
 162          * receive messages.  This function must be defined by child classes
 163          *
 164          * @return true if the contact can be reached
 165          * @return false if the contact cannot be reached
 166          */
 167         // FIXME: After KDE 3.2 we should split this into a public, NON-virtual
 168         //        isReachable() accessor that checks for account->isConnected()
 169         //        and then calls a new virtual method that does the
 170         //        protocol-specific work, like 'doIsUnreachable' or so - Martijn
 171         //
 172         //FIXME: Can this be made const please? - JK
 173         virtual bool isReachable();
 174
 175         /**
 176          * @brief Serialize the contact for storage in the contact list.
 177          *
 178          * The provided serializedData contain the contact id in the field
 179          * "contactId". If you don't like this, or don't want to
 180          * store these fields at all,
 181          * you are free to remove them from the list.
 182          *
 183          * Most plugins don't need more than these fields, so they only need
 184          * to set the address book fields themselves. If you have nothing to
 185          * save at all you can clear the QMap, an empty map is treated as
 186          * 'nothing to save'.
 187          *
 188          * The provided addressBookFields QMap contains the index field as
 189          * marked with @ref Plugin::addAddressBookField() with the
 190          * contact id as value. If no index field is available the QMap is
 191          * simply passed as an empty map.
 192          *
 193          * @sa Protocol::deserializeContact
 194          */
 195         virtual void serialize( QMap<QString, QString> &serializedData, QMap<QString, QString> &addressBookData );
 196
 197         /**
 198          * @brief Get the online status of the contact
 199          * @return the online status of the contact
 200          */
 201         OnlineStatus onlineStatus() const;
 202
 203         /**
 204          * \brief Set the contact's online status
 205          */
 206         void setOnlineStatus(const OnlineStatus &status);
 207
 208         /**
 209          * @brief Get the current status message of the contact.
 210          * @return the status in a Kopete::StatusMessage.
 211          */
 212         Kopete::StatusMessage statusMessage() const;
 213         /**
 214          * @brief Set the contact's status message.
 215          * It sets also the "awayMessage" property so you don't need to do it.
 216          */
 217         void setStatusMessage(const Kopete::StatusMessage &statusMessage);
 218
 219         /**
 220          * \brief Get the set of custom menu items for this contact
 221          *
 222          * Returns a set of custom menu items for the context menu
 223          * which is displayed in showContextMenu (private).  Protocols
 224          * should use this to add protocol-specific actions to the
 225          * popup menu. Kopete take care of the deletion of the action collection.
 226          * Actions should have the collection as parent.
 227          *
 228          * @return Collection of menu items to be show on the context menu
 229          * @todo if possible, try to use KXMLGUI
 230          */
 231         virtual QList<KAction *> *customContextMenuActions();
 232
 233         /**
 234          * @todo  What is this function for ?
 235          */
 236         virtual QList<KAction *> *customContextMenuActions( ChatSession *manager );
 237
 238         /**
 239          * @brief Get the Context Menu for this contact
 240          *
 241          * This menu includes generic actions common to each protocol, and action defined in
 242          * @ref customContextMenuActions()
 243          */
 244         KMenu *popupMenu( ChatSession *manager = 0L );
 245
 246         /**
 247          * \brief Get whether or not this contact is capable of file transfers
 248          *
 249          *
 250          * \see setFileCapable()
 251          * \return true if the protocol for this contact is capable of file transfers
 252          * \return false if the protocol for this contact is not capable of file transfers
 253          *
 254          * @todo have a capabilioties. or move to protocol capabilities
 255          */
 256         bool isFileCapable() const;
 257
 258         /**
 259          * \brief Set the file transfer capability of this contact
 260          *
 261          * \param filecap The new file transfer capability setting
 262          * @todo have a capabilioties. or move to protocol capabilities
 263          */
 264         void setFileCapable( bool filecap );
 265
 266         /**
 267          * \brief Get whether or not this contact can accept file transfers
 268          *
 269          * This function checks to make sure that the contact is online as well as
 270          * capable of sending files.
 271          * \see isReachable()
 272          * @return true if this contact is online and is capable of receiving files
 273          * @todo have a capabilioties. or move to protocol capabilities
 274          */
 275         bool canAcceptFiles() const;
 276
 277         enum CanCreateFlags {  CannotCreate=false , CanCreate=true  };
 278
 279         /**
 280          * Returns the primary message manager affiliated with this contact
 281          * Although a contact can have more than one active message manager
 282          * (as is the case with MSN at least), only one message manager will
 283          * ever be the contacts "primary" message manager.. aka the 1 on 1 chat.
 284          * This function should always return that instance.
 285          *
 286          * @param canCreate If a new message manager can be created in addition
 287          * to any existing managers. Currently, this is only set to true when
 288          * a chat is initiated by the user by clicking the contact list.
 289          */
 290         virtual ChatSession * manager( CanCreateFlags canCreate = CannotCreate ) =0;
 291
 292         /**
 293          * Returns the name of the icon to use for this contact
 294          *  If null, the protocol icon need to be used.
 295          * The icon is not colored, nor has the status icon overloaded
 296          */
 297         QString& icon() const;
 298
 299         /**
 300          * @brief Change the icon to use for this contact
 301          * If you don't want to have the protocol icon as icon for this contact, you may set
 302          * another icon.  The icon doesn't need to be colored with the account icon as this operation
 303          * will be performed later.
 304          *
 305          * if you want to go back to the protocol icon, set a null string.
 306          */
 307         void setIcon( const QString& icon );
 308
 309         /**
 310          * \brief Get the time (in seconds) this contact has been idle
 311          * It will return the time set in @ref setIdleTime() with an addition of the time
 312          * since you set this last time
 313          * @return time this contact has been idle for, in seconds
 314          //
 315          // FIXME: Can we make this just 'unsigned long' ? QT Properties can't handle
 316          // 'unsigned long int'
 317          */
 318         virtual unsigned long int idleTime() const;
 319
 320         /**
 321          * \brief Set the current idle time in seconds.
 322          * Kopete will automatically calculate the time in @ref idleTime
 323          * except if you set 0.
 324          //
 325          // FIXME: Can we make this just 'unsigned long' ? QT Properties can't handle
 326          // 'unsigned long int'
 327          */
 328         void setIdleTime(unsigned long int);
 329
 330         /**
 331          * \brief Convenience method to set the nickName property to the specified value
 332          * @param name The nickname to set
 333          */
 334         void setNickName( const QString &name );
 335
 336         /**
 337          * \brief Convenience method to retrieve the nickName property.
 338          *
 339          * This method will return the contactId if there has been no nickName property set
 340          */
 341         QString nickName() const;
 342
 343         /**
 344          * \brief Get the tooltip for this contact
 345          * Makes use of formattedName() and formattedIdleTime().
 346          * \return an RTF tooltip depending on Kopete::AppearanceSettings settings
 347          **/
 348         QString toolTip() const;
 349
 350         /**
 351          * Returns a formatted string of "firstName" and/or "lastName" properties
 352          * if present.
 353          * Suitable for GUI display
 354          **/
 355         QString formattedName() const;
 356
 357         /**
 358          * Returns a formatted string of idleTime().
 359          * Suitable for GUI display
 360          **/
 361         QString formattedIdleTime() const;
 362
 363         /**
 364          * @brief Convience method to set the photo property
 365          * @param photoPath Local path to the photo
 366          */
 367         void setPhoto(const QString &photoPath);
 368
 369 public slots:
 370         /**
 371          * This should typically pop up a KopeteChatWindow
 372          */
 373         void startChat();
 374
 375         /**
 376          * Pops up an email type window
 377          */
 378         void sendMessage();
 379
 380         /**
 381          * The user clicked on the contact, do the default action
 382          */
 383         void execute();
 384
 385         /**
 386          * Changes the MetaContact that this contact is a part of.  This function
 387          * is called by the KAction changeMetaContact that is part of the context
 388          * menu.
 389          */
 390         void changeMetaContact();
 391         /**
 392          * Method to retrieve user information.  Should be implemented by
 393          * the protocols, and popup some sort of dialog box
 394          *
 395          * reimplement it to show the informlation
 396          * @todo rename and make it pure virtual
 397          */
 398         virtual void slotUserInfo() {}
 399
 400         /**
 401          * @brief Syncronise the server and the metacontact.
 402          * Protocols with server-side contact lists can implement this to
 403          * sync the server groups with the metaContact groups. Or the server alias if any.
 404          *
 405          * This method is called every time the metacontact has been moved or renamed.
 406          *
 407          * default implementation does nothing
 408          *
 409          * @param changed is a bitmask of the @ref Changed enum which say why the call to this function is done.
 410          */
 411         virtual void sync(unsigned int changed = 0xFF);
 412
 413         /**
 414          * @deprecated Use DeleteContactTask instead.
 415          * Method to delete a contact from the contact list,
 416          * should be implemented by protocol plugin to handle
 417          * protocol-specific actions required to delete a contact
 418          * (ie. messages to the server, etc)
 419          * the default implementation simply call deleteLater()
 420          */
 421         virtual KDE_DEPRECATED void deleteContact();
 422
 423         /**
 424          * This is the Contact level slot for sending files. It should be
 425          * implemented by all contacts which have the setFileCapable() flag set to
 426          * true. If the function is called through the GUI, no parameters are sent
 427          * and they take on default values (the file is chosen with a file open dialog)
 428          *
 429          * @param sourceURL The actual KUrl of the file you are sending
 430          * @param fileName (Optional) An alternate name for the file - what the
 431          * receiver will see
 432          * @param fileSize (Optional) Size of the file being sent. Used when sending
 433          * a nondeterminate
 434          *                file size (such as over  asocket
 435          */
 436         virtual void sendFile( const KUrl &sourceURL = KUrl(),
 437                                const QString &fileName = QString(), uint fileSize = 0L );
 438 private slots:
 439         /**
 440          * This add the contact totally in the list if it was a temporary contact
 441          */
 442         void slotAddContact();
 443
 444         /**
 445          * slot called when the action "delete" is called.
 446          */
 447         void slotDelete();
 448
 449         /**
 450          * slot called when the action "block" is called.
 451          */
 452         void slotBlock();
 453
 454         /**
 455          * slot called when the action "unblock" is called.
 456          */
 457         void slotUnblock();
 458
 459         /**
 460          * The account's isConnected has changed.
 461          */
 462         void slotAccountIsConnectedChanged();
 463 signals:
 464         /**
 465          * The contact's online status changed
 466          */
 467         void onlineStatusChanged( Kopete::Contact *contact,
 468                 const Kopete::OnlineStatus &status, const Kopete::OnlineStatus &oldStatus );
 469
 470         /**
 471          * The contact is about to be destroyed.
 472          * Called when entering the destructor. Useful for cleanup, since
 473          * metaContact() is still accessible at this point.
 474          *
 475          * @warning this signal is emit in the Contact destructor, so all
 476          * virtual method are not available
 477          */
 478         void contactDestroyed( Kopete::Contact *contact );
 479
 480         /**
 481          * The contact's idle state changed.
 482          * You need to emit this signal to update the view.
 483          * That mean when activity has been noticed
 484          */
 485         void idleStateChanged( Kopete::Contact *contact );
 486
 487         /**
 488          * \brief Emitted when the file transfer capability of this contact has changed
 489          */
 490         void canAcceptFilesChanged();
 491
 492 private:
 493         class Private;
 494         Private * const d;
 495
 496
 497 };
 498
 499
 500 } //END namespace Kopete
 501
 502 #endif
 503