File indexing completed on 2024-06-16 07:42:26

0001 /*
0002     SPDX-FileCopyrightText: 2005-2009 Sebastian Trueg <trueg@k3b.org>
0003     SPDX-FileCopyrightText: 1998-2009 Sebastian Trueg <trueg@k3b.org>
0004 
0005     SPDX-License-Identifier: GPL-2.0-or-later
0006 */
0007 
0008 
0009 #ifndef _K3B_MEDIA_CACHE_H_
0010 #define _K3B_MEDIA_CACHE_H_
0011 
0012 #include "k3b_export.h"
0013 
0014 #include "k3bdevice.h"
0015 #include "k3btoc.h"
0016 #include "k3bcdtext.h"
0017 #include "k3bdiskinfo.h"
0018 
0019 #include "k3bmedium.h"
0020 
0021 #include <QMutex>
0022 #include <QObject>
0023 #include <QThread>
0024 
0025 namespace K3b {
0026     namespace Device {
0027         class DeviceManager;
0028     }
0029 
0030 
0031     /**
0032      * The Media Cache does know the status of all devices at all times
0033      * (except for blocked devices).
0034      *
0035      * It should be used to get information about media and device status
0036      * instead of the libk3bdevice methods for faster access.
0037      *
0038      * The Media Cache polls for new information every 2 seconds on all devices
0039      * (except for blocked ones) and emits signals in case a device status changed
0040      * (for example a media was inserted or removed).
0041      *
0042      * To start the media caching call buildDeviceList().
0043      */
0044     class LIBK3B_EXPORT MediaCache : public QObject
0045     {
0046         Q_OBJECT
0047 
0048     public:
0049         explicit MediaCache( QObject* parent = 0 );
0050         ~MediaCache() override;
0051 
0052         /**
0053          * block a device so it will not be polled. This is used
0054          * to disable polling on devices that are currently in use
0055          * for burning.
0056          *
0057          * \return A unique id to be used to unblock the device or -1 if the device
0058          *         is already blocked.
0059          */
0060         int blockDevice( Device::Device* dev );
0061 
0062         /**
0063          * Unblock a device that has been blocked with block() before.
0064          *
0065          * \param id The id returned by the previous call to block(). This makes
0066          *           sure only the one who did the block may unblock the device.
0067          *
0068          * \return true if dev has been blocked with id before. false otherwise.
0069          */
0070         bool unblockDevice( Device::Device* dev, int id );
0071 
0072         bool isBlocked( Device::Device* dev );
0073 
0074         /**
0075          * Read cached medium information.
0076          */
0077         Medium medium( Device::Device* dev );
0078 
0079         /**
0080          * Read cached disk information.
0081          */
0082         Device::DiskInfo diskInfo( Device::Device* );
0083 
0084         /**
0085          * Read cached Table of contents.
0086          */
0087         Device::Toc toc( Device::Device* );
0088 
0089         /**
0090          * Read cached CD text from an Audio CD.
0091          */
0092         Device::CdText cdText( Device::Device* );
0093 
0094         /**
0095          * Read cached supported writing speeds.
0096          */
0097         QList<int> writingSpeeds( Device::Device* );
0098 
0099         /**
0100          * \see Medium::shortString()
0101          */
0102         QString mediumString( Device::Device* device, bool useContent = true );
0103 
0104     Q_SIGNALS:
0105         /**
0106          * Signal emitted whenever a medium changes. That means when a new medium is inserted
0107          * or an old one is removed.
0108          *
0109          * This signal will also be emitted when a previously blocked device becomes unblocked.
0110          *
0111          * Be aware though that the Media Cache will silently ignore removed devices. That means
0112          * one should also listen to Device::DeviceManager::changed() in case a USB drive or
0113          * something similar is removed.
0114          */
0115         void mediumChanged( K3b::Device::Device* dev );
0116 
0117         /**
0118          * Emitted when the cache analysis a new medium. This might be emitted multiple times
0119          * with different messages.
0120          *
0121          * \param dev The device being analysed.
0122          * \param message An optional message to display more details to the user.
0123          *
0124          * Analyzation of the medium is finished once mediumChanged has been emitted.
0125          */
0126         void checkingMedium( K3b::Device::Device* dev, const QString& message );
0127         
0128         /**
0129          * Emitted whenever medium CDDB information changes.
0130          */
0131         void mediumCddbChanged( K3b::Device::Device* dev );
0132 
0133     public Q_SLOTS:
0134         /**
0135          * Build the device list and start the polling.
0136          * It might make sense to connect this to Device::DeviceManager::changed()
0137          */
0138         void buildDeviceList( K3b::Device::DeviceManager* );
0139 
0140         /**
0141          * Clear the device list and stop all the polling.
0142          * This is also done in the destructor.
0143          */
0144         void clearDeviceList();
0145 
0146         /**
0147          * Perform a new cddb query to update the information. This may be useful
0148          * to let the user select a different entry in case of a multiple entry result
0149          * or to re-query after enabling a new cddb source.
0150          *
0151          * Will result in a mediumChanged signal for media that have audio content.
0152          */
0153         void lookupCddb( K3b::Device::Device* );
0154 
0155         /**
0156          * Reset a device, i.e. force an update of the device.
0157          *
0158          * This is useful to ensure that after an eject the cache is still valid.
0159          */
0160         void resetDevice( K3b::Device::Device* );
0161 
0162     private:
0163         class PollThread;
0164         class DeviceEntry;
0165 
0166         class Private;
0167         Private* const d;
0168 
0169         DeviceEntry* findDeviceEntry( Device::Device* );
0170 
0171         Q_PRIVATE_SLOT( d, void _k_mediumChanged( K3b::Device::Device* ) )
0172         Q_PRIVATE_SLOT( d, void _k_cddbJobFinished( KJob* job ) )
0173     };
0174 }
0175 
0176 #endif