src/core/storage.h

   1 /***************************************************************************
   2  *   Copyright (C) 2005-2015 by the Quassel Project                        *
   3  *   devel@quassel-irc.org                                                 *
   4  *                                                                         *
   5  *   This program is free software; you can redistribute it and/or modify  *
   6  *   it under the terms of the GNU General Public License as published by  *
   7  *   the Free Software Foundation; either version 2 of the License, or     *
   8  *   (at your option) version 3.                                           *
   9  *                                                                         *
  10  *   This program is distributed in the hope that it will be useful,       *
  11  *   but WITHOUT ANY WARRANTY; without even the implied warranty of        *
  12  *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the         *
  13  *   GNU General Public License for more details.                          *
  14  *                                                                         *
  15  *   You should have received a copy of the GNU General Public License     *
  16  *   along with this program; if not, write to the                         *
  17  *   Free Software Foundation, Inc.,                                       *
  18  *   51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.         *
  19  ***************************************************************************/
  20
  21 #ifndef STORAGE_H
  22 #define STORAGE_H
  23
  24 #include <QtCore>
  25
  26 #include "types.h"
  27 #include "coreidentity.h"
  28 #include "message.h"
  29 #include "network.h"
  30
  31 class Storage : public QObject
  32 {
  33     Q_OBJECT
  34
  35 public:
  36     Storage(QObject *parent = 0);
  37     virtual ~Storage() {};
  38
  39     enum State {
  40         IsReady,    // ready to go
  41         NeedsSetup, // need basic setup (ask the user for input)
  42         NotAvailable // remove the storage backend from the list of avaliable backends
  43     };
  44
  45     enum HashVersion {
  46         Sha1,
  47 #if QT_VERSION >= 0x050000
  48         Sha2_512,
  49         Latest=Sha2_512
  50 #else
  51         Latest=Sha1
  52 #endif
  53     };
  54
  55 public slots:
  56     /* General */
  57
  58     //! Check if the storage type is available.
  59     /** A storage subclass should return true if it can be successfully used, i.e. if all
  60      *  prerequisites are in place (e.g. we have an appropriate DB driver etc.).
  61      * \return True if and only if the storage class can be successfully used.
  62      */
  63     virtual bool isAvailable() const = 0;
  64
  65     //! Returns the display name of the storage backend
  66     /** \return A string that can be used by the client to name the storage backend */
  67     virtual QString displayName() const = 0;
  68
  69     //! Returns a description of this storage backend
  70     /** \return A string that can be displayed by the client to describe the storage backend */
  71     virtual QString description() const = 0;
  72
  73     //! Returns a list of properties required to use the storage backend
  74     virtual QStringList setupKeys() const = 0;
  75
  76     //! Returns a map where the keys are are properties to use the storage backend
  77     /*  the values are QVariants with default values */
  78     virtual QVariantMap setupDefaults() const = 0;
  79
  80     //! Setup the storage provider.
  81     /** This prepares the storage provider (e.g. create tables, etc.) for use within Quassel.
  82      *  \param settings   Hostname, port, username, password, ...
  83      *  \return True if and only if the storage provider was initialized successfully.
  84      */
  85     virtual bool setup(const QVariantMap &settings = QVariantMap()) = 0;
  86
  87     //! Initialize the storage provider
  88     /** \param settings   Hostname, port, username, password, ...
  89      *  \return the State the storage backend is now in (see Storage::State)
  90      */
  91     virtual State init(const QVariantMap &settings = QVariantMap()) = 0;
  92
  93     //! Makes temp data persistent
  94     /** This Method is periodically called by the Quassel Core to make temporary
  95      *  data persistant. This reduces the data loss drastically in the
  96      *  unlikely case of a Core crash.
  97      */
  98     virtual void sync() = 0;
  99
 100     // TODO: Add functions for configuring the backlog handling, i.e. defining auto-cleanup settings etc
 101
 102     /* User handling */
 103
 104     //! Add a new core user to the storage.
 105     /** \param user     The username of the new user
 106      *  \param password The cleartext password for the new user
 107      *  \return The new user's UserId
 108      */
 109     virtual UserId addUser(const QString &user, const QString &password) = 0;
 110
 111     //! Update a core user's password.
 112     /** \param user     The user's id
 113      *  \param password The user's new password
 114      *  \return true on success.
 115      */
 116     virtual bool updateUser(UserId user, const QString &password) = 0;
 117
 118     //! Rename a user
 119     /** \param user     The user's id
 120      *  \param newName  The user's new name
 121      */
 122     virtual void renameUser(UserId user, const QString &newName) = 0;
 123
 124     //! Validate a username with a given password.
 125     /** \param user     The username to validate
 126      *  \param password The user's alleged password
 127      *  \return A valid UserId if the password matches the username; 0 else
 128      */
 129     virtual UserId validateUser(const QString &user, const QString &password) = 0;
 130
 131     //! Check if a user with given username exists. Do not use for login purposes!
 132     /** \param username  The username to validate
 133      *  \return A valid UserId if the user exists; 0 else
 134      */
 135     virtual UserId getUserId(const QString &username) = 0;
 136
 137     //! Determine the UserId of the internal user
 138     /** \return A valid UserId if the password matches the username; 0 else
 139      */
 140     virtual UserId internalUser() = 0;
 141
 142     //! Remove a core user from storage.
 143     /** \param user     The userid to delete
 144      */
 145     virtual void delUser(UserId user) = 0;
 146
 147     //! Store a user setting persistently
 148     /**
 149      * \param userId       The users Id
 150      * \param settingName  The Name of the Setting
 151      * \param data         The Value
 152      */
 153     virtual void setUserSetting(UserId userId, const QString &settingName, const QVariant &data) = 0;
 154
 155     //! Retrieve a persistent user setting
 156     /**
 157      * \param userId       The users Id
 158      * \param settingName  The Name of the Setting
 159      * \param default      Value to return in case it's unset.
 160      * \return the Value of the Setting or the default value if it is unset.
 161      */
 162     virtual QVariant getUserSetting(UserId userId, const QString &settingName, const QVariant &data = QVariant()) = 0;
 163
 164     /* Identity handling */
 165     virtual IdentityId createIdentity(UserId user, CoreIdentity &identity) = 0;
 166     virtual bool updateIdentity(UserId user, const CoreIdentity &identity) = 0;
 167     virtual void removeIdentity(UserId user, IdentityId identityId) = 0;
 168     virtual QList<CoreIdentity> identities(UserId user) = 0;
 169
 170     /* Network handling */
 171
 172     //! Create a new Network in the storage backend and return it unique Id
 173     /** \param user        The core user who owns this network
 174      *  \param networkInfo The networkInfo holding the network definition
 175      *  \return the NetworkId of the newly created Network. Possibly invalid.
 176      */
 177     virtual NetworkId createNetwork(UserId user, const NetworkInfo &info) = 0;
 178
 179     //! Apply the changes to NetworkInfo info to the storage engine
 180     /**
 181      *  \param user        The core user
 182      *  \param networkInfo The Updated NetworkInfo
 183      *  \return true if successfull.
 184      */
 185     virtual bool updateNetwork(UserId user, const NetworkInfo &info) = 0;
 186
 187     //! Permanently remove a Network and all the data associated with it.
 188     /** \note This method is thredsafe.
 189      *
 190      *  \param user        The core user
 191      *  \param networkId   The network to delete
 192      *  \return true if successfull.
 193      */
 194     virtual bool removeNetwork(UserId user, const NetworkId &networkId) = 0;
 195
 196     //! Returns a list of all NetworkInfos for the given UserId user
 197     /** \note This method is thredsafe.
 198      *
 199      *  \param user        The core user
 200      *  \return QList<NetworkInfo>.
 201      */
 202     virtual QList<NetworkInfo> networks(UserId user) = 0;
 203
 204     //! Get a list of Networks to restore
 205     /** Return a list of networks the user was connected at the time of core shutdown
 206      *  \note This method is threadsafe.
 207      *
 208      *  \param user  The User Id in question
 209      */
 210     virtual QList<NetworkId> connectedNetworks(UserId user) = 0;
 211
 212     //! Update the connected state of a network
 213     /** \note This method is threadsafe
 214      *
 215      *  \param user        The Id of the networks owner
 216      *  \param networkId   The Id of the network
 217      *  \param isConnected whether the network is connected or not
 218      */
 219     virtual void setNetworkConnected(UserId user, const NetworkId &networkId, bool isConnected) = 0;
 220
 221     //! Get a hash of channels with their channel keys for a given network
 222     /** The keys are channel names and values are passwords (possibly empty)
 223      *  \note This method is threadsafe
 224      *
 225      *  \param user       The id of the networks owner
 226      *  \param networkId  The Id of the network
 227      */
 228     virtual QHash<QString, QString> persistentChannels(UserId user, const NetworkId &networkId) = 0;
 229
 230     //! Update the connected state of a channel
 231     /** \note This method is threadsafe
 232      *
 233      *  \param user       The Id of the networks owner
 234      *  \param networkId  The Id of the network
 235      *  \param channel    The name of the channel
 236      *  \param isJoined   whether the channel is connected or not
 237      */
 238     virtual void setChannelPersistent(UserId user, const NetworkId &networkId, const QString &channel, bool isJoined) = 0;
 239
 240     //! Update the key of a channel
 241     /** \note This method is threadsafe
 242      *
 243      *  \param user       The Id of the networks owner
 244      *  \param networkId  The Id of the network
 245      *  \param channel    The name of the channel
 246      *  \param key        The key of the channel (possibly empty)
 247      */
 248     virtual void setPersistentChannelKey(UserId user, const NetworkId &networkId, const QString &channel, const QString &key) = 0;
 249
 250     //! retrieve last known away message for session restore
 251     /** \note This method is threadsafe
 252      *
 253      *  \param user       The Id of the networks owner
 254      *  \param networkId  The Id of the network
 255      */
 256     virtual QString awayMessage(UserId user, NetworkId networkId) = 0;
 257
 258     //! Make away message persistent for session restore
 259     /** \note This method is threadsafe
 260      *
 261      *  \param user       The Id of the networks owner
 262      *  \param networkId  The Id of the network
 263      *  \param awayMsg    The current away message of own user
 264      */
 265     virtual void setAwayMessage(UserId user, NetworkId networkId, const QString &awayMsg) = 0;
 266
 267     //! retrieve last known user mode for session restore
 268     /** \note This method is threadsafe
 269      *
 270      *  \param user       The Id of the networks owner
 271      *  \param networkId  The Id of the network
 272      */
 273     virtual QString userModes(UserId user, NetworkId networkId) = 0;
 274
 275     //! Make our user modes persistent for session restore
 276     /** \note This method is threadsafe
 277      *
 278      *  \param user       The Id of the networks owner
 279      *  \param networkId  The Id of the network
 280      *  \param userModes  The current user modes of own user
 281      */
 282     virtual void setUserModes(UserId user, NetworkId networkId, const QString &userModes) = 0;
 283
 284     /* Buffer handling */
 285
 286     //! Get the unique BufferInfo for the given combination of network and buffername for a user.
 287     /** \param user      The core user who owns this buffername
 288      *  \param networkId The network id
 289      *  \param type      The type of the buffer (StatusBuffer, Channel, etc.)
 290      *  \param buffer  The buffer name (if empty, the net's status buffer is returned)
 291      *  \param create    Whether or not the buffer should be created if it doesnt exist
 292      *  \return The BufferInfo corresponding to the given network and buffer name, or an invalid BufferInfo if not found
 293      */
 294     virtual BufferInfo bufferInfo(UserId user, const NetworkId &networkId, BufferInfo::Type type, const QString &buffer = "", bool create = true) = 0;
 295
 296     //! Get the unique BufferInfo for a bufferId
 297     /** \param user      The core user who owns this buffername
 298      *  \param bufferId  The id of the buffer
 299      *  \return The BufferInfo corresponding to the given buffer id, or an invalid BufferInfo if not found.
 300      */
 301     virtual BufferInfo getBufferInfo(UserId user, const BufferId &bufferId) = 0;
 302
 303     //! Request a list of all buffers known to a user.
 304     /** This method is used to get a list of all buffers we have stored a backlog from.
 305      *  \param user  The user whose buffers we request
 306      *  \return A list of the BufferInfos for all buffers as requested
 307      */
 308     virtual QList<BufferInfo> requestBuffers(UserId user) = 0;
 309
 310     //! Request a list of BufferIds for a given NetworkId
 311     /** \note This method is threadsafe.
 312      *
 313      *  \param user  The user whose buffers we request
 314      *  \param networkId  The NetworkId of the network in question
 315      *  \return List of BufferIds belonging to the Network
 316      */
 317     virtual QList<BufferId> requestBufferIdsForNetwork(UserId user, NetworkId networkId) = 0;
 318
 319     //! Remove permanently a buffer and it's content from the storage backend
 320     /** This call cannot be reverted!
 321      *  \param user      The user who is the owner of the buffer
 322      *  \param bufferId  The bufferId
 323      *  \return true if successfull
 324      */
 325     virtual bool removeBuffer(const UserId &user, const BufferId &bufferId) = 0;
 326
 327     //! Rename a Buffer
 328     /** \note This method is threadsafe.
 329      *  \param user      The id of the buffer owner
 330      *  \param bufferId  The bufferId
 331      *  \param newName   The new name of the buffer
 332      *  \return true if successfull
 333      */
 334     virtual bool renameBuffer(const UserId &user, const BufferId &bufferId, const QString &newName) = 0;
 335
 336     //! Merge the content of two Buffers permanently. This cannot be reversed!
 337     /** \note This method is threadsafe.
 338      *  \param user      The id of the buffer owner
 339      *  \param bufferId1 The bufferId of the remaining buffer
 340      *  \param bufferId2 The buffer that is about to be removed
 341      *  \return true if successfull
 342      */
 343     virtual bool mergeBuffersPermanently(const UserId &user, const BufferId &bufferId1, const BufferId &bufferId2) = 0;
 344
 345     //! Update the LastSeenDate for a Buffer
 346     /** This Method is used to make the LastSeenDate of a Buffer persistent
 347      * \param user      The Owner of that Buffer
 348      * \param bufferId  The buffer id
 349      * \param MsgId     The Message id of the message that has been just seen
 350      */
 351     virtual void setBufferLastSeenMsg(UserId user, const BufferId &bufferId, const MsgId &msgId) = 0;
 352
 353     //! Get a Hash of all last seen message ids
 354     /** This Method is called when the Quassel Core is started to restore the lastSeenMsgIds
 355      * \param user      The Owner of the buffers
 356      */
 357     virtual QHash<BufferId, MsgId> bufferLastSeenMsgIds(UserId user) = 0;
 358
 359     //! Update the MarkerLineMsgId for a Buffer
 360     /** This Method is used to make the marker line position of a Buffer persistent
 361      *  \note This method is threadsafe.
 362      *
 363      * \param user      The Owner of that Buffer
 364      * \param bufferId  The buffer id
 365      * \param MsgId     The Message id where the marker line should be placed
 366      */
 367     virtual void setBufferMarkerLineMsg(UserId user, const BufferId &bufferId, const MsgId &msgId) = 0;
 368
 369     //! Get a Hash of all marker line message ids
 370     /** This Method is called when the Quassel Core is started to restore the MarkerLineMsgIds
 371      *  \note This method is threadsafe.
 372      *
 373      * \param user      The Owner of the buffers
 374      */
 375     virtual QHash<BufferId, MsgId> bufferMarkerLineMsgIds(UserId user) = 0;
 376
 377     /* Message handling */
 378
 379     //! Store a Message in the storage backend and set its unique Id.
 380     /** \param msg  The message object to be stored
 381      *  \return true on success
 382      */
 383     virtual bool logMessage(Message &msg) = 0;
 384
 385     //! Store a list of Messages in the storage backend and set their unique Id.
 386     /** \param msgs The list message objects to be stored
 387      *  \return true on success
 388      */
 389     virtual bool logMessages(MessageList &msgs) = 0;
 390
 391     //! Request a certain number messages stored in a given buffer.
 392     /** \param buffer   The buffer we request messages from
 393      *  \param first    if != -1 return only messages with a MsgId >= first
 394      *  \param last     if != -1 return only messages with a MsgId < last
 395      *  \param limit    if != -1 limit the returned list to a max of \limit entries
 396      *  \return The requested list of messages
 397      */
 398     virtual QList<Message> requestMsgs(UserId user, BufferId bufferId, MsgId first = -1, MsgId last = -1, int limit = -1) = 0;
 399
 400     //! Request a certain number of messages across all buffers
 401     /** \param first    if != -1 return only messages with a MsgId >= first
 402      *  \param last     if != -1 return only messages with a MsgId < last
 403      *  \param limit    Max amount of messages
 404      *  \return The requested list of messages
 405      */
 406     virtual QList<Message> requestAllMsgs(UserId user, MsgId first = -1, MsgId last = -1, int limit = -1) = 0;
 407
 408 signals:
 409     //! Sent when a new BufferInfo is created, or an existing one changed somehow.
 410     void bufferInfoUpdated(UserId user, const BufferInfo &);
 411     //! Sent when a Buffer was renamed
 412     void bufferRenamed(const QString &newName, const QString &oldName);
 413     //! Sent when a new user has been added
 414     void userAdded(UserId, const QString &username);
 415     //! Sent when a user has been renamed
 416     void userRenamed(UserId, const QString &newname);
 417     //! Sent when a user has been removed
 418     void userRemoved(UserId);
 419
 420 protected:
 421     QString hashPassword(const QString &password);
 422     bool checkHashedPassword(const UserId user, const QString &password, const QString &hashedPassword, const Storage::HashVersion version);
 423
 424 private:
 425     QString hashPasswordSha1(const QString &password);
 426     bool checkHashedPasswordSha1(const QString &password, const QString &hashedPassword);
 427
 428 #if QT_VERSION >= 0x050000
 429     QString hashPasswordSha2_512(const QString &password);
 430     bool checkHashedPasswordSha2_512(const QString &password, const QString &hashedPassword);
 431 #endif
 432 };
 433
 434
 435 #endif