kopete/libkopete/kopeteblacklister.h

   1 /*
   2     kopeteblacklister.h - Kopete BlackLister
   3
   4     Copyright (c) 2004     by Roie Kerstein        <sf_kersteinroie@bezeqint.net>
   5
   6     *************************************************************************
   7     *                                                                       *
   8     * This library is free software; you can redistribute it and/or         *
   9     * modify it under the terms of the GNU Lesser General Public            *
  10     * License as published by the Free Software Foundation; either          *
  11     * version 2 of the License, or (at your option) any later version.      *
  12     *                                                                       *
  13     *************************************************************************
  14 */
  15
  16 #ifndef KOPETEBLACKLISTER_H
  17 #define KOPETEBLACKLISTER_H
  18
  19 #include <QtCore/QObject>
  20
  21 namespace Kopete
  22 {
  23
  24 class Contact;
  25
  26 /**
  27  * @brief Manages the list of blacklisted contacts for an account
  28  *
  29  * This class manages the list of contacts the user wishes
  30  * to ignore permanently. In order to use the this class, there is no need to
  31  * create an instance. Use the @ref Kopete::Account::blackLister() instead.
  32  *
  33  * Keep in mind that this class does not discard messages from blocked
  34  * users - It only manages the list. It is the up to the protocol to
  35  * check whether a user is blocked, and act accordingly. A protocol may
  36  * re-implement @ref Kopete::Account::block() and @ref Kopete::Account::unblock()
  37  * and use @ref Kopete::Account::blackLister() as a persistent list manager
  38  * only, or connect the signals @ref contactAdded() and @ref contactRemoved()
  39  * to its slots.
  40  *
  41  * @sa Kopete::Account::block() Kopete::Account::unblock()
  42  *
  43  * @author Roie Kerstein <sf_kersteinroie@bezeqint.net>
  44  */
  45 class BlackLister : public QObject
  46 {
  47         Q_OBJECT
  48
  49 public:
  50         /**
  51          * Create an instance, and read the blacklist from disk if it exists.
  52          * @param protocolId is the ID of the protocol owning accountId
  53          * @param accountId is the ID of the owning Account.
  54          * @param parent The QObject parent for this class.
  55          * @param name The QObject name for this class.
  56          */
  57         BlackLister( const QString &protocolId, const QString &accountId, QObject *parent = 0 );
  58         ~BlackLister();
  59
  60         /**
  61          * \return @c true if @p contact is blocked, @c false otherwise.
  62          */
  63         bool isBlocked( Contact *contact );
  64
  65         /**
  66          * \return @c true if the contact with ID @p contactId is blocked, @c false otherwise.
  67          */
  68         bool isBlocked( const QString &contactId );
  69
  70 public slots:
  71         /**
  72          * Add a contact to the blacklist.
  73          *
  74          * This function emits the @ref contactAdded() signal.
  75          * @param contactId is the ID of the contact to be added to the list.
  76          */
  77         void addContact( const QString &contactId );
  78
  79         /**
  80          * @overload
  81          */
  82         void addContact( Contact *contact );
  83
  84         /**
  85          * \brief Remove a contact from the blacklist.
  86          *
  87          * Removes the contact from the blacklist.
  88          * This function emits the @ref contactRemoved() signal.
  89          * @param contact is the contact to be removed from the list.
  90          */
  91         void removeContact( Contact *contact );
  92
  93         /**
  94          * @overload
  95          */
  96         void removeContact( const QString &contactId );
  97
  98 signals:
  99         /**
 100          * \brief A new contact has been added to the list
 101          *
 102          * Connect to this signal if you want to perform additional actions,
 103          * and you prefer not to derive from this class.
 104          */
 105         void contactAdded( const QString &contactId );
 106
 107         /**
 108          * \brief A contact has been removed from the list
 109          *
 110          * Connect to this signal if you want to perform additional actions,
 111          * and you prefer not to derive from this class.
 112          */
 113         void contactRemoved( const QString &contactId );
 114
 115 private:
 116         void saveToDisk();
 117
 118         class Private;
 119         Private * const d;
 120 };
 121
 122 }
 123
 124 #endif